Place virtual content with VPS2

VPS2 enables high-accuracy placement of virtual content. Anchors are the primary mechanism used to place and persist that content across sessions.

To place content, VPS2 must be configured and running. If you haven’t set it up yet, see Get started with VPS2.

Anchors

Anchors are persistent spatial reference points used to place and share virtual content across sessions and devices.

An anchor:

• Is a tracked point tied to a VPS map with a position and orientation (pose) defined in a coordinate space.
• Has a trackingState that indicates the accuracy of its own pose relative to a device: Limited, for coarse alignment, and Tracked for high-confidence alignment.

The coordinate space determines how the anchor behaves:

• In AR space, an anchor remains stable relative to the session origin.
• In map-relative space, an anchor remains fixed to a location in the real world.
• In global space, an anchor aligns to geographic coordinates.

Anchor payloads are the serialized data used to restore anchors across sessions and devices.

Anchor lifecycle

The typical workflow for placing content with anchors:

1. An anchor is created typically starting in trackingState = Limited, providing coarse localization.
2. The anchor becomes Tracked when VPS resolves.
3. The anchor payload is retrieved to persist across devices or sessions.
4. Anchors continue to update as localization changes and can be removed when no longer needed.

Tracking states

VPS2 exposes two tracking states for anchors:

• Limited: The anchor pose is estimated using coarse localization. The pose is usable for approximate placement but may drift and does not provide centimeter-level alignment.
• Tracked: The device is localized to a VPS map, and the anchor pose is resolved relative to that VPS map with centimeter-level accuracy.

These states describe the accuracy of the anchor’s pose in the local AR coordinate frame. They are independent of the VPS2 transformer’s geographic tracking state, which governs the accuracy of geoposition-based conversions.

An anchor may transition from Limited to Tracked once the device localizes to the underlying VPS map. If map localization is lost, a Tracked anchor may revert to Limited. If precise AR alignment is required, your application should wait until the anchor reaches the Tracked state.

Anchor management

The VPS2 session manages the lifecycle of anchors and maintains the relationship between each anchor’s map-relative pose and its global geoposition. Niantic automatically creates an anchor for each asset in a Site when you generate assets. You cannot change the position of this anchor, but you can create an additional anchor if you want to locate a specific item within the space.

To obtain an anchor, you can:

• Create an anchor from a pose.
• Get an anchor from an anchor payload.

Create anchor

To place virtual content, you first create or track an anchor at the desired location.

The TryCreateAnchor method:

• Creates a persistent anchor in addition to the one that Niantic creates when you generate assets.
• Ties the new anchor to visual features at a specified pose.
• Returns an ARPersistentAnchor GameObject.
• Allows you to later get its anchor payload to use it across devices or sessions.

The pose provided when creating an anchor is expressed in the current local AR coordinate frame. Do not manually modify the anchor’s transform; it is updated automatically by VPS2.

The following code example shows how to create an anchor anchorOut at a specified pose:

if (vps2Manager.TryCreateAnchor(pose, out var anchorOut)) {
    // Attach virtual content to the anchor so it stays fixed in the real world
}

Get anchor payload

After creating or tracking an anchor, you can optionally retrieve its payload for persistence.

An anchor payload is a base64-encoded string that encodes the data required to resolve the anchor across devices or sessions.

For user-created anchors, the payload becomes available only after the anchor has been sufficiently resolved against its originating VPS map, typically when the anchor reaches the Tracked state.

To retrieve a payload, you must already have an anchor, either created or tracked.

Key points:

• Payload retrieval depends on the anchor’s tracking state.
• Payloads are typically available when the anchor is Tracked.
• Payloads are map-specific and should be reused with the same VPS map.

note

Anchor payloads are map-specific and can only be precisely resolved against the map on which they were created. If resolved outside that map, the anchor may only achieve coarse positioning based on global geoposition.

Anchor payloads can be obtained in two ways:

1. From default anchors associated with published Sites, using the “Anchor Payload” field in the Site’s Assets view.
2. From anchors created or tracked in your application.

You can also retrieve an anchor payload from Scaniverse web by selecting a generated asset, then selecting the copy icon next to Anchor Payload from the right panel as shown in the following image:

In Unity, use the TryGetAnchorPayload API:

• Takes an ARPersistentAnchor as input.
• Returns a base64-encoded payload string via an output parameter.
• Succeeds only when the anchor has been sufficiently resolved.

The following code example shows how to retrieve the payload payload from an anchor:

if (vps2Manager.TryGetAnchorPayload(anchor, out string payload)) {
    // Your logic here
}

Update anchors

After creating or tracking an anchor using either TryCreateAnchor or TryTrackAnchor, the transform of the ARPersistentAnchor component is updated automatically. You may also subscribe to anchor updates as follows:

vps2Manager.trackablesChanged.AddListener(OnTrackablesChanged);

Remove anchors

Once removed, an anchor stops receiving updates and no longer consumes processing resources.

The following code example shows how to use TryRemoveAnchor to remove an anchor _anchor:

vps2Manager.TryRemoveAnchor(_anchor);