CLASS

ArdkVpsSession

public final class ArdkVpsSession: ArdkSession.IDisposable, ArdkFeatureSession

A session for Visual Positioning System (VPS) functionality.

ArdkVpsSession provides capabilities for precise localization using visual features. VPS can determine device position and orientation relative to a pre-mapped environment, enabling persistent AR experiences that maintain accuracy across sessions.

Example Usage

// 1. Create the VPS session from your ARDK session
let vpsSession = ardkSession.createVpsSession()

// 2. Configure the session (must be done before starting)
let config = ArdkVpsSession.Configuration(
    continuousLocalizationEnabled: true,
    temporalFusionEnabled: true
)
try vpsSession.configure(with: config)

// 3. Start the session
vpsSession.start()

// 4. Track an anchor using a payload (from Geospatial Browser or previously created)
let anchorId = try vpsSession.trackAnchor(payload: anchorPayload)

// 5. Poll for anchor updates regularly (e.g., using a Timer)
// Check feature status to ensure VPS is working correctly
let featureStatus = vpsSession.featureStatus()
if !featureStatus.isOk() {
    print("VPS Feature Status Error: \(featureStatus)")
}

// Get the latest anchor update
if let update = vpsSession.anchorUpdate(anchorId: anchorId) {
    // 6. Check tracking state before placing content
    switch update.trackingState {
    case .notTracked:
        print("Anchor not tracked - waiting for localization")
    case .limited:
        print("Limited tracking - pose may be unreliable")
    case .tracked:
        // Anchor is fully tracked - safe to place content
        if let transform = update.anchorToLocalTransform {
            // Update your AR content with the anchor's transform
            anchorEntity.transform = Transform(matrix: transform)
        }
    }
}

// Optional: Create new anchors at specific poses (requires successful localization)
let newAnchorId = try vpsSession.createAnchor(at: cameraPose)

// Optional: Get payload for created anchor (only available when tracked)
if let payloadState = vpsSession.anchorPayload(anchorId: newAnchorId) {
    switch payloadState {
    case .inProgress:
        print("Payload not yet available")
    case .success(let payload):
        print("Anchor payload: \(payload)")
        // Store or share this payload for future sessions
    }
}

// Optional: Get GPS coordinates from VPS localization
// (requires gpsCorrectionForContinuousLocalization enabled in config)
let result = vpsSession.devicePoseAsGeolocation(pose: cameraPose)
switch result {
case .success(let geolocation):
    print("Lat: \(geolocation.latitude), Lon: \(geolocation.longitude)")
case .failure(let error):
    print("Geolocation error: \(error)")
}

// Stop the session when done
vpsSession.stop()

Methods

featureStatus()

public func featureStatus() -> ArdkFeatureStatus

Reports errors that have occurred within processes running inside this feature.

Check this periodically to see if any errors have occurred with processes running inside this feature. Once an error has been flagged, it will remain flagged until the culprit process has been run again and completed successfully.

• Returns: Feature status flags for any issues that have occurred

configure(with:)

public func configure(with config: Configuration) throws

Configures the session with the specified settings.

• Attention: This method must be called while the session is stopped, or configuration will fail. In that case, while this function returns without throwing, configuration will still fail asynchronously. Use featureStatus() to check that configuration has not failed.
• Parameter config: An object that defines this session's behavior. Only settings that differ from the defaults will be applied.
• Throws: ArdkError.invalidArgument if the configuration is invalid. Check ARDK's C logs for more information.

Parameters

Name	Description
config	An object that defines this session’s behavior. Only settings that differ from the defaults will be applied.

start()

public func start()

Starts the VPS session.

This begings the process of collecting some local device sensor data that is needed for localization. In order to actually localize, trackAnchor(payload:) must be called.

stop()

public func stop()

Stops the VPS.

This halts all VPS processing and anchor tracking. The session can be reconfigured and restarted after stopping.

createAnchor(at:)

public func createAnchor(at pose: simd_float4x4) throws -> ArdkVpsAnchorId

Requests to create an anchor at the specified pose. This will create an anchor relative to the currently tracked location that can be used to localize in future sessions.

• Attention: This method requires that the session has successfully localized (an anchor was successfully tracked) before it returns a valid anchor payload for future sessions.
• Parameter pose: The 4x4 transformation matrix representing the anchor's position and orientation
• Returns: A unique identifier for the created anchor

Parameters

Name	Description
pose	The 4x4 transformation matrix representing the anchor’s position and orientation

trackAnchor(payload:)

public func trackAnchor(payload: String) throws -> ArdkVpsAnchorId

Requests to start tracking an anchor specified by a payload.

A VPS payload contains all the data needed to localize at a VPS-activated location. A default payload for a VPS-activated location can be obtained from the "blob" field in the details view of an entry in the Geospatial Browser, or via anchorPayload(anchorId:) for user-generated anchors.

• Parameter payload: Base64-encoded anchor payload
• Returns: The unique identifier of the anchor encoded in the payload
• Throws: ArdkError.invalidArgument if the payload is not valid.

Parameters

Name	Description
payload	Base64-encoded anchor payload

removeAnchor(withId:)

public func removeAnchor(withId anchorId: ArdkVpsAnchorId) -> Bool

Request to stop tracking an anchor.

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

• Precondition: anchorId must be exactly 32 characters long.
• Parameter anchorId: The unique identifier of the anchor to remove
• Returns: True if the anchor was removed, false if otherwise

Parameters

Name	Description
anchorId	The unique identifier of the anchor to remove

anchorUpdate(anchorId:)

public func anchorUpdate(anchorId: ArdkVpsAnchorId) -> VpsAnchorUpdate?

Gets the latest tracking update for a specified anchor.

Call this regularly to get updated anchor poses as the device moves and VPS refines the localization.

• Precondition: anchorId must be exactly 32 characters long.
• Parameter anchorId: The unique identifier of an anchor
• Returns: The anchor update, if it is available, nil if otherwise.

Parameters

Name	Description
anchorId	The unique identifier of an anchor

anchorPayload(anchorId:)

public func anchorPayload(anchorId: ArdkVpsAnchorId) -> ArdkAsyncState<String, Never>?

Gets the payload data of a specified anchor.

The payload encodes the data needed to localize an anchor across multiple devices or sessions. It can be shared or stored for later use with trackAnchor(payload:).

Payloads are only available after the anchor is tracked.

• Precondition: anchorId must be exactly 32 characters long.
• Parameter anchorId: The unique identifier of the anchor
• Returns: An AnchorTrackingBound 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.

Parameters

Name	Description
anchorId	The unique identifier of the anchor

sessionId()

public func sessionId() -> String?

Gets the unique session identifier for this VPS session.

The session identifier can be used to distinguish between different VPS sessions, useful for debugging. The ID only exists after at least one anchor has been created via createAnchor(at:) or trackAnchor(payload:).

• Returns: The session identifier if available, nil if otherwise.

devicePoseAsGeolocation(pose:)

public func devicePoseAsGeolocation(
    pose: simd_float4x4
) -> Result<GeolocationData, VpsGraphOperationError>

Use VPS to get an estimated geolocation for a pose in AR space.

Requires that the session was configured with gpsCorrectionForContinuousLocalization, enabled and the user be currently localized.

• Note: Test (private) scans currently don't have GPS data so they cannot be used with this functionality.

• Parameter pose: A pose in the device's AR space.

• Returns: The estimated geolocation, if available, or an error code otherwise.

Parameters

Name	Description
pose	A pose in the device’s AR space.