NSDKVps2Session

A session for VPS2 (Visual Positioning System) localization with Combine publisher support....

Declaration

final class NSDKVps2Session

Summary

A session for VPS2 (Visual Positioning System) localization with Combine publisher support. NSDKVps2Session provides capabilities for localizing the device in the real world using VPS maps, universal localization, and anchor tracking. Anchors can be created at specific poses and tracked across sessions using payloads.

Overview

VPS2 features include:

Real-time localization updates for converting between AR space and geolocation
Anchor tracking with per-anchor pose updates
Payload-based anchor persistence across sessions
Localization request diagnostics

Usage Pattern

// Acquire and configure the VPS2 session
let vps2Session = nsdkSession.acquireVps2Session()
let config = NSDKVps2Session.Configuration()
try vps2Session.configure(with: config)
// Subscribe to localization updates
vps2Session.$latestLocalization
    .compactMap { $0 }
    .sink { localization in
        // Use localization.trackingState to check localization quality
    }
    .store(in: &cancellables)
// Subscribe to anchor updates
vps2Session.anchorUpdated
    .sink { id, update in
        // Handle per-anchor pose update
    }
    .store(in: &cancellables)
vps2Session.start()
// Track an anchor by payload
let anchorId = try vps2Session.trackAnchor(payload: base64Payload)

$latestLocalization is updated automatically each frame by NSDKSession.update() while the session is active. anchorUpdated, createdAnchorPayload, and localizationRequestRecords are fired via PassthroughSubject during update() when new data is available.

Properties

Name	Type	Summary
let anchorUpdated	PassthroughSubject<(id: NSDKVpsAnchorId, update: VpsAnchorUpdate), Never>	Fires each frame for every tracked anchor that returns an update. Subscribe to this to receive per-anchor pose changes. The session internally tracks all anchors registered via `trackAnchor(payload:)` or `createAnchor(at:)` and polls them each frame.
let createdAnchorPayload	PassthroughSubject<(id: NSDKVpsAnchorId, payload: String), Never>	Fires once when the payload for a created anchor becomes available. After calling `createAnchor(at:)`, the session automatically polls for the anchor's payload each frame. When the payload is ready, this subject fires once with the anchor ID and the base64-encoded payload string, which can be stored and used later with `trackAnchor(payload:)` to relocalize the anchor in a future session.
@Published var latestLocalization	Vps2Localization	The latest VPS2 localization. Updated each frame by `NSDKSession` while active. `nil` until the first frame update after `start()`. Use `localization.trackingState` to determine localization quality — fields other than `trackingState` are only valid when the state is not `.unavailable`.
let localizationRequestRecords	PassthroughSubject<[Vps2LocalizationRequestRecord], Never>	Fires each frame when new localization request records are available. The array contains only records that occurred since the last call — it is a delta, not a cumulative list. Use this for diagnostics and monitoring localization request activity.

Methods

Name	Type	Summary
anchorPayload	NSDKAsyncState<String, Never>?	Gets the payload data of a specified anchor. The payload encodes the data needed to relocalize an anchor across devices or sessions. It can be stored and used later with `trackAnchor(payload:)`. For anchors created via `createAnchor(at:)`, subscribe to `createdAnchorPayload` instead of polling this method — the session handles polling automatically. - Precondition: `anchorId` must be exactly 32 characters long. - Parameter anchorId: The unique identifier of the anchor. - Returns: - `.inProgress(nil)`: The anchor is tracked but the payload is not yet available. - `.success(payload)`: The base64-encoded payload is ready. - `nil`: No anchor with `anchorId` was found.
anchorUpdate	VpsAnchorUpdate?	Gets the latest tracking update for a specified anchor. Call this for one-shot queries. For ongoing per-frame updates, subscribe to `anchorUpdated` instead. - Precondition: `anchorId` must be exactly 32 characters long. - Parameter anchorId: The unique identifier of a tracked anchor. - Returns: The latest anchor update, or `nil` if the anchor ID is not recognized.
configure	void	Configures the session with the specified settings. - Attention: This method must be called while the session is stopped, or else 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. Creates an anchor relative to the currently tracked location, and begins tracking (no need to call `trackAnchor(payload:)`). The payload for the new anchor will not be available immediately — the session polls for it each frame and fires `createdAnchorPayload` once it becomes ready. - Attention: Anchors can only be created when the current localization's tracking state is `.precise`. Use `$latestLocalization` to observe tracking state. - Parameter pose: The 4x4 transformation matrix representing the anchor's position and orientation in ARKit space. - Returns: A unique identifier for the created anchor. - Throws: `NSDKError.invalidOperation` if the localization is not in `.precise` state.
deviceGeolocation	Vps2GeolocationData?	Gets the geolocation of the device's last known camera pose. - Parameter headingMode: Controls how the heading is derived. Use `.cameraDirection` when the device is upright, or `.deviceTop` when flat or for a compass-style heading. - Returns: Geolocation data corresponding to the device's current pose, or `nil` if VPS2 tracking is unavailable.
featureStatus	NSDKFeatureStatus	Gets the current status of the VPS2 feature. This method reports any errors or warnings that have occurred within the VPS2 system. Check this periodically to monitor the health of localization operations. Once an error is flagged, it will remain flagged until the problematic process runs again and completes successfully. - Returns: Feature status flags indicating current state and any issues.
getLatestLocalization	Vps2Localization	Gets a copy of the latest VPS2 localization. The localization contains all data required to convert between AR space and geolocation. If VPS2 has not yet localized, the localization's `trackingState` will be `.unavailable` and the other fields should be considered invalid. For reactive use, subscribe to `$latestLocalization` instead of calling this directly. - Returns: The latest VPS2 localization.
getLatestLocalizationRequestRecords	[Vps2LocalizationRequestRecord]	Gets the latest localization request records from the VPS2 feature. Returns only records that occurred since the last call — this is a delta, not cumulative. For reactive use, subscribe to `localizationRequestRecords` instead. - Returns: Localization request state changes since the last call.
getPose	Vps2Pose?	Converts a CLLocation to an AR pose using the provided localization snapshot. - Parameters: - localization: The localization to use for the conversion. - location: The CLLocation to convert. - Returns: The pose in the device's AR coordinate space, or `nil` if unavailable.
@discardableResult removeAnchor	Bool	Stops 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 no anchor with that ID exists.
start	void	Starts the VPS2 session. This begins collecting local device sensor data required for localization. To actually localize, call `trackAnchor(payload:)` with a valid VPS payload.
stop	void	Stops the VPS2 session. This halts all VPS2 processing and anchor tracking. The session can be reconfigured and restarted after stopping. `$latestLocalization` is reset to `nil`.
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. The returned anchor ID is automatically polled each frame via `update()`, and updates are published on `anchorUpdated`. - 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 for the VPS2 session.

Relationships

conforms to: NSDKFeatureSession

Class NSDKVps2Session NSDKVps2Session

Declaration​

Summary​

Overview​

Usage Pattern​

Properties​

Methods​

Nested Types​

Structs​

Relationships​