Skip to main content

Spatial Anchors

Build Spectacles experiences where virtual content stays locked to real-world locations and persists across sessions using Spatial Anchors.

  • Snapchat: not supported
  • SPECS: fully supported
  • Camera Kit Web: not supported
  • Camera Kit Mobile: not supported
  • SnapchatNot supported
  • SPECSFully supported
  • Camera Kit WebNot supported
  • Camera Kit MobileNot supported

Platform details

  • Snapchat — Not supported.

  • SPECS — Fully supported.

  • Camera Kit Web — Not supported.

  • Camera Kit Mobile — Not supported.

Overview

Anchors in augmented reality enable the creation of immersive experiences by allowing users to seamlessly integrate virtual content with the real world. These anchors serve as fixed points that ensure digital elements remain in place as users move around their environment.

For example, an instructional Lens can place permanent step-by-step guides directly on household appliances. Each guide stays fixed to its appliance and is there every time the user comes back, so they can operate the appliance without consulting a manual. Similarly, users can pin notes and reminders around their home that stay exactly where they left them across sessions.

The Anchors API is built into Lens Studio, so you don't need to install a package to use it. The AnchorModule is the entry point to the overall anchoring system, and the first anchor type is WorldAnchor.

The Anchors API is available only on SPECS.

WorldAnchor is currently the only supported anchor type, and more types will be added in future releases.

Getting Started

What You'll Build

The following sections build one script, AnchorPlacementController, step by step. The completed example attaches one object to each anchor and looks like this:

Prerequisites

  • Lens Studio: v5.25+ (Lens Scripting 376+ for the native AnchorModule)
  • SPECS OS: v7.0+
  • SPECS App iOS: v1.7+
  • SPECS App Android: v1.7+

Project Setup

Create a new project from the SPECS base template: in the Lens Studio home, select Spectacles > Base Template. The template's camera is already set up for anchors, with a Device Tracking component set to World mode.

Accessing the AnchorModule

Create a new script named AnchorPlacementController. We'll build on it throughout this guide. Get the AnchorModule in your script with require.

@component
export class AnchorPlacementController extends BaseScriptComponent {
private anchorModule: AnchorModule = require('LensStudio:AnchorModule');
}

Starting an AnchorSession

The next step is to open an AnchorSession, which lets you create, save, delete, and detect saved anchors near the user. Using the anchorModule from the previous step, call openSession().

In this example, we set up the onAnchorNearby callback so it runs whenever a previously saved anchor is found nearby. We haven't saved any anchors yet, so none will be found.

@component
export class AnchorPlacementController extends BaseScriptComponent {
private anchorModule: AnchorModule = require('LensStudio:AnchorModule');
private anchorSession?: AnchorModule.AnchorSession;

onAwake() {
this.createEvent('OnStartEvent').bind(() => {
this.onStart();
});
}

async onStart() {
// Open a session to start working with anchors
this.anchorSession = await this.anchorModule.openSession();

// Listen for saved anchors found nearby
this.anchorSession.onAnchorNearby.add((anchor) =>
this.onAnchorNearby(anchor)
);
}

private onAnchorNearby(anchor: AnchorModule.Anchor) {
// Invoked when a saved anchor is found nearby
}
}

Anchor Session Options (Optional)

openSession() works without any options. You can also open a session with an area by setting area in AnchorSessionOptions to a name you choose, such as 'living-room'. For when to use an area, see Area.

const options = new AnchorModule.AnchorSessionOptions();
options.area = 'living-room';

this.anchorSession = await this.anchorModule.openSession(options);
  • Anchors you create in a session with an area belong to that area.
  • Anchors you create in a session without an area belong to no area.
  • A session without an area finds all the Lens's saved anchors, including the ones that belong to an area.

Placing an Anchor

To place an anchor, pass its world-space pose as a mat4 to createWorldAnchor(). In this example, the pose is 100 cm in front of the user, and the user anchors a 3D object there by pinching a button. To create the button, install UI Kit and add a button to your scene. You can choose the button's shape and style in the Inspector. When the button is pinched, the script creates a WorldAnchor, attaches an object to it, and calls saveAnchor() so the anchor is found again in future sessions.

Also add an empty SceneObject to your scene and assign it to the anchorsRoot input. The script puts every anchor object under it, so later examples can find the anchor objects and remove them all at once.

Building on the example above:

import { Button } from 'SpectaclesUIKit.lspkg/Scripts/Components/Button/Button';

@component
export class AnchorPlacementController extends BaseScriptComponent {
@input createAnchorButton: Button;
@input camera: SceneObject;
@input prefab: ObjectPrefab;
@input anchorsRoot: SceneObject;

private anchorModule: AnchorModule = require('LensStudio:AnchorModule');
private anchorSession?: AnchorModule.AnchorSession;

onAwake() {
this.createEvent('OnStartEvent').bind(() => {
this.onStart();
});
}

async onStart() {
this.createAnchorButton.onTriggerUp.add(() => {
this.createAnchor();
});

// Open a session to start working with anchors
this.anchorSession = await this.anchorModule.openSession();

// Listen for saved anchors found nearby
this.anchorSession.onAnchorNearby.add((anchor) =>
this.onAnchorNearby(anchor)
);
}

private onAnchorNearby(anchor: AnchorModule.Anchor) {
// Invoked when a saved anchor is found nearby
}

private async createAnchor() {
if (!this.anchorSession) {
return;
}

// Compute the anchor pose 100 cm in front of the user
const toWorldFromDevice = this.camera.getTransform().getWorldTransform();
const anchorPose = toWorldFromDevice.mult(
mat4.fromTranslation(new vec3(0, 0, -100))
);

// Create the anchor
const anchor = await this.anchorSession.createWorldAnchor(anchorPose);

// Create the object and attach it to the anchor
this.attachNewObjectToAnchor(anchor);

// Save the anchor so it's found again in future sessions
try {
await this.anchorSession.saveAnchor(anchor);
} catch (error) {
print('Error saving anchor: ' + error);
}
}

private attachNewObjectToAnchor(anchor: AnchorModule.Anchor) {
// Create a SceneObject for the anchor. Its transform is driven by the anchor.
const anchorObject = global.scene.createSceneObject('Anchor Object');
anchorObject.setParent(this.anchorsRoot);

// Add an AnchorComponent and set its anchor to start tracking
const anchorComponent = anchorObject.createComponent(
'Component.AnchorComponent'
);
anchorComponent.anchor = anchor;

// Create the content from the prefab as a child of the anchor object
this.prefab.instantiate(anchorObject);
}
}

In the code above, pinching the button calls createAnchor, which creates a new anchor 100 cm in front of the user, attaches content to it, and saves the anchor. This example creates the content from a prefab, such as a 3D model. The following examples use a Snapchat ghost model.

Before you run the Lens, select the SceneObject with the AnchorPlacementController script and set its inputs in the Inspector:

  • Create Anchor Button: the UI Kit button you added.
  • Camera: the SceneObject your camera is on. The script uses its position and rotation to place the anchor in front of the user.
  • Prefab: the prefab to place at each anchor.
  • Anchors Root: the empty SceneObject you added. The script puts every anchor object under it.

Put the AnchorComponent on its own SceneObject and add your content as a child of it, as attachNewObjectToAnchor does. The anchor controls the transform of the object it's attached to, so any position or rotation you set on that object is overwritten. With the content on a child object, you can move, rotate, or replace it relative to the anchor.

This guide creates one anchor for each object. You can also attach several objects close together to one anchor and place each one relative to it, which can improve stability and performance. For the best stability, keep each object within about 3 m of its anchor. See Attaching Several Objects to One Anchor.

Scanning for Anchors

Saved anchors are found again the next time the Lens runs. In the previous example, we saved each new anchor by calling saveAnchor(anchor). Because we added an onAnchorNearby callback to the AnchorSession, the next time the Lens runs, the callback is called for every saved anchor near the user once SPECS localizes it.

Only anchors are saved, not the content attached to them. To restore the objects you attached to an anchor in a previous session, recreate them when the anchor is found.

In onAnchorNearby, recreate the object for each anchor that's found by passing it to attachNewObjectToAnchor:

private onAnchorNearby(anchor: AnchorModule.Anchor) {
print('Anchor found: ' + anchor.id);

// Recreate the object for the saved anchor
this.attachNewObjectToAnchor(anchor);
}

Restoring an Anchor from a Persisted String ID

onAnchorNearby only reports saved anchors once the user is near them. To get an anchor back wherever the user is, or to restore only some anchors, save their id strings in persistent storage, so they're kept after the Lens closes. In a later session, pass each one to resolveAnchor() on the AnchorSession. Like onAnchorNearby, resolving returns only the anchor, not its content, so you still need to recreate the content.

resolveAnchor() fails if the id does not represent a valid AnchorId owned by the Lens.

The following example restores the last placed anchor when the Lens starts:

  • In createAnchor, when a new anchor is saved, the script also stores the latest anchor's id in persistent storage. Anchors that aren't saved don't persist across sessions, so this happens only after saveAnchor() succeeds.
  • After opening the session, onStart calls restoreLastAnchor, which resolves the stored id and recreates the content with attachNewObjectToAnchor. If resolving fails, it removes the id from persistent storage.
  • onAnchorNearby also reports the resolved anchor when the user is near it. To avoid creating its content twice, restoreLastAnchor and onAnchorNearby both check first that the anchor doesn't already have an anchor object under anchorsRoot.

In the following video, the onAnchorNearby listener is turned off, so only the last placed anchor comes back, through resolveAnchor(). With the listener on, every other saved anchor near the user comes back too.

// At the top of the file, outside the class.
// The id of the last placed anchor is stored under this key.
const LAST_ANCHOR_KEY = 'lastAnchorId';

// In the class:
private store = global.persistentStorageSystem.store;

// In onStart, after listening for onAnchorNearby:
this.restoreLastAnchor();

// In createAnchor, remember the anchor as the last placed one right after saving it.
// If saveAnchor() fails, the catch runs instead, so no id is stored.
try {
await this.anchorSession.saveAnchor(anchor);
this.store.putString(LAST_ANCHOR_KEY, anchor.id);
} catch (error) {
print('Error saving anchor: ' + error);
}
// Turn the stored id back into an anchor and recreate its content
private async restoreLastAnchor() {
if (!this.anchorSession || !this.store.has(LAST_ANCHOR_KEY)) {
return;
}
const anchorId = this.store.getString(LAST_ANCHOR_KEY);

let anchor: AnchorModule.Anchor;
try {
anchor = await this.anchorSession.resolveAnchor(anchorId);
} catch (error) {
// The id is unknown or the anchor isn't accessible to this Lens, so forget it,
// unless a newer anchor was saved while it was being resolved
print('Error resolving anchor ' + anchorId + ': ' + error);
this.forgetLastAnchor(anchorId);
return;
}

// onAnchorNearby may have found this anchor while it was being resolved
if (this.findAnchorObject(anchor.id)) {
return;
}
this.attachNewObjectToAnchor(anchor);
}

private onAnchorNearby(anchor: AnchorModule.Anchor) {
print('Anchor found: ' + anchor.id);

// onAnchorNearby also reports resolved anchors, so skip the anchor if it already has content
if (this.findAnchorObject(anchor.id)) {
return;
}

// Recreate the object for the saved anchor
this.attachNewObjectToAnchor(anchor);
}

// Find the anchor object that's tracking an anchor, if any
private findAnchorObject(anchorId: string): SceneObject | null {
for (let i = 0; i < this.anchorsRoot.getChildrenCount(); i++) {
const anchorObject = this.anchorsRoot.getChild(i);
const anchorComponent = anchorObject.getComponent('Component.AnchorComponent');
if (
anchorComponent &&
anchorComponent.anchor &&
anchorComponent.anchor.id === anchorId
) {
return anchorObject;
}
}
return null;
}

In Lifecycle of Tracking State, attachNewObjectToAnchor hides the content until the anchor is Tracking, so a resolved anchor's content appears once SPECS localizes the anchor. The stored id also has to change when its anchor reaches Error, moves, or is deleted. Add a forgetLastAnchor helper for the cases where the id can no longer be resolved:

// Remove the stored id if it belongs to this anchor
private forgetLastAnchor(anchorId: string) {
if (
this.store.has(LAST_ANCHOR_KEY) &&
this.store.getString(LAST_ANCHOR_KEY) === anchorId
) {
this.store.remove(LAST_ANCHOR_KEY);
}
}

Lifecycle of Tracking State, Moving Anchors, and Deleting Anchors each show how to keep the stored id up to date.

Lifecycle of Tracking State

Assigning an anchor to an AnchorComponent doesn't make it usable right away. The anchor first loads (Initializing), then waits to be localized (Ready). It reaches Tracking once SPECS localizes it, meaning SPECS recognizes the surroundings where the anchor was saved and works out where the anchor is. Once localized, the anchor stays in place as the user moves around, even when it's out of view. Tracking can be lost if SPECS can no longer track the user's position, for example when the cameras are covered or the environment is too dark. AnchorComponent reports where the anchor is in this process through its state property and onStateChanged event.

StateMeaning
InitializingThe anchor is loading.
ReadyThe anchor is loaded but hasn't been localized in the user's surroundings yet.
TrackingThe anchor is localized and its pose is valid. Show your content.
LostThe anchor was localized but isn't anymore. Hide your content until it's tracking again. Anchors in a closed session stay Lost.
ErrorThe anchor can't be tracked, for example because it was deleted or failed to load. This state doesn't recover.

Assign the anchor, then add a listener to onStateChanged in the same function to respond to each state.

Building on the example above, update attachNewObjectToAnchor to handle each state:

  • Initializing and Ready: the content stays hidden, since the anchor hasn't been localized yet.
  • Tracking: the content is shown.
  • Lost: the content is hidden until tracking resumes.
  • Error: the anchor object and its content are destroyed, since the anchor won't be tracked again. If you store the last anchor's id, as in Restoring an Anchor from a Persisted String ID, forgetLastAnchor also removes it, so the Lens doesn't try to resolve this anchor in a later session.

Every state except Tracking also prints a message you can use for debugging.

private attachNewObjectToAnchor(anchor: AnchorModule.Anchor) {
// Create a SceneObject for the anchor. Its transform is driven by the anchor.
const anchorObject = global.scene.createSceneObject('Anchor Object');
anchorObject.setParent(this.anchorsRoot);

// Create the content from the prefab as a child of the anchor object.
// Hide it until the anchor is tracking.
const content = this.prefab.instantiate(anchorObject);
content.enabled = false;

// Add an AnchorComponent and set its anchor to start tracking
const anchorComponent = anchorObject.createComponent('Component.AnchorComponent');
anchorComponent.anchor = anchor;

// Listen for tracking state changes
anchorComponent.onStateChanged.add((state) => {
switch (state) {
case AnchorModule.AnchorTrackingState.Initializing:
print('Anchor initializing: ' + anchorComponent.anchor.id);
break;
case AnchorModule.AnchorTrackingState.Ready:
print('Anchor ready, waiting to localize: ' + anchorComponent.anchor.id);
break;
case AnchorModule.AnchorTrackingState.Tracking:
// The pose is valid, so show the content
content.enabled = true;
break;
case AnchorModule.AnchorTrackingState.Lost:
// Hide the content until tracking resumes. You can also show a hint,
// such as asking the user to uncover the cameras or find more light.
content.enabled = false;
print('Anchor lost: ' + anchorComponent.anchor.id);
break;
case AnchorModule.AnchorTrackingState.Error:
// Error doesn't recover, so remove the anchor object and its content
print('Anchor can no longer be tracked: ' + anchorComponent.anchor.id);
// Forget the stored id too, as in Restoring an Anchor from a Persisted String ID.
// Use the component's current anchor, since moving replaces it with a new id.
this.forgetLastAnchor(anchorComponent.anchor.id);
anchorObject.destroy();
break;
}
});
}

Hide the content child, not the anchor object. Disabling the anchor object can stop the AnchorComponent from tracking, so the content would never reappear.

Waiting for a New Anchor to Track

A new anchor takes a moment to start tracking. If the user presses the button repeatedly during that time, creating anchors can get stuck. To prevent this, block repeated presses while an anchor is still starting up, and allow them again once it has settled:

  • An isCreating flag is set when createAnchor starts creating an anchor. While it's set, new presses are ignored.
  • attachNewObjectToAnchor takes an optional onSettled callback. It runs once, when the anchor first reaches Tracking, Lost, or Error, and clears the flag.
  • If the anchor doesn't settle within 5 seconds, for example because it stays Initializing or Ready in poor lighting, a timeout clears the flag so the user can try again.
  • If createWorldAnchor fails, the flag is cleared right away.

The highlighted lines are the changes to createAnchor from Placing an Anchor and to attachNewObjectToAnchor from Lifecycle of Tracking State:

// True from when a new anchor is requested until it settles
private isCreating = false;

private async createAnchor() {
if (!this.anchorSession) {
return;
}
// Block repeated presses while the previous anchor is still starting up
if (this.isCreating) {
print('Still placing the previous anchor');
return;
}

// Compute the anchor pose 100 cm in front of the user
const toWorldFromDevice = this.camera.getTransform().getWorldTransform();
const anchorPose = toWorldFromDevice.mult(
mat4.fromTranslation(new vec3(0, 0, -100))
);

// Create the anchor. Block new presses until it settles.
this.isCreating = true;
let anchor: AnchorModule.Anchor;
try {
anchor = await this.anchorSession.createWorldAnchor(anchorPose);
} catch (error) {
// Creating failed, so allow new presses again
print('Error creating anchor: ' + error);
this.isCreating = false;
return;
}

// Allow new presses once the anchor settles or the timeout runs out,
// whichever comes first
let settled = false;
const settle = () => {
if (settled) {
return;
}
settled = true;
this.isCreating = false;
};

// Create the object and attach it to the anchor
this.attachNewObjectToAnchor(anchor, settle);

// If the anchor doesn't settle within 5 seconds, allow new presses anyway
const timeout = this.createEvent('DelayedCallbackEvent');
timeout.bind(() => {
// The timeout only fires once, so remove its event from the script
this.removeEvent(timeout);
if (!settled) {
print('Anchor did not start tracking in time, allowing new placements');
}
settle();
});
timeout.reset(5);

// Save the anchor so it's found again in future sessions
try {
await this.anchorSession.saveAnchor(anchor);
} catch (error) {
print('Error saving anchor: ' + error);
}
}

// onSettled runs once, when the anchor first reaches Tracking, Lost, or Error
private attachNewObjectToAnchor(
anchor: AnchorModule.Anchor,
onSettled?: () => void
) {
// Create the anchor object, content, and AnchorComponent, as above

// Listen for tracking state changes
anchorComponent.onStateChanged.add((state) => {
if (
onSettled &&
(state === AnchorModule.AnchorTrackingState.Tracking ||
state === AnchorModule.AnchorTrackingState.Lost ||
state === AnchorModule.AnchorTrackingState.Error)
) {
onSettled();
onSettled = undefined;
}

// Handle each state with the switch statement, as above
});
}

The settled check makes sure the flag is only cleared once for each anchor. Without it, a timeout from an earlier anchor could clear the flag while a newer anchor is still starting up.

onAnchorNearby and restoreLastAnchor call attachNewObjectToAnchor without onSettled, since restoring a saved anchor doesn't need to block new presses.

Moving Anchors

An anchor's pose can't be changed after it's created. To move an anchor, create a new anchor at the new pose, save it, and then delete the old one. Building on the earlier examples, the user can now grab the anchored content and drag it to a new spot. When they let go, the script:

  1. Creates a new anchor at the content's new pose and saves it.
  2. Moves the anchor object to the new pose and re-centers the content on it.
  3. Sets the AnchorComponent to track the new anchor.
  4. Updates the stored id to the new anchor's id.
  5. Deletes the old anchor.

If saving the new anchor fails, the script discards it and snaps the content back, so the original anchor stays in place.

Set Up the Prefab

To let users grab and move the content, add these components to the root SceneObject of your prefab:

  • Physics Collider: defines the area the user can grab. Fit its shape to your content.
  • Interactable: lets the content respond to hand input.
  • InteractableManipulation: lets the user move and rotate the content. Turn off scaling, since an anchor's pose doesn't include scale.

Interactable and InteractableManipulation come from Spectacles Interaction Kit, which is installed with Spectacles UI Kit.

Move the Anchor When the User Releases the Content

In attachNewObjectToAnchor, listen for onManipulationEnd on the content, then move the anchor to the content's new pose:

import { InteractableManipulation } from 'SpectaclesInteractionKit.lspkg/Components/Interaction/InteractableManipulation/InteractableManipulation';

// In attachNewObjectToAnchor, after creating the content:
const manipulation = content.getComponent(
InteractableManipulation.getTypeName()
) as InteractableManipulation;

if (manipulation) {
// Move the anchor when the user releases the content
manipulation.onManipulationEnd.add(() => {
this.moveAnchor(anchorComponent, content);
});
} else {
print("Prefab has no InteractableManipulation, so it can't be moved");
}
private isMoving = false;

private async moveAnchor(anchorComponent: AnchorComponent, content: SceneObject) {
const contentTransform = content.getTransform();

// If another move is in progress or the anchor isn't tracking, skip the move
// and snap the content back to where it was before the drag
if (
!this.anchorSession ||
this.isMoving ||
anchorComponent.state !== AnchorModule.AnchorTrackingState.Tracking
) {
this.recenter(contentTransform);
return;
}
this.isMoving = true;

try {
const oldAnchor = anchorComponent.anchor;

// Build the new pose from where the user released the content
const newPose = mat4.compose(
contentTransform.getWorldPosition(),
contentTransform.getWorldRotation(),
vec3.one()
);

// Create the new anchor and save it before touching the old one
const newAnchor = await this.anchorSession.createWorldAnchor(newPose);
try {
await this.anchorSession.saveAnchor(newAnchor);
} catch (error) {
// Saving failed: snap the content back and discard the new anchor
print('Error moving anchor: ' + error);
this.recenter(contentTransform);
await this.anchorSession.deleteAnchor(newAnchor);
return;
}

// Move the anchor object to the new pose, re-center the content on it,
// then track the new anchor
anchorComponent.getSceneObject().getTransform().setWorldTransform(newPose);
this.recenter(contentTransform);
anchorComponent.anchor = newAnchor;

// If you store the last anchor's id, as in
// Restoring an Anchor from a Persisted String ID, update it
// so it points at the new anchor
if (
this.store.has(LAST_ANCHOR_KEY) &&
this.store.getString(LAST_ANCHOR_KEY) === oldAnchor.id
) {
this.store.putString(LAST_ANCHOR_KEY, newAnchor.id);
}

// Delete the old anchor. The move already succeeded, so only log a failure here.
try {
await this.anchorSession.deleteAnchor(oldAnchor);
} catch (error) {
print('Error deleting old anchor: ' + error);
}
} finally {
this.isMoving = false;
}
}

// Put the content back at the anchor object's origin
private recenter(contentTransform: Transform) {
contentTransform.setLocalPosition(vec3.zero());
contentTransform.setLocalRotation(quat.quatIdentity());
}

Save before you delete. saveAnchor() can fail if the system can't register an anchor at the new pose. Deleting the old anchor only after the new one is saved means a failed move leaves the original in place.

Re-center the content after the move. Dragging moves the content away from the anchor object. Once the anchor object moves to the new pose, reset the content's local position and rotation, or the drag offset is applied twice.

Update stored id values. Because a new anchor has to be created at the new pose, it gets a new id. If you store anchor id values yourself, replace the old id with the new one. Step 4 does this for the last anchor's id.

Deleting Anchors

When an anchor is no longer needed, delete it with deleteAnchor(anchor) so it isn't found again in later sessions, then destroy the SceneObjects attached to it. deleteAnchor() only removes the saved anchor: the SceneObject that holds the AnchorComponent, and the content under it, stay in the scene until you destroy them.

Deleting an Anchor

The following removeAnchor function deletes the anchor tracked by an AnchorComponent, then destroys the anchor object and its content. Call it when the user wants to remove an anchored object, for example from a button on the content.

private async removeAnchor(anchorComponent: AnchorComponent) {
if (!this.anchorSession) {
return;
}
const anchor = anchorComponent.anchor;
const anchorObject = anchorComponent.getSceneObject();

try {
await this.anchorSession.deleteAnchor(anchor);
} catch (error) {
// Deleting failed, so keep the anchor and its content
print('Error deleting anchor: ' + error);
return;
}

// If you store the last anchor's id, as in
// Restoring an Anchor from a Persisted String ID, remove it,
// since a deleted anchor can't be resolved
this.forgetLastAnchor(anchor.id);

// Destroy the anchor object and its content, unless the Error case in
// onStateChanged already destroyed it after the delete
if (!isNull(anchorObject)) {
anchorObject.destroy();
}
}

Clearing Anchors

To delete many anchors at once, call one of these AnchorSession methods. Both delete anchors permanently.

  • clearArea() deletes the anchors saved in the session's area and leaves anchors in other areas alone. The session must be opened with an area, or the call fails. To set an area, see Anchor Session Options. Use it to reset one space, such as the living room.
  • clearAllAnchors() deletes every anchor this Lens saved, in every area. It works whether or not the session was opened with an area. Use it to let the user start over.

Clear methods only delete the saved anchors. Your Lens is still responsible for destroying the SceneObjects that hold an AnchorComponent, and any content attached to them. Every anchor object is under anchorsRoot, as set up in Placing an Anchor, so you can destroy them all at once by destroying its children after clearing.

To set this up, add two UI Kit buttons, one to clear the current area and one to clear every anchor, and assign them to new clearAreaButton and clearAllButton inputs. Then register the buttons in onStart:

@input clearAreaButton: Button;
@input clearAllButton: Button;

// In onStart, next to createAnchorButton:
this.clearAreaButton.onTriggerUp.add(() => {
this.clearAreaAnchors();
});
this.clearAllButton.onTriggerUp.add(() => {
this.clearAllAnchors();
});

To delete only the anchors in the current area, call clearArea(). A session opened with an area only finds anchors in that area and saves new ones to it, so every anchor object under anchorsRoot belongs to the area, and the same cleanup applies:

private async clearAreaAnchors() {
// clearArea() needs a session opened with an area
if (!this.anchorSession || !this.anchorSession.area) {
print('The session has no area to clear');
return;
}

try {
await this.anchorSession.clearArea();
} catch (error) {
print('Error clearing area ' + this.anchorSession.area + ': ' + error);
return;
}

// Keep the stored id of the last anchor, since it might belong to another area.
// If it was in this area, restoreLastAnchor forgets it when resolving fails.

// Destroy every anchor object in this area, which also removes its content
for (let i = this.anchorsRoot.getChildrenCount() - 1; i >= 0; i--) {
this.anchorsRoot.getChild(i).destroy();
}
}

To delete every saved anchor and remove all anchored content, call clearAllAnchors():

private async clearAllAnchors() {
if (!this.anchorSession) {
return;
}

try {
await this.anchorSession.clearAllAnchors();
} catch (error) {
print('Error clearing anchors: ' + error);
return;
}

// If you store the last anchor's id, as in
// Restoring an Anchor from a Persisted String ID, remove it,
// since a cleared anchor can't be resolved
this.store.remove(LAST_ANCHOR_KEY);

// Destroy every anchor object, which also removes its content
for (let i = this.anchorsRoot.getChildrenCount() - 1; i >= 0; i--) {
this.anchorsRoot.getChild(i).destroy();
}
}

Additional Concepts

Attaching Several Objects to One Anchor

An anchor can hold more than one object. If your Lens creates several objects close together, or has objects that belong together, such as objects that move together, consider attaching them all to one anchor instead of creating an anchor for each. For the best stability, keep each object within about 3 m of its anchor. Each object is placed relative to the anchor, so it's restored and localized along with it. To restore objects in a later session, record each object's pose relative to the anchor.

In this example, the Snapchat ghost with a crown is the main object of its group. It sits where the anchor is, and dragging it moves the whole group. Every other ghost created within 1.5 m of the anchor is a sub object, which the user can move on its own. Its position and rotation are stored relative to the anchor.

The following example builds on the earlier one object per anchor example. Every object comes from one prefab, and the user can drag any of them. A new object created within 1.5 m of an existing anchor is attached to that anchor. Objects that share an anchor form a group:

  • The main object is the one with the crown. When the user lets go of it, the anchor moves to its new pose, as in Moving Anchors.
  • Sub objects stay in their group wherever the user drops them.

When the user creates a new object, the script decides which anchor it belongs to:

When the user…What happens
Creates the first object, or a new object more than 1.5 m from every tracking anchorThe script creates a new anchor, and the object becomes its main object.
Creates a new object within 1.5 m of a tracking anchorIt joins that anchor's group as a sub object.

Set Up the Prefab

Every object comes from the same prefab you set up in Moving Anchors. The only change is a new SceneObject that holds the crown mesh:

  • Physics Collider, Interactable, and InteractableManipulation are already on the prefab's root SceneObject from Moving Anchors, so every object can be dragged.
  • A first child SceneObject named Crown holds the crown mesh. A prefab with a visible crown is a main object, and the others, with hidden crowns, are sub objects.

The script builds this hierarchy at runtime. Sub objects are children of the main object, so they move with it when the user drags the main object. The script names each sub object Sub Object, so it can tell them apart from its main object:

Anchors Root
└─ Anchor Object ← AnchorComponent; its transform is driven by the anchor
└─ Prefab ← main object, crown shown
├─ Sub Object (Prefab) ← crown hidden
└─ Sub Object (Prefab) ← crown hidden
.
.
.

The example uses the prefab input from the earlier examples, and the anchorsRoot object from Placing an Anchor to find existing anchors.

Add Objects to a Nearby Anchor

In createAnchor, check for a nearby anchor before creating a new one. Each press is handled in this order:

  1. If a new anchor is still starting up, isCreating is true and the press is ignored. This is the guard from Waiting for a New Anchor to Track.
  2. Otherwise, findNearbyAnchor looks for a tracking anchor within 1.5 m. If it finds one, a sub object is added to its group. In this case, isCreating stays false, since no anchor is created.
  3. If there's no tracking anchor nearby, the script creates a new anchor with a main object. isCreating is true until the anchor first reaches Tracking, Lost, or Error, or until the 5-second timeout runs out. Then it's false again.

When tracking is poor, a press can still create a second anchor next to a new one that isn't tracking:

  • The 5-second timeout runs out first, so the user can press again before the new anchor is tracking.
  • The new anchor settles on Lost, so findNearbyAnchor can't find any tracking anchor nearby, and the press creates a new one.

The following code adds the nearby check to createAnchor:

// At the top of the file, outside the class.
// New objects created within this distance of a tracking anchor join its group.
const NEARBY_ANCHOR_RADIUS_CM = 150;

// The name of the prefab's first child, which holds the crown, and the name given to
// sub objects so they can be told apart from the crown
const CROWN_NAME = 'Crown';
const SUB_OBJECT_NAME = 'Sub Object';

// In createAnchor, after computing the pose and before setting isCreating:
const position = toWorldFromDevice.multiplyPoint(new vec3(0, 0, -100));

const nearby = this.findNearbyAnchor(position);
if (nearby) {
this.addSubObject(nearby, position);
return;
}

// Otherwise, create a new anchor with a main object, as before
// Find the closest tracking anchor within NEARBY_ANCHOR_RADIUS_CM of a position
private findNearbyAnchor(position: vec3): AnchorComponent | null {
let closest: AnchorComponent | null = null;
let closestDistance = NEARBY_ANCHOR_RADIUS_CM;

for (let i = 0; i < this.anchorsRoot.getChildrenCount(); i++) {
const anchorObject = this.anchorsRoot.getChild(i);
const anchorComponent = anchorObject.getComponent('Component.AnchorComponent');

// Only tracking anchors have a valid pose to measure from
if (
!anchorComponent ||
anchorComponent.state !== AnchorModule.AnchorTrackingState.Tracking
) {
continue;
}

const distance = anchorObject.getTransform().getWorldPosition().distance(position);
if (distance <= closestDistance) {
closest = anchorComponent;
closestDistance = distance;
}
}
return closest;
}

// Add a sub object to an anchor's group at a world position, and save the group
private addSubObject(anchorComponent: AnchorComponent, worldPosition: vec3) {
const main = this.getMainObject(anchorComponent);

// Store the position relative to the main object, so it's the same in every session
const position = main
.getTransform()
.getInvertedWorldTransform()
.multiplyPoint(worldPosition);
this.spawnSubObject(anchorComponent, position, quat.quatIdentity());
this.saveSubObjectPoses(anchorComponent);
}

// Create a sub object as a child of the main object, hide its crown, and let the
// user drag it on its own. It stays in this anchor's group wherever it's dropped.
private spawnSubObject(
anchorComponent: AnchorComponent,
position: vec3,
rotation: quat
) {
const sub = this.prefab.instantiate(this.getMainObject(anchorComponent));
sub.name = SUB_OBJECT_NAME;
this.setCrown(sub, false);
sub.getTransform().setLocalPosition(position);
sub.getTransform().setLocalRotation(rotation);

// Save the group when the user drops the sub object, so its new pose is restored
const manipulation = this.getManipulation(sub);
if (manipulation) {
manipulation.onManipulationEnd.add(() => {
this.saveSubObjectPoses(anchorComponent);
});
}
}
// Show the crown only on the main object, the one at the anchor's origin.
// The crown is the prefab's first child.
private setCrown(object: SceneObject, visible: boolean) {
const crown = object.getChildrenCount() > 0 ? object.getChild(0) : null;
if (crown && crown.name === CROWN_NAME) {
crown.enabled = visible;
} else {
print("Prefab's first child isn't named " + CROWN_NAME);
}
}

// The main object is the anchor object's only child
private getMainObject(anchorComponent: AnchorComponent): SceneObject {
return anchorComponent.getSceneObject().getChild(0);
}

// A main object's sub objects are its children named SUB_OBJECT_NAME
private getSubObjects(main: SceneObject): SceneObject[] {
const subs: SceneObject[] = [];
for (let i = 0; i < main.getChildrenCount(); i++) {
if (main.getChild(i).name === SUB_OBJECT_NAME) {
subs.push(main.getChild(i));
}
}
return subs;
}

private getManipulation(object: SceneObject): InteractableManipulation | null {
const manipulation = object.getComponent(
InteractableManipulation.getTypeName()
) as InteractableManipulation;
if (!manipulation) {
print("Prefab has no InteractableManipulation, so it can't be moved");
}
return manipulation;
}

Update attachNewObjectToAnchor from Lifecycle of Tracking State. The highlighted lines are the changes:

private attachNewObjectToAnchor(
anchor: AnchorModule.Anchor,
onSettled?: () => void
) {
// Create a SceneObject for the anchor. Its transform is driven by the anchor.
const anchorObject = global.scene.createSceneObject('Anchor Object');
anchorObject.setParent(this.anchorsRoot);

// Create the main object as the anchor object's only child, and show its crown.
// Hide it until the anchor is tracking. Its sub objects are hidden with it.
const main = this.prefab.instantiate(anchorObject);
this.setCrown(main, true);
main.enabled = false;

// Add an AnchorComponent and set its anchor to start tracking
const anchorComponent = anchorObject.createComponent('Component.AnchorComponent');
anchorComponent.anchor = anchor;

// Recreate the sub objects saved for this anchor, if any, as children of the
// main object, so they move with it.
// loadSubObjectPoses is defined in Save Sub Objects Across Sessions.
for (const pose of this.loadSubObjectPoses(anchor.id)) {
this.spawnSubObject(anchorComponent, pose.position, pose.rotation);
}

// Let the user drag the main object; the whole group moves with it,
// and the anchor moves on release
const manipulation = this.getManipulation(main);
if (manipulation) {
manipulation.onManipulationEnd.add(() => {
this.moveAnchor(anchorComponent, main);
});
}

// Listen for tracking state changes
anchorComponent.onStateChanged.add((state) => {
if (
onSettled &&
(state === AnchorModule.AnchorTrackingState.Tracking ||
state === AnchorModule.AnchorTrackingState.Lost ||
state === AnchorModule.AnchorTrackingState.Error)
) {
onSettled();
onSettled = undefined;
}

switch (state) {
case AnchorModule.AnchorTrackingState.Initializing:
print('Anchor initializing: ' + anchorComponent.anchor.id);
break;
case AnchorModule.AnchorTrackingState.Ready:
print('Anchor ready, waiting to localize: ' + anchorComponent.anchor.id);
break;
case AnchorModule.AnchorTrackingState.Tracking:
// The pose is valid, so show the main object and its sub objects
main.enabled = true;
break;
case AnchorModule.AnchorTrackingState.Lost:
// Hide the main object and its sub objects until tracking resumes
main.enabled = false;
print('Anchor lost: ' + anchorComponent.anchor.id);
break;
case AnchorModule.AnchorTrackingState.Error:
// Error doesn't recover, so remove the anchor object and everything on it
print('Anchor can no longer be tracked: ' + anchorComponent.anchor.id);
// Forget the stored id, and delete the saved sub object poses too. Use the
// component's current anchor, since moving replaces it with a new id.
this.forgetLastAnchor(anchorComponent.anchor.id);
this.deleteSubObjectPoses(anchorComponent.anchor.id);
anchorObject.destroy();
break;
}
});
}

Save Sub Objects Across Sessions

Anchors are saved, but the objects attached to them aren't. To restore sub objects in a later session, save each sub object's position and rotation relative to its main object, keyed by the anchor's id. Every sub object can be rotated, so the rotation is saved too. This example stores the poses in persistent storage as JSON.

The script saves an anchor's group when a sub object is added and when the user drops a dragged sub object. saveSubObjectPoses rebuilds the list from the objects in the group each time, replacing the one saved before:

// At the top of the file, outside the class.
// Sub object poses are saved per anchor under this key prefix.
const SUB_OBJECT_POSES_KEY_PREFIX = 'subObjectPoses:';

// In the class, if you didn't already add it in
// Restoring an Anchor from a Persisted String ID:
private store = global.persistentStorageSystem.store;

// Save the pose of every sub object in an anchor's group, relative to its main object,
// replacing any saved before. Stored as JSON: [[x, y, z, qw, qx, qy, qz], ...]
private saveSubObjectPoses(anchorComponent: AnchorComponent) {
const values: number[][] = [];
for (const sub of this.getSubObjects(this.getMainObject(anchorComponent))) {
const transform = sub.getTransform();
const p = transform.getLocalPosition();
const r = transform.getLocalRotation();
values.push([p.x, p.y, p.z, r.w, r.x, r.y, r.z]);
}

if (values.length === 0) {
this.deleteSubObjectPoses(anchorComponent.anchor.id);
return;
}
this.store.putString(
SUB_OBJECT_POSES_KEY_PREFIX + anchorComponent.anchor.id,
JSON.stringify(values)
);
}

// Load the sub object poses saved for an anchor, or an empty list if there are none
private loadSubObjectPoses(anchorId: string): { position: vec3; rotation: quat }[] {
const key = SUB_OBJECT_POSES_KEY_PREFIX + anchorId;
if (!this.store.has(key)) {
return [];
}
const values: number[][] = JSON.parse(this.store.getString(key));
return values.map((v) => ({
position: new vec3(v[0], v[1], v[2]),
rotation: new quat(v[3], v[4], v[5], v[6]),
}));
}

// Remove the sub object poses saved for an anchor
private deleteSubObjectPoses(anchorId: string) {
this.store.remove(SUB_OBJECT_POSES_KEY_PREFIX + anchorId);
}

Sub objects come back with their anchor, whether onAnchorNearby or restoreLastAnchor from Restoring an Anchor from a Persisted String ID recreates it, since both call attachNewObjectToAnchor, which loads the saved poses.

The saved sub object poses are keyed by the anchor's id, so they need care when an anchor changes. Moving a group saves its poses under the new anchor's id. Deleting an anchor, or an anchor reaching Error, removes the group's saved poses.

When you move a group, a new anchor is created, so the group's anchor has a new id. Add these lines to moveAnchor:

// In moveAnchor, after setting anchorComponent.anchor to the new anchor:
// save the group under the new id, and remove the entry saved under the old id
this.saveSubObjectPoses(anchorComponent);
this.deleteSubObjectPoses(oldAnchor.id);

When you delete an anchor, delete its saved sub object poses too. In removeAnchor, after deleteAnchor() succeeds, call deleteSubObjectPoses(anchor.id). In clearAreaAnchors and clearAllAnchors, replace the cleanup loop from Clearing Anchors with:

// Delete each anchor's saved sub object poses, then destroy its anchor object,
// which also removes its main object and sub objects
for (let i = this.anchorsRoot.getChildrenCount() - 1; i >= 0; i--) {
const anchorObject = this.anchorsRoot.getChild(i);
const anchorComponent = anchorObject.getComponent(
'Component.AnchorComponent'
);
if (anchorComponent && anchorComponent.anchor) {
this.deleteSubObjectPoses(anchorComponent.anchor.id);
}
anchorObject.destroy();
}

clearAllAnchors() also deletes anchors this session hasn't found yet, such as anchors in other areas or anchors the user isn't near. Their anchor objects aren't under anchorsRoot, so the loop doesn't remove their poses. Every anchor is gone after clearing, so in clearAllAnchors, also remove every saved pose after the loop:

// In clearAllAnchors, after the cleanup loop:
// remove the poses of anchors that weren't found in this session
for (const key of this.store.getAllKeys()) {
if (key.indexOf(SUB_OBJECT_POSES_KEY_PREFIX) === 0) {
this.store.remove(key);
}
}

clearArea() can leave poses behind the same way, for anchors in the area that weren't found in this session. The keys don't include the area, so you can't remove only that area's poses. To cover this case, include the area in the key, such as subObjectPoses:living-room:<id>.

When an anchor reaches Error, delete its saved sub object poses too, since the anchor won't recover. The Error case in attachNewObjectToAnchor does this before destroying the anchor object. It uses anchorComponent.anchor, not the anchor passed in, since moving the anchor replaces it with a new one that has a new id:

// In attachNewObjectToAnchor, in the onStateChanged handler:
case AnchorModule.AnchorTrackingState.Error:
print('Anchor can no longer be tracked: ' + anchorComponent.anchor.id);
this.forgetLastAnchor(anchorComponent.anchor.id);
this.deleteSubObjectPoses(anchorComponent.anchor.id);
anchorObject.destroy();
break;

Closing a Session

Close a session when you no longer need it to track anchors. Closing doesn't delete saved anchors. They're found again the next time you open a session.

When you close a session, the tracking state of each AnchorComponent changes to Lost. Your Lens is responsible for destroying the SceneObjects that hold these AnchorComponents, and the content attached to them, so they don't pile up. When you open a session for that area again, it finds the saved anchors, and your onAnchorNearby handler recreates their attached content.

Close a session when:

  • The user switches to another area. Close the current session, then open a new one for the other area.
  • The user leaves the part of your Lens that uses anchors, and won't see anchored content until they come back.

The following example switches to another area. It closes the current session, removes the previous area's content, and opens a session for the new area. It uses the anchorsRoot object from Placing an Anchor.

private async switchArea(area: string) {
// Close the current session. Its anchors change to Lost, and onStateChanged hides their content.
if (this.anchorSession) {
await this.anchorSession.close();
}

// Remove the previous area's anchor objects and their content
for (let i = this.anchorsRoot.getChildrenCount() - 1; i >= 0; i--) {
this.anchorsRoot.getChild(i).destroy();
}

// Open a session for the new area and listen for its saved anchors
const options = new AnchorModule.AnchorSessionOptions();
options.area = area;
this.anchorSession = await this.anchorModule.openSession(options);
this.anchorSession.onAnchorNearby.add((anchor) =>
this.onAnchorNearby(anchor)
);
}

Area

An area is an optional label for the physical space you're anchoring in, such as "living-room" or "office". You set it with AnchorSessionOptions when you open an AnchorSession, as shown in Anchor Session Options. Anchors created in that session belong to the area, and the session only finds saved anchors in that area. Areas are specific to each Lens, so two Lenses that use the same area name won't share anchors.

If you open a session without an area, it finds all of the Lens's saved anchors, whether or not they belong to an area.

If your Lens is used in more than one space, such as home and office, give each space its own area, and open the session with the area for the space the user is in. If your Lens is used in a single space, you may not need an area at all. Keep each area under about 250 m², since tracking performance degrades in larger spaces.

To switch to another area, see Closing a Session.

Persistence

World anchors can persist across sessions, but they aren't saved automatically. Save an anchor with saveAnchor() and remove it with deleteAnchor() on the AnchorSession. Saved anchors belong to your Lens. Other Lenses can't access them.

In a later session, your Lens gets saved anchors back through onAnchorNearby when the user is near them, or through resolveAnchor() if you stored the anchor's id, as in Restoring an Anchor from a Persisted String ID.

While anchors persist, the content attached to them doesn't. Include logic to re-attach content when your Lens gets an anchor back. For example, if a user attaches virtual weather information to an anchor at their front door, re-attach that information when the Lens finds the anchor again in a future session.

API Reference

AnchorModule

The entry point to the anchoring system. Get it with require('LensStudio:AnchorModule').

SignatureTypeDescription
METHODS
openSessionfunction (options?: AnchorSessionOptions) → Promise<AnchorSession>Open an AnchorSession to start working with anchors. options is optional; pass an AnchorSessionOptions with an area to scope which saved anchors are relevant. The returned AnchorSession is used to create, save, delete, detect, and track anchors.

AnchorSession

An AnchorSession is your connection to the anchor system for an area. Use it to create, save, delete, detect, resolve, and track anchors. When a saved anchor is found, the session hands it to you so you can attach it to a SceneObject with an AnchorComponent. All anchors derive from Anchor. One anchor type is available: WorldAnchor.

SignatureTypeDescription
METHODS
createWorldAnchorfunction (toWorldFromAnchor: mat4) → Promise<WorldAnchor>Create an anchor with the specified world pose. 'World' is the coordinate system of the scene graph root, compatible with a child rendering camera positioned by DeviceTracking set to World. Set the returned anchor on an AnchorComponent to start tracking.
saveAnchorfunction (anchor: Anchor) → Promise<void>Save the given anchor so it can be found again in later sessions via onAnchorNearby or resolveAnchor.
resolveAnchorfunction (anchorId: string) → Promise<Anchor>Restore a saved anchor from its id so you can track it again. Fails if the id is unknown or the anchor isn't accessible to this Lens.
deleteAnchorfunction (anchor: Anchor) → Promise<void>Permanently delete a saved anchor. Tracking stops immediately.
clearAreafunction () → Promise<void>Permanently delete the anchors this Lens saved in the session's area. Fails if the session has no area.
clearAllAnchorsfunction () → Promise<void>Delete all saved anchors for this Lens, across every area.
closefunction () → Promise<void>Close the session and stop tracking. Close it only when tracking is no longer required.
PROPERTIES
areastring | nullThe area this session is using, or null if it was opened without one. Read-only.
onAnchorNearbyevent → (anchor: Anchor)Called when a previously saved anchor is found nearby, including anchors the Lens already resolved with resolveAnchor(). Set it on an AnchorComponent to track it.

AnchorSessionOptions

Options for opening an AnchorSession. Create one with new AnchorModule.AnchorSessionOptions() and pass it to openSession().

SignatureTypeDescription
PROPERTIES
areastring | nullA label for the physical space you're anchoring in, such as "home" or "office". Anchors created in the session belong to this area. Keep areas under about 250 m². Defaults to null, which opens the session without an area, so it finds all of the Lens's saved anchors.

Anchor

Base class for anchors. An Anchor identifies a saved place the system can recognize and track. Holding an Anchor doesn't track it; set it on an AnchorComponent to start tracking. Anchors are always obtained from an AnchorSession, by creating, detecting, or resolving them.

SignatureTypeDescription
PROPERTIES
idstringA string you can store to refer to this anchor later. Pass it to resolveAnchor() to restore the anchor. Read-only.
areastring | nullThe area this anchor belongs to, or null if it was created in a session without an area. Read-only.

WorldAnchor

A spatial anchor fixed to a point in the user's mapped space. Create one by passing a world-space pose to AnchorSession.createWorldAnchor(). To change its pose later, create a new anchor and delete the old one.

WorldAnchor inherits all of its properties from Anchor.

AnchorComponent

Component that ties virtual content (attached to a SceneObject) to the physical world (via an Anchor). Add it to its own SceneObject, set its anchor, and parent your content under that object. The component drives the object's transform from the anchor and reports its tracking state.

The tracking state starts at Initializing, moves to Ready, and then switches between Tracking and Lost as the anchor is localized and lost. The state can move to Error at any point, and Error doesn't recover.

SignatureTypeDescription
PROPERTIES
anchorAnchor | nullThe anchor this component tracks. Set it to begin tracking; set it to null to stop. Defaults to null.
stateAnchorTrackingStateThe current tracking state: Initializing, Ready, Tracking, Lost, or Error. Read-only.
onStateChangedevent → (state: AnchorTrackingState)Called when the tracking state changes, for example when the anchor is found or lost.
onPositionalUncertaintyChangedevent → (uncertainty: number)Called when the anchor's positional uncertainty changes. Roughly how accurate the tracked position is, in centimeters (~1σ).

To add the component from a script, use this.getSceneObject().createComponent('Component.AnchorComponent').