Spatial Anchors
This section discusses how to use spatial anchors, a shared reference point for tethering virtual content to a persistent physical location.
Magic Leap 1 used the term PCF (Persistent Coordinate Frame) to describe our previous system of anchoring virtual content. Differences between PCFs and Spatial Anchors can be found on the Spatial Anchors Overview Page
Spatial anchors enable developers to create persistent and multi-user content. These anchors can be used to create shared experiences, such as multiplayer gaming, collaborative work, or interactive exhibits. You can create anchors inside your applications using Magic Leap's Spatial Anchors API. Once created, you can use the Spaces application to visualize all of the anchors that were created in your map.
If you are using Magic Leap's AR Cloud, anchors are shared between devices automatically. No additional networking is required to have the anchors appear across all connected devices.
Spatial Anchors
Modes of Operation
Spatial Anchor API supports two modes:
- On-Device Mode: Anchors are stored locally on the device and are available for multiple sessions within the same space of creation.
- AR Cloud Mode: Anchors are stored in the cloud and can be accessed from different devices in multiple sessions, provided the devices are localized to the same space where the anchors were published.
Properties of Spatial Anchors
Spatial anchors help maintain the position and orientation of digital content in the physical world over time. Each Spatial anchor has a unique ID, an expiration timestamp indicating its validity period, and a space ID signifying the space to which the anchor belongs.
Anchor Expiration Timestamp
When a new anchor is submitted to a map, its default expiration timestamp is 0. If left at this value, the system will keep the anchor indefinitely.
Managing Spatial Anchors
Through the API, you can create, publish, update, and delete anchors based on the requirements of your application. You can also query for existing anchors using criteria such as the center point of a spatial query, a radius for the spatial query, or a list of anchor IDs.
Spaces
Localization is a process by which the Magic Leap 2 device identifies its position in a space. Before localizing, Magic Leap 2 requires users to map the location and save it as a Space using the Spaces application. When Magic Leap 2 successfully localizes into a Space, it attempts to localize into it anytime a new session starts, even across reboots. If you consistently use your device at the same location, your device recognizes and localizes into the Space automatically, without manual selection.
Additionally it is possible to programmatically request localization using MLSpaces API. Sometimes localization fails. Reasons for failure include:
- Unknown
- The user is outside of the mapped area
- There aren't enough features in the environment to localize
- Excessive motion
- Lighting levels are too low in the environment
- A headpose failure caused localization to be unsuccessful
- Internal algorithm failure that prevented localization
Mapping
Mapping is a necessary process for device recognition and interaction with the surrounding space. Before localizing into a space you need to map the location and save it locally or to ARCloud. Currently, mapping can only be performed inside the Spaces application.
Updating Spaces
Unlike localization, Spaces don't update automatically. If you want to update a Space or add additional information, you will need perform the remapping step explicitly inside the Spaces application. This workflow insures that the device will be able to localize into your space efficiently.
Currently, on device maps do not support mergeing or updating existing maps. Instead, you will need to delete and remap the space.
Localize into a Specific Space
Developers can use the MLSpace API to localize into a specific space without leaving their application.
Localization Updates
Localization data on the device is updated every 10 seconds to correct for drift. This ensures that Spatial Anchors remain accurately placed in your location, even when head pose is lost or interrupted.
Additional Considerations
It's important to note that Magic Leap 2 doesn't support re-localizing to multiple maps simultaneously. The device only localizes into the space you've chosen.
If the user is not localized when launching your application, it's possible to send them to the Spaces application and start the mapping tool using Magic Leap's System Intents. This allows you to integrate the map tool as part of a start-up procedure for your application.