Core Package

Immersal SDK core functionality. Native plugins and C# scripts

The core package for Unity can be downloaded from the Developer Portal.

Core Overview

Contents of the core .unitypackage

Plugins

Immersal SDK plugin for Android, iOS, Windows, and macOS. The plugin is used for on-device localization, loading maps, and some coordinate system conversions.

Prefabs

ImmersalSDK prefab is the main controller for the Immersal SDK for Unity and contains several important settings. Your scene must include an instance of this.

Immersal SDK shown in the inspector panel

Developer Token You can paste your Developer Token here or you the Immesal SDK settings window to log in and retrieve the token automatically. The token is required for various REST API calls to the Cloud Service.

Target Frame Rate sets the target frame rate for Unity's AR Foundation.

Android Resolution sets the camera resolution for Android applications.

iOS resolution sets the camera resolution for iOS applications.

Downsample turn on downsampling for on-device localization. This is faster, but not quite as accurate as with full-resolution camera images.

On Pose Lost event is triggered when AR Foundation camera tracking is later lost after successful Immersal SDK localizations. This can be used, for example, to hide virtual content and display a notification to the user.

On Pose Found event is triggered when AR Foundation is tracking and Immersal SDK has successfully localized. This can be used, for example, to unhide virtual content and display them to the user.

Seconds to Decay Pose determines how many seconds should pass between successful localizations until TrackingQuality is decreased.

Resources

The minimum required resources and assets for the SDK. Currently only includes the point cloud shader for visualizing maps.

Editor Tools

Immersal SDK Settings

Access from the top menu Immersal SDK -> Open Settings Allows you to log in with your credentials and get your token in the Editor. Will automatically copy the token to the ImmersalSDK prefab if it exists.

AR Map Downloader

An automatic tool to download maps to your project. It will download the map metadata and map files and save them to disk in Assets/Map Data folder. it will then set up the maps in AR Map game objects in your scene.

  • Map ids CSV is a comma-separated values list for map ids to download

  • AR Space is a reference to an AR Space game object in the scene. AR Map from the input maps ids will be parented under this object. A new will be created if none is specified

  • Load Alignment (Experimental) will load alignment data from the map metadata. By default these are in the ECEF coordinate system and are not directly useable in Unity.

If you've overwritten the alignment map metadata with your own map alignments, you can use the AR Map Downloader to quickly and automatically set up maps in your scene

Scripts

Scripts that provide the basic functionalities required to build an AR application with Spatial Mapping and Visual Positioning capabilities.

AR Map

This is where the map data is loaded into and is what is used for Visual Positioning by the localizers.

When specifying a map file, the script will try to parse the Map ID and Map Name from the filename. Try not to rename your map files.

The AR Map has a couple of settings

  • Point Size controls the point size for the rendered point cloud

  • Render as 3D Points switched between 2D and 3D point rendering

  • Render Mode controls point cloud visibility

    • Do Not Render hides the point cloud

    • Editor Only render the point cloud in Unity Editor only

    • Editor And Runtime renders the point cloud in both the Unity Editor and the AR app

  • Map File specifies the .bytes map file used for Visual Positioning by the localizer

  • Point Color specifies the point cloud color for the AR Map

There are some read-only properties from the map metadata for debugging and preview

  • Map ID is the uneditable map id for the map

  • Map Name

  • Privacy is either private (0) or public (1)

  • Map Alignment is by default in ECEF coordinate system based on captured GPS coordinates

  • WGS84 lat/lon/alt based on captured GPS coordinates

There's an On First Localization event that's triggered when ARLocalizer localizes to this AR Map the first time. Useful for triggering content actions and animations.

There are functions to save, load, and reset the map alignment

  • Load Alignment loads the alignment from the map metadata on the Cloud Service

  • Save Alignment saves the alignment to map metadata on the Cloud Service

  • Reset Alignment reloads the originally captured alignment from map metadata on the Cloud Service

The default captured alignment is in global ECEF coordinates with very large values. These are not useful as is inside Unity but you can overwrite the alignment however you want to.

The metadata is stored in a right-handed coordinate system on the Cloud Service. Conversion to Unity's left-handed coordinate system is done on Loading/Saving.

AR Space

The transform space for AR Maps and virtual content. When localizing, the AR Space is what gets moved around in Unity's World Space to match what the camera sees.

AR Localizer

An AR Foundation specific localizer implementation which inherits common features from the LocalizerBase.cs class.

Usually together with the ImmersalSDK component. It has the settings related to Visual Positioning.

ImmersalSDK

Acts as a manager and controller for global Immersal SDK settings and functions. More information above in Prefabs section