World locking and spatial anchors in Unity
Getting your holograms to stay in place, move with you, or in some cases position themselves relative to other holograms is a big part of creating Mixed Reality applications. This article will take you through our recommended solution using World Locking Tools, but we'll also cover manually setting up spatial anchors in your Unity projects. Before we jump into any code, it's important to understand how Unity handles coordinate space and anchors in its own engine.
World-scale coordinate systems
Today, when writing games, data visualization apps, or virtual reality apps, the typical approach is to establish one absolute world coordinate system that all other coordinates can reliably map back to. In that environment, you can always find a stable transform that defines a relationship between any two objects in that world. If you didn't move those objects, their relative transforms would always remain the same. This kind of global coordinate system is easy to get right when rendering a purely virtual world where you know all of the geometry in advance. Room-scale VR apps today typically establish this kind of absolute room-scale coordinate system with its origin on the floor.
In contrast, an untethered mixed reality device such as HoloLens has a dynamic sensor-driven understanding of the world, continuously adjusting its knowledge over time of the user's surroundings as they walk many meters across an entire floor of a building. In a world-scale experience, if you placed all your holograms in a naive rigid coordinate system, those holograms would end up drifting over time, either based on the world or relative to each other.
For example, the headset may currently believe two locations in the world to be 4 meters apart, and then later refine that understanding, learning that the locations are in fact 3.9 meters apart. If those holograms had initially been placed 4 meters apart in a single rigid coordinate system, one of them would then always appear 0.1 meters off from the real world.
You can manually place spatial anchors in Unity to maintain a hologram's position in the physical world when the user is mobile. However, this sacrifices the self-consistency within the virtual world. Different anchors are constantly moving in relation to one another, and are also moving through the global coordinate space. In this scenario, simple tasks like layout become difficult. Physics simulation can also be problematic.
World Locking Tools (WLT) gets you the best of both worlds, stabilizing a single rigid coordinate system using an internal supply of spatial anchors spread throughout the virtual scene as the user moves around. WLT analyzes the coordinates of the camera and those spatial anchors every frame. Instead of changing the coordinates of everything in the world to compensate for the corrections in the coordinates of the user's head, WLT just fixes the head's coordinates instead.
Choose your world locking approach
If possible, use World Locking Tools for hologram positioning.
World Locking Tools provides a stable coordinate system that minimizes the visible inconsistencies between virtual and real world markers. World Locking Tools world-locks the entire scene with a shared pool of anchors, rather than locking each group of objects with the group's own individual anchor.
World Locking Tools automatically handles internal creation and management of spatial anchors. You don't need to interact with ARAnchorManager or WorldAnchor to keep your holograms world-locked.
- For Unity 2019/2020 using OpenXR or the Windows XR Plugin, use ARAnchorManager.
- For older Unity versions or WSA projects, use WorldAnchor.
Set up world locking
To get started using the World Locking Tools, download the Mixed Reality Feature Tool. To learn more about the basics, see the main World Locking Tools documentation page for links to Overview, Quickstart, and other useful topics.
When your project is ready to go, run the configure scene utility from Mixed Reality > World Locking Tools:
The Configure scene utility can be rerun at any time. For example, it should be rerun if the AR target has been changed from Legacy to XR SDK. If the scene is already properly configured, running the utility has no effect.
During early development, adding visualizers can be helpful to ensure WLT is setup and working properly. They can be removed for production performance, or if for any reason are no longer needed, using the Remove visualizers utility. More details on the visualizers can be found in the Tools documentation.
Persistent world locking
Spatial anchors save holograms in real-world space between application sessions. Once saved in the HoloLens anchor store, spatial anchors can be found and loaded in different sessions and are an ideal fallback when there's no internet connectivity.
Local anchors are stored on device, while Azure Spatial Anchors are stored in the cloud. You can have local and Azure anchors in the same project without conflict. For more information about integrating Azure cloud services to store your anchors, see Azure Spatial Anchors.
By default, World Locking Tools restore Unity's coordinate system relative to the physical world across sessions on devices that support persistence of local spatial anchors. To have a hologram appear in the same place in the physical world after quitting and rerunning the application, the application only needs to restore the same pose to the hologram.
If the application needs finer control, you can disable Auto-Save and Auto-Load in the inspector, and manage persistence from a script. For more information, see Persist spatial coordinate systems.
World Locking Tools supports local anchor persistence only on HoloLens devices. For Android, iOS, and HoloLens devices, integrate with Azure Spatial Anchors to support persistence and sharing of coordinate spaces across sessions and devices. For more information and samples using World Locking Tools with Azure Spatial Anchors, see World Locking Tools (WLT) combined with Azure Spatial Anchors (ASA).
Share a world locked coordinate space:
Learn about spatial mapping:
Go back to the Unity development checkpoints: