Skip to main content
Version: 20 Mar 2024

Immersal SDK

Immersal SDK is a spatial mapping & visual positioning system that allows you to merge digital content with the physical world by enabling devices to precisely locate themselves in the physical world. It is currently available for Unity and it supports Magic Leap 2 and a variety of other devices.

Features​

Immersal SDK brings immersive AR experiences and tools to large spaces.

The applications are limitless and range from AR games to ad campaigns, indoor navigation, maintenance tools for industries and more.

The main features of the Immersal SDK are:

  • Fast visual positioning with low system overhead.
  • Works both offline on-device and online in the cloud.
  • Android and iOS compatible.
  • REST API for SDK use with any device.
  • Capable of mapping large spaces, both indoor and outside.
  • Point clouds and detailed meshes of the mapped spaces available.
  • Supports multiple maps in the same space.
  • Easy-to-use Unity samples with templates for indoor navigation and more.
  • Detailed documentation to help developers get started.
  • Automatically combine multiple maps together with map stitching.
  • Continue updating older maps by restoring the map source data.

Getting Started​

The Immersal solution consists of 3 parts:

  1. Mapping real-world locations. The maps are constructed and hosted on Immersal's Cloud Service and can be captured using a ready-made Immersal Mapper app for iOS and Android. Maps can be created with the Magic Leap 2 device as well.
  2. Building applications that use these maps with the Immersal SDK.
  3. Localizing (finding the position and orientation in the map) end-user devices to show the persistent digital AR content to the end-user.

Prerequisites​

Before you can start with the project, you need to follow these steps:

  1. You first need to create an Immersal Developer account. You can register for a free account in the Immersal Developer Portal. The free license has capacity limitations, but you can use it even for commercial projects and it suits many use cases.

  2. Once you have an account, you need to map the area using the Immersal Mapper application which is available for both iOS Devices and Android devices. You can use the app with your free developer account. You can read about the mapping process in the Immersal documentation..

  3. Download the latest Immersal SDK Core .unitypackage from the Immersal Developer Portal and the Immersal Magic Leap 2 samples project from the Immersal Github repository. You will also need to download the Immersal Samples project separately from the Immersal SDK samples Github repository.

  4. Immersal SDK is supported on the Magic Leap 2 headset using the Magic Leap XR Plugin and the Magic Leap Unity SDK Package. You need to download and install Unity 2022 LTS version. Make sure to also install the Android module for Unity, as it is needed to build the project for Magic Leap 2. The Immersal Magic Leap 2 samples project is already configured and has all required packages and settings in place, apart from the Immersal SDK package and the Immersal Samples folder.

Starting the project​

Once you have all the requisites downloaded and installed, these are the steps you need to follow:

  1. Open the Immersal Magic Leap 2 samples project in Unity 2022 LTS version. There will be some errors when opening the sample project without the Immersal SDK Core, do not enter Safe Mode when prompted.

  2. Import the latest Immersal SDK Core .unitypackage into the sample project (Select Assets > Import Package > Custom Package. Then select the ImmersalSDK.unitypackage).

  3. Move the /Immersal Samples/ folder and it's contents from the Immersal SDK Samples project to the Immersal Magic Leap 2 Samples project, under the /Immersal/ folder. This will resolve all of errors in the Unity Console.

  4. Download and install the Magic Leap Hub.

  5. Open the ML Hub.

  6. Select the Package Manager tile from the ML Hub home screen.

  7. Navigate to the All tab in the Package Manager.

  8. Install or update the ML C SDK version (version 1.3.0) package, located under the Common Packages section.

  9. Install the Unity Package (version 1.9.0), located under the Unity Packages section.

  10. Press Apply Changes to complete the installation

Building the project​

When you are ready to build the project to the Magic Leap 2 headset, follow these steps:

  1. Connect your Magic Leap 2 headset to the computer you are building on. In Unity, navigate to the Build settings menu and make sure the target platform is Android. You should then see the Magic Leap 2 headset under the Run Devices.

  2. You can either use the Build & Run option in Unity to build the APK file of the project and run it on the device device automatically, or you can manually first build the APK file with the Build option and then navigate to the Device Bridge in the Magic Leap Hub where you can install the APK to the headset.

  3. When the APK is built on the Magic Leap 2 headset, you need to allow permissions when the app asks for them.

Troubleshooting​

If you have any questions or need help with troubleshooting, you can reach Immersal either through their Discord, the Immersal Developer Forum, or email.

Discord​

You can get help with Immersal SDK related problems through the Immersal Discord channel.

Email​

You can reach Immersal by email at sdk@immersal.com or through the Immersal website.

Immersal SDK Documentation​

You can also find more information on how to use the Immersal SDK from the Immersal SDK documentation.

Magic Leap Developer Forum​

You can also discuss Immersal SDK on the Magic Leap 2 Developer Forum.