Comment on page
Mapping Example Scene
The Mapping Example scene is a part of an SDK that provides an interactive demonstration of working with Spatial Anchors. The experience enables users to create, place, save, and reload anchors within the augmented reality environment.
To access the "MappingExample" scene, follow these steps:
- 1.After importing the SDK package into your Unity project, navigate to the "Scenes" folder in the Project window.
- 2.Locate and open the "MappingExample" scene.
- 3.Explore the scene hierarchy and components to understand how the
AnchorItemscript is used.
- 4.Run the scene in the Unity Editor or build it for your device to see the Spatial Anchor functionality in action.
LocalMapExampleclass is responsible for handling world anchors in the local map. It provides functionalities for loading, saving, destroying, and adding anchors. The class also includes methods to control anchor panels and manage user interactions with anchors.
m_NRWorldAnchorStore: Represents the NR world anchor store.
m_AnchorPanel: A transform for controlling the anchor panel's visibility.
target: Holds the target transform for the anchor item.
m_AnchorPrefabDict: A dictionary to store and manage anchor prefabs.
- Initializes the anchor items and the NR world anchor store.
- Associates anchor items with their keys.
- Disables the anchor panel initially and sets trackable anchor enabled for native configurations.
- Listens for the trigger button press on the controller and calls the
AddAnchormethod if a target is set.
- Toggles the visibility of the anchor panel.
OnAnchorItemClick(string key, GameObject anchorItem)
- Handles anchor item clicks and configures the target according to the clicked anchor item.
- Loads all anchors from the
NRWorldAnchorStore, reinstantiating them in the scene.
- Saves all anchors to the
- Destroys the
NRWorldAnchorStore, removing all anchors from memory.
- Instantiates a new anchor based on the current target.
After entering the MappingExample scene, users can click the
OpenAnchorPanelbutton to reveal the Anchor panel.
Three Anchor options will appear. Users can select any of these anchors using a hand-held controller and then position the anchor in a specific location within the real world.
Before saving the anchor, users should pause and scan the surrounding area with the headset's camera. This step ensures that sufficient feature points are collected, enhancing the stability and accuracy of the anchor.
Once sufficient feature points have been gathered, users can click
Save. Successful saving turns the anchor green, signaling that it has been anchored to that location in the real world.
Users may exit the application and reopen it at any time.
After reopening the application, clicking
Loadwill reload the previously saved anchor. By returning to the physical location where the anchor was originally placed, users can observe the anchor successfully loading back into the scene.
AnchorItemclass represents individual anchor items. It provides functionalities for saving, erasing, destroying, and managing the visual appearance of anchors.
key: Represents the key associated with the anchor item. This key must be unique for each spatial anchor. If two spatial anchors have the same key, it may cause unexpected behavior or bugs.
OnAnchorItemClick: An action event for handling anchor item clicks.
canvas: Associated canvas object for display.
anchorUUID: The UUID text associated with the anchor.
m_NRWorldAnchor: The associated NR world anchor.
m_Material: The material for visual representation of tracking state.
Initializes the NR world anchor and sets up tracking state color indicators.
Saves the anchor to the NR world anchor store.
Erases the anchor from the NR world anchor store.
Destroys the NR world anchor object.
Handles pointer clicks on the anchor item and invokes the
NRWorldAnchorStoreclass manages the storage, creation, and retrieval of spatial anchors, known as
NRWorldAnchor, within an application. It provides a unified interface for handling anchors, including tracking their states, saving them to persistent storage, and retrieving them as required.
The class is highly tailored to work with the underlying native mapping system and the Unity editor, as seen by the conditional compilation directives. It manages the anchors' lifecycle, ensures their persistence across sessions, and facilitates their efficient retrieval and updates.
- m_NativeMapping: The native interface for mapping operations.
- m_AnchorDict: A dictionary containing the anchors, indexed by unique 64-bit identifiers.
- m_Anchor2ObjectDict: A dictionary mapping anchor UUIDs to user-defined keys.
- Instance: A singleton instance of the NRWorldAnchorStore.
- MapFolder: The constant folder name where the anchor maps are stored.
- MapPath: The absolute path to the anchor maps folder.
- Anchor2ObjectFile: The constant filename for anchor-to-object mapping.
Initializes the NRWorldAnchorStore. It sets up the mapping path and reads existing anchors if any.
Cleans up the WorldAnchorStore and releases memory.
Executes the 'update' action for native mapping and tracking of anchors.
CreateAnchor(NRWorldAnchor anchor): bool
Creates an NRWorldAnchor and returns true if successful.
BindAnchor(NRWorldAnchor anchor, UInt64 handle)
Binds a specified anchor with a given handle.
SaveAnchor(NRWorldAnchor anchor): bool
Saves the provided NRWorldAnchor with the UserDefinedKey. Returns true if successful.
Saves all NRWorldAnchor and returns true.
DestroyAnchor(NRWorldAnchor anchor): bool
Destroys a specified NRWorldAnchor from the store and returns true if successful.
Clears all NRWorldAnchors.
EraseAnchor(NRWorldAnchor anchor): bool
Erases a specified NRWorldAnchor from disk and returns true if successful.
LoadwithUUID(string uuid, Action<UInt64> action)
Loads a NRWorldAnchor from disk for the given identifier and executes the provided action if successful.
GetLoadableAnchorUUID(): Dictionary<string, string>
Returns a dictionary of UUIDs and user-defined keys that can be loaded.
MappingExample, special care is required when loading previously saved Spatial Anchors in the subsequent Session. The Anchor to be loaded (referred to as
AnchorItemin the example) must exist in the scene, and its key value must be consistent with the key value at the time of saving. Even though the active state of the AnchorItem should be false, or the GameObject placed at a great distance beyond the Camera's display range to ensure it is not visible, it is essential that the AnchorItem be present in the scene.
The logic behind this requirement lies within
LocalMapExample.cs. During scene initialization, the method
FindObjectsOfType<AnchorItem>()is employed to find all
AnchorItemobjects within the scene and assign them to
m_AnchorPrefabDict. This dictionary is further utilized to reinstantiate the actual
AnchorItemobjects appearing in the scene.
Here's a part of the code that demonstrates this:
private void Start()
var anchorItems = FindObjectsOfType<AnchorItem>();
foreach (var item in anchorItems)
item.OnAnchorItemClick += OnAnchorItemClick;