Skip to main content
Version: 20 Mar 2024

Localization Map Overview

The Magic Leap OpenXR Localization Map Feature allows developers to manage Spaces inside their application. This includes functionality such as querying a list of spaces, requesting localization into a specific Space and importing/exporting on device Spaces.

A Magic Leap Space is a container that holds metadata about your scanned environment. It is a digital copy of a physical place and could include spatial anchors, environment meshes, environment objects, etc. Spaces can be created on device or in the Magic Leap AR Cloud. Spaces created in the AR Cloud can be easily shared between other devices.

caution

Some functions require the com.magicleap.permission.SPACE_IMPORT_EXPORT permission to be requested at runtime and enabled in your project's Manifest Settings (Edit > Project Settings > Magic Leap > Manifest Settings).

caution

This feature requires the Magic Leap 2 Localization Maps OpenXR Feature to be enabled in your project's OpenXR Settings (Window > XR Plugin Manager > OpenXR Settings).

Key Features​

Localization Requests: The Magic Leap Space API enables applications to query the list of Spaces available and discern the Space for device localization. To list the Spaces and initiate localization, the application needs to create a Space Manager. However, only one manager instance can be created per application and this API is not thread safe.

Importing and Exporting Spaces: Magic Leap Space API supports exporting and importing on device Spaces. Applications cannot export AR Cloud spaces. Applications will need additional permissions to import/export spaces: com.magicleap.permission.SPACE_IMPORT_EXPORT (protection level: dangerous). The format of the exported Space data can change with OS version updates.

Backwards compatibility: Space exported using OS version n should work on OS versions up to and including OS version n-4. Forwards compatibility: Space exported using OS version n is not guaranteed to work on OS versions > n. Developers are strongly encouraged to encrypt the exported Magic Leap Spaces.

Localization Map Structures​

The MLSpace API provides several structures that help you manage and interact with your Spaces, including:

  • MagicLeapLocalizationMapFeature.LocalizationMap: Information about a Magic Leap Space.
  • MagicLeapLocalizationMapFeature.LocalizationEventData: Information about the device's localization state.

Localization Map Enums​

There are two enumeration types used in the MLSpace API:

  • MagicLeapLocalizationMapFeature.LocalizationMapType: Indicates the type of the Space (OnDevice or ARCloud).
  • MagicLeapLocalizationMapFeature.LocalizationMapState: Denotes the current localization status of the device (NotLocalized, Localized, LocalizationPending, or SleepingBeforeRetry).
  • MagicLeapLocalizationMapFeature.LocalizationMapConfidence: Describes the current localization confidence of the device (Poor, Fair, Good, or Excellent).

Please refer to the specific APIs for further details on how to utilize them in your application development.

📄️ API Overview

This guide provides a comprehensive overview of the MLSpace API, specifically focusing on the key features and functions used to manage MLSpaces in your applications. It covers topics such as subscribing to the OnLocalizationEvent to monitor localization status changes, fetching available spaces, understanding and getting localization results, localizing into a specific space, and the export and import of spaces. Each topic is explored with detailed explanations and illustrative code snippets, aiming to provide a clear understanding of how to leverage the MLSpace API effectively. The guide offers insights into the usage of key structs, values, and enums, enhancing your ability to create more interactive and responsive applications using MLSpaces.

📄️ Localization Map Examples

These scripts demonstrate various functionalities of the OpenXR Localization Map Feature, which is used for managing spaces in a mixed reality environment. The scripts are broken down into specific functionalities: requesting permissions, retrieving available spaces, localizing into a space, exporting and saving spaces, and importing previously saved spaces. Each script serves as an isolated example of a particular functionality, making it easier to understand and implement these functions in your own projects. They are designed to be used with the Unity game engine and the Magic Leap platform. Note that they should be used in a real device environment for proper functioning.