Reading this with an AI agent?

Read this page as plain text instead: https://www.nianticspatial.com/docs/llms-api-swift/NSDK.class-NSDKVps2Session.txt — same content, easier to parse than this HTML, with each platform's steps kept separate.

Every page in the current release follows the same pattern, so you can build the URL directly instead of fetching an index: a page at /api/swift/<page>/ is at /llms-api-swift/<page>.txt.

For every page in this section, read https://www.nianticspatial.com/docs/llms-api-swift.txt; for every section of these docs, read https://www.nianticspatial.com/docs/llms.txt.

←API Reference ←NSDK

NSDKVps2Session

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.
let debuggerEvents	PassthroughSubject<Nsdk_Vps_VpsDebuggerDataEvent, Never>	Fires each frame when new VPS debugger events are available. Each emission is a single parsed debugger event from the latest delta batch. Enable logging via `Configuration/vpsDebuggerEnabled` before starting the session. Prefer this publisher for reactive use; `getLatestDebuggerEvents()` returns the same events buffered since its last call (native logs are drained only once per frame here).
@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.
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.
assetTrackingData	Vps2AssetTrackingData?	Gets the pose of a VPS asset's origin in the device's AR tracking space. Polling is the demand that starts tracking: the first call for an asset begins tracking its origin frame and returns `nil` while that spins up, so keep polling. Data is only served while the asset is fully tracked; `nil` covers never-localized, limited, and lost tracking alike, and a `nil` assetId while the device is not localized. Content should not be placed while this returns `nil`.
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.
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.
deviceGeolocation	Vps2GeolocationData?	Gets the geolocation of the device's last known camera pose.
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.
getLatestDebuggerEvents	[Nsdk_Vps_VpsDebuggerDataEvent]	Gets VPS debugger events since the last call to this method. Native debugger logs are drained once per frame in `update()` and published on `debuggerEvents`. This method returns (and clears) the in-memory buffer of those same events accumulated since the previous call — it does not call into native again. Prefer `debuggerEvents` for reactive use.
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 geolocation fields should be considered invalid. For reactive use, subscribe to `$latestLocalization` instead of calling this directly.
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.
getPose	Vps2Pose?	Converts a geolocation to an AR pose using the provided localization snapshot. In most cases you want the overload that uses the latest localization automatically; use this one only when a batch of geolocations must share a single snapshot.
insertCustomDebuggerEvent	void	Inserts a custom event into the VPS debugger log.
localize	void	Requests localization to a site, identified by its site ID. Localizes against the site's production-deployed VPS assets and only those: an asset that has not been deployed to production cannot be localized against. Asynchronous: observe `$latestLocalization` for the outcome. Requests are additive: calling this again does not disturb a request already in flight, and the sites accumulate.
@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.
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`.

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​