Skip to main content
←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. 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​

NameTypeSummary
let anchorUpdatedPassthroughSubject<(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 createdAnchorPayloadPassthroughSubject<(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.
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 debuggerEventsPassthroughSubject<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 latestLocalizationVps2Localization
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. Use
localization.trackingState to determine localization quality. Fields other than
trackingState are only valid when the state is not .unavailable.
let localizationRequestRecordsPassthroughSubject<[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​

NameTypeSummary
anchorPayloadNSDKAsyncState<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.
anchorUpdateVpsAnchorUpdate?
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 or
assetTrackingData(assetId:) to get the pose of a VPS asset's origin.
assetTrackingDataVps2AssetTrackingData?
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 will
not 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.
configurevoid
Configures the session with the specified settings.
createAnchorNSDKVpsAnchorId
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.
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:) or
localize(latitude:longitude:radiusMeters:). An anchor created here will only track
with the asset of the site that was active at the time of its creation.
deviceGeolocationVps2GeolocationData?
Gets the geolocation of the device's last known camera pose.
Equivalent to passing the last camera pose to getGeolocation(pose:), with the heading
derived according to headingMode.
featureStatusNSDKFeatureStatus
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.
getGeolocationVps2GeolocationData?
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, not
just 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 an
arbitrary 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 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.
getLatestLocalizationVps2Localization
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 .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.
getPoseVps2Pose?
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 that
geolocation 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.
insertCustomDebuggerEventvoid
Inserts a custom event into the VPS debugger log.
localizevoid
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 removeAnchorBool
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 localization
targets.
startvoid
Starts the VPS2 session.
This begins collecting local device sensor data required for localization. Universal
localization does not run by default (see Configuration/universalLocalizationEnabled for
more 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:) start
the 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 already
active has no effect.
stopvoid
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.
stopLocalizevoid
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 localization
targets after a later start(). Requests for the site still in progress are
cancelled, and their localization request records end as failed.
trackAnchorNSDKVpsAnchorId
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:) or
createdAnchorPayload.
The returned anchor ID is automatically polled each frame via update(), and updates
are published on anchorUpdated.

Nested Types​

Structs​

NameTypeSummary
ConfigurationConfiguration
Configuration for the VPS2 session.

Relationships​

conforms to: NSDKFeatureSession