Skip to main content
←API Reference ←com.nianticspatial.nsdk.vps2

Vps2Session

↳ extends SessionBase
A session for VPS2 localization.

Declaration​

class Vps2Session

Properties​

NameTypeSummary
anchorUpdatesFlow<AnchorUpdate>
Flow of anchor updates for all tracked anchors.
Anchors are automatically added when created via [trackAnchor] or [createAnchor].
debuggerEventsFlow<VpsDebuggerDataEvent>
Flow of VPS debugger events.
Each emission is a single [VpsDebuggerDataEvent] from the latest delta batch.
Events are emitted only when new ones are available. Enable logging via
[Vps2Config.enableVpsDebugger] before starting the session.
DEFAULT_ANCHOR_POLLING_INTERVAL_MSDEFAULT_ANCHOR_POLLING_INTERVAL_MS
-
DEFAULT_LOCALIZATION_POLLING_INTERVAL_MSDEFAULT_LOCALIZATION_POLLING_INTERVAL_MS
-
localizationRequestRecordsFlow<Vps2LocalizationRequestRecord>
Flow of localization request records.
Each emission is a single [Vps2LocalizationRequestRecord] from the latest batch.
Records are emitted only when new ones are available.
localizationUpdatesFlow<Vps2Localization>
Flow of the latest localization snapshot.
This is useful for consumers that want to reactively drive UI or downstream computations
without manually polling [getLatestLocalization].

Functions​

NameTypeSummary
anchorIdToStringString
Convert a VPS2 anchor id (32-byte ASCII hex) to a printable string.
configurevoid
Configure VPS2. Must be called while stopped.
createAnchorUUID
Create and start tracking an anchor at the specified pose.
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] with a site ID or its
lat/long overload. An anchor created here will only track with the asset of the site that
was active at the time of its creation.
featureStatusFeatureStatus
-
getAnchorPayloadString?
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].
Note: an anchor is tied to the site asset it was created against, so it will not resolve
against a different site or a different asset of the same site. To start tracking an anchor
in a different session, first localize to its site with [localize], then call [trackAnchor].
getAnchorUpdateAnchorUpdate
Gets the latest tracking update for a specified anchor.
This tracks the app's own anchors. It is not how the device's relationship to a map is read:
use [getPose] to place a geolocation in AR space or [getAssetTrackingData] to get the pose
of a VPS asset's origin.
getAssetTrackingDataVps2AssetTrackingData?
Gets the pose and tracking confidence of a VPS asset's origin in the device's AR tracking space.
Call this regularly to place content authored in the asset's coordinate space: the pose is
refined as the device moves and VPS relocalizes. The pose relates the asset's origin to the
tracking space origin; it is not relative to the current camera pose.
Data is only served while the asset is tracked; until then this returns null, 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.trackingConfidence] 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.
An asset the portal published without geographic bounds — only legacy assets — is treated
as always near the device, so it can be tracked and served from any distance.
This function only accepts a VPS map asset ID, not a mesh or splat asset ID.
getDeviceGeolocationVps2GeolocationData?
Get the geolocation of the device's last known camera pose.
Equivalent to passing the last camera pose to [getGeolocation], with the heading derived
according to [headingMode].
getGeolocationVps2GeolocationData?
Convert an AR pose to a geolocation using the latest localization. The inverse of
[getPose]. [pose] can be any pose in AR tracking space (ARCore's coordinate convention, in
meters), not just the camera's.
The heading is the direction of the pose's forward axis projected onto the horizontal
plane, which matches [HeadingMode.CAMERA_DIRECTION] in [getDeviceGeolocation].
[HeadingMode.DEVICE_TOP] 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.
getLatestDebuggerEventsList<VpsDebuggerDataEvent>
Get VPS debugger events since the last call.
getLatestLocalizationVps2Localization
Gets the most recent VPS2 localization result.
The returned localization contains the spatial mapping between the device's AR tracking
space and real-world geolocation: a transform from the tracking space origin to a geographic
reference point. It is not relative to the current camera pose. Pass it to [getPose] to
convert geolocations to AR poses.
getLatestLocalizationRequestRecordsList<Vps2LocalizationRequestRecord>
Get diagnostic localization request records since the last call.
getPosePose
Convert a geolocation to an AR pose using a 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.
getTrackedAnchorsSet<UUID>
Get the set of all tracked anchors.
insertCustomDebuggerEventvoid
Insert 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. This is an asynchronous
operation: progress is reported on [localizationRequestRecords] as a record of type
[Vps2LocalizationRequestType.ASSET_INFO] — [Vps2LocalizationRequestStatus.PENDING] on
dispatch, then [Vps2LocalizationRequestStatus.COMPLETED], or
[Vps2LocalizationRequestStatus.FAILED] with the record's error set (e.g.
[Vps2LocalizationError.SITE_NOT_FOUND] when no such site exists, or
[Vps2LocalizationError.ASSETS_NOT_FOUND] when the site has nothing localizable in it).
COMPLETED means every production-deployed asset in the site was submitted for
localization, not that localization succeeded — observe [localizationUpdates] for the outcome.
Requests are additive: calling this again does not disturb a request already in flight,
and the sites accumulate. Each request produces its own records, but the caller is not
given its record identifier, so records from concurrent requests are distinguishable
only by the order in which they arrive.
Starts the session if it is not already started.
Note: assets already submitted for localization stay in the localization set until
[stopLocalize] removes them; [stopLocalize] for the site also cancels a request still in
progress. Each additional site increases the size of every cloud localization request and the per-frame
target-selection cost, so keep the number of sites small.
onDestroyvoid
-
onInitvoid
-
onSessionEndedvoid
-
onStopBeforeDestroyvoid
-
removeAnchorvoid
Stop tracking an anchor.
This removes one of the app's own anchors. It is not how localization to a map is stopped:
use [stopLocalize] to drop a site's assets from the localization targets.
startvoid
Start the VPS2 session.
Optional: [localize] starts the session itself. 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 started has no effect.
stopvoid
-
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 records end
as [Vps2LocalizationRequestStatus.FAILED].
trackAnchorUUID
Start tracking an anchor specified by a base64 payload.
Use this only to restore an AR anchor the app created itself with [createAnchor] and saved
with [getAnchorPayload].
Note: an anchor payload is no longer the preferred method to identify the map to localize
against: target a map by site ID with [localize] or by coordinate with its lat/long
overload. An anchor is tied to the site asset it was created against, so it will not
resolve against a different site or a different asset of the same site.