NsdkVpsSession

A session for Visual Positioning System (VPS) functionality....

Declaration

final class NsdkVpsSession

Summary

A session for Visual Positioning System (VPS) functionality. NsdkVpsSession 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 NSDK session
let vpsSession = nsdkSession.createVpsSession()
// 2. Configure the session (must be done before starting)
let config = NsdkVpsSession.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

Name	Type	Summary
anchorPayload	NsdkAsyncState<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.
anchorUpdate	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.
configure	void	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: `NsdkError.invalidArgument` if the configuration is invalid. Check NSDK's C logs for more information.
createAnchor	NsdkVpsAnchorId	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
devicePoseAsGeolocation	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.
featureStatus	NsdkFeatureStatus	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
removeAnchor	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
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.
start	void	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	void	Stops the VPS. This halts all VPS processing and anchor tracking. The session can be reconfigured and restarted after stopping.
trackAnchor	NsdkVpsAnchorId	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: `NsdkError.invalidArgument` if the payload is not valid.

Nested Types

Structs

Name	Type	Summary
Configuration	Configuration	Configuration structure for the VPS session.

Relationships

conforms to: NsdkFeatureSession

Class NsdkVpsSession NsdkVpsSession

Declaration​

Summary​

Example Usage​

Methods​

Nested Types​

Structs​

Relationships​