NSDKVps2Session
Declaration
final class NSDKVps2SessionSummary
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. Maps are targeted by site ID or
coordinate; anchors mark a place in the world that content should stay attached to, and can
be persisted across sessions using payloads.
Overview
VPS2 features include:
- Localization to a map by site ID or coordinate
- Real-time localization updates for converting between AR space and geolocation
- Anchor tracking with per-anchor pose updates
- Payload-based persistence of anchors 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()
// Localize to a map by site ID (or by coordinate with the lat/long overload)
try vps2Session.localize(siteId: siteId)
$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> | |
| 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'spayload 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.An anchor is tied to the site asset it was created against: in a later session, first localize to its site with localize(siteId:), then call trackAnchor(payload:). |
| 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 sameevents 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.The localization relates the AR tracking space origin to a geographic reference point; it is not relative to the current camera pose. See Vps2Localization.nil until the first frame update after the session becomes active. Uselocalization.trackingState to determine localization quality. Fields other thantrackingState 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 createdAnchorPayloadinstead of polling this method — the session handles polling automatically. |
| 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.This tracks the app's own anchors. It is not how the device's relationship to a map is read: use getPose(location:) to place a geolocation in AR space orassetTrackingData(assetId:) to get the pose of a VPS asset's origin. |
| assetTrackingData | Vps2AssetTrackingData? | Gets the pose of a VPS asset's origin in the device's AR tracking space. The pose relates the asset's origin to the tracking space origin; it is not relative to the current camera pose. See Vps2AssetTrackingData/assetToTrackingTransform.Data is only served while the asset is tracked; until then this returns nil, so keep polling — though an asset the device never approaches willnot become tracked however long it is polled. A pose can be served before the device has localized against the asset, at reduced accuracy, and each localization against it refines the pose. Vps2AssetTrackingData/confidence reflects how well the pose is known.Once tracked, an asset keeps being served while device tracking holds, including after the device localizes in a different asset or moves away. This is independent of the VPS2 tracking state, which describes the geolocation estimate: an asset with no georeference serves tracking data while the tracking state stays coarse. |
| configure | void | Configures the session with the specified settings. |
| 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 beavailable immediately — the session polls for it each frame and fires createdAnchorPayload once it becomes ready.Anchors mark a place in the world that content should stay attached to. VPS2 must localize to a map before anchors can be created for it: use localize(siteId:) orlocalize(latitude:longitude:radiusMeters:). An anchor created here will only trackwith the asset of the site that was active at the time of its creation. |
| deviceGeolocation | Vps2GeolocationData? | Gets the geolocation of the device's last known camera pose. Equivalent to passing the last camera pose to getGeolocation(pose:), with the headingderived according to headingMode. |
| 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. |
| getGeolocation | Vps2GeolocationData? | Converts an AR pose to a geolocation using the latest localization. The inverse of getPose(location:). pose can be any pose in AR tracking space, notjust the camera's. The heading is the direction of the pose's forward axis projected onto the horizontal plane, which matches .cameraDirection in deviceGeolocation(headingMode:)..deviceTop is not offered because it depends on the display orientation, which anarbitrary pose does not have. The heading is not meaningful when the forward axis points straight up or down, or close to it. |
| 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 ondebuggerEvents. This method returns (and clears) the in-memory buffer of thosesame 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 tracking space and geolocation: a transform from the tracking space origin to a geographic reference point. It is not relative to the current camera pose. If VPS2 has not yet localized, the localization's trackingState will be .unavailableand 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. location can be any geolocation, not just the device's; the result is where thatgeolocation lies in AR tracking space, and does not depend on the current camera pose. 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. This removes one of the app's own anchors. It is not how localization to a map is stopped: use stopLocalize(siteId:) to drop a site's assets from the localizationtargets. |
| start | void | Starts the VPS2 session. This begins collecting local device sensor data required for localization. Universal localization does not run by default (see Configuration/universalLocalizationEnabled formore details on enabling Universal localization). To localize against VPS maps, call localize(siteId:) or localize(latitude:longitude:radiusMeters:).Optional: localize(siteId:) and localize(latitude:longitude:radiusMeters:) startthe session themselves. Call this to begin collecting sensor data before any localization target is known, or to resume after stop(). Calling it while the session is alreadyactive has no effect. |
| 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. |
| stopLocalize | void | Stops localizing against previously requested sites. Unregisters the site's assets, removes their anchors, and removes the map data they seeded. Call it before stop() so the site's maps are not localizationtargets after a later start(). Requests for the site still in progress arecancelled, and their localization request records end as failed. |
| trackAnchor | NSDKVpsAnchorId | Requests to start tracking an anchor specified by a payload. Use this only to restore an AR anchor the app created itself with createAnchor(at:) and saved from anchorPayload(anchorId:) orcreatedAnchorPayload.The returned anchor ID is automatically polled each frame via update(), and updatesare published on anchorUpdated. |
Nested Types
Structs
| Name | Type | Summary |
|---|---|---|
| Configuration | Configuration | Configuration for the VPS2 session. |
Relationships
conforms to: NSDKFeatureSession
Subscribe to this to receive per-anchor pose changes. The session internally tracks
all anchors registered via
trackAnchor(payload:)orcreateAnchor(at:)and pollsthem each frame.