Skip to main content

Localizing and Tracking Anchors with VPS

Anchors are persistent spatial reference points that can be tracked across sessions and devices. The Vps2Session is responsible for managing these anchors and correlating them with their real-world geographic locations.

Anchors persist individual points within a place you have already localized to. To localize to a Site itself, call localize(siteId:) — see Place virtual content with VPS2.

Creating anchors​

The createAnchor(at:) method creates a persistent anchor relative to the Site you are currently localized to, so you must localize to a Site first. Creating an anchor returns its unique anchorId string.

let anchorPose = simd_float4x4(/* your transformation matrix */)

do {
let anchorId = try vps2Session.createAnchor(at: anchorPose)
} catch {
print("Failed to create anchor: \(error)")
}

The transformation matrix here can be assigned to any AR Content you’d want to place.

Getting anchor payloads​

The payload encodes the data needed to resolve an anchor across multiple devices or sessions. It is a string blob that can be shared or stored, is only available after the anchor's Site has been tracked, and is obtained from the anchorPayload(anchorId:) method.

if let payloadState = vps2Session.anchorPayload(anchorId: anchorId) {
switch payloadState {
case .inProgress:
print("Anchor payload is being generated...")
case .success(let payload):
// Payload is available - base64-encoded string
saveAnchorPayload(payload, for: anchorId)
default:
print("Unknown error, default result hit")
}
} else {
// No anchor with the given ID was found
print("Anchor not found")
}

The anchorPayload(anchorId:) returns: An `NSDKAsyncState` representing the state of the anchor payload request:
.inProgress(nil): The anchor is not yet tracked, so the payload is not yet available.
.success(value): The request completed successfully. Contains the base64-encoded payload.
nil: No anchor with id `anchorId` was found.

Tracking existing anchors​

To bring back an anchor you saved earlier, or one shared by another device, pass its payload to trackAnchor(payload:). Tracking also depends on localizing to the anchor's Site: the call is accepted at any time, but the anchor stays untracked until the session localizes to the Site it belongs to.

do {
let anchorId = try vps2Session.trackAnchor(payload: anchorPayload)
} catch {
print("Failed to track anchor: \(error)")
}

The trackAnchor(payload:) returns the unique identifier of the anchor encoded in the payload once tracking has started. Note that successfully getting the id does not mean the anchor is being tracked yet, and for that we need to call the update function.

Updating anchors​

After tracking an anchor, you’ll need to explicitly poll for updates to get the anchor's state and latest pose and make corrections to any related AR content:

// Poll for anchor updates every frame in your update loop
if let update = vps2Session.anchorUpdate(anchorId: anchorId) {
switch update.trackingState {
case .tracked:
// Localized and succesfully tracking the anchor.
case .notTracked:
// Handle untracked state (e.g., hide AR content)
case .limited:
// Tracking is limited or degraded
default:
//Default error message, example: "Unknown error, default result hit"
}
}

The VpsAnchorUpdate object contains a lot of useful information, see the api reference for more information.

Removing anchors​

Once removed, the anchor will no longer receive updates or consume processing resources.

if vps2Session.removeAnchor(withId: anchorId) {
// if you are keeping local anchor references you'll need to handle those
} else {
// Failed to remove anchor (may not exist)
}

This returns true if the anchor was removed, false if otherwise. Keep in mind that you’ll still need to clear content associated with the anchor.
Note that this call uses the anchorId and not the payload.

VPS Workflow:

A typical VPS workflow involves the following sequence of steps:

  1. Initialization and Setup
  • Initialize and set up your ardkSession.
    • Note: Ensure GPS data is included within the ArdkFrameData.
  1. Session Configuration and Start
  • Configure and start the vps2Session.
  1. Anchor Management
  • Load and Get Payloads:
    • (Optional) Load anchor payload(s) saved from previous sessions.
  • Start Tracking: Begin the anchor tracking process.
  • Update and Maintain:
    • Periodically call anchorUpdate to check for state or position changes in the anchors.
    • Handle any detected changes.
  • Cleanup and Save:
    • Remove any anchors that are no longer needed.
    • (Optional) Save any anchor payloads you want to be loaded in a subsequent session.
  1. Finalization
  • End the session and clear all related content.