ARDK for Android/com.nianticlabs.ardk.vps/VPSSession

VPSSession

class VPSSession : SessionBase<VPSSession>

A session for Visual Positioning System (VPS) functionality.

VPSSession provides capabilities for precise localization using visual features. VPS can determine device position and orientation relative to a pre-mapped environment, enabling persistent AR experiences that maintain accuracy across sessions.

Usage

1. Acquire the VPS session:

val vpsSession = ardkSession.vps.acquire()

2. Configure the session (must be done before starting):

val config = VPSConfig(
    enableContinuousLocalization = true,
    enableTemporalFusion = true
)
vpsSession.configure(config)

3. Start the session:

vpsSession.start()

4. Track an anchor using a payload:

A VPS payload can be obtained from the "blob" field in the Geospatial Browser, or via getAnchorPayload for user-generated anchors.

val anchorId = vpsSession.trackAnchor(anchorPayload)

5. Poll for anchor updates regularly:

coroutineScope.launch {
    while (trackingStarted) {
        delay(500) // Update every 500ms
        val update = vpsSession.getAnchorUpdate(anchorId)

        when (update.trackingState) {
            AnchorTrackingState.NOT_TRACKED ->
                println("Anchor not tracked - waiting for localization")
            AnchorTrackingState.LIMITED ->
                println("Limited tracking - pose may be unreliable")
            AnchorTrackingState.TRACKED -> {
                // Anchor is fully tracked - safe to place content
                val matrix = FloatArray(16)
                update.anchorToLocalTrackingTransform.toMatrix(matrix, 0)
                // Update your AR content with the anchor's transform
            }
        }
    }
}

6. Clean up when done:

vpsSession.stop()
vpsSession.close()

Advanced Features

Creating new anchors:

val cameraPose = frame.camera.getDisplayOrientedPose()
val newAnchorId = vpsSession.createAnchor(cameraPose)

Getting anchor payload for sharing:

val payload = vpsSession.getAnchorPayload(newAnchorId)
if (payload != null) {
    // Store or share this payload for future sessions
}

Converting poses to GPS coordinates:

val result = vpsSession.getDevicePoseAsGeolocation(frame.camera.pose)
when (result) {
    is ARDKResult.Success -> {
        val geolocation = result.value
        println("Lat: ${geolocation.latitude}, Lon: ${geolocation.longitude}")
    }
    is ARDKResult.Error -> {
        println("Geolocation error: ${result.code}")
    }
}

Getting session ID for debugging:

val sessionId = vpsSession.getSessionId()
println("VPS Session ID: ${sessionId?.joinToString("") { "%02x".format(it) }}")

See also

VPSSession.start
VPSSession.stop
VPSSession.configure
VPSSession.trackAnchor
VPSSession.getAnchorUpdate

Functions

Name	Summary
acquire	[androidJvm] @Synchronized fun acquire(): VPSSession
close	[androidJvm] @Synchronized open override fun close()
configure	[androidJvm] fun configure(config: VPSConfig) Configures the session with the specified settings.
createAnchor	[androidJvm] fun createAnchor(pose: Pose): UUID Requests to create an anchor at the specified pose. This will create an anchor relative to the currently tracked location that can be used to localize in future sessions.
featureStatus	[androidJvm] fun featureStatus(): FeatureStatus Reports errors that have occurred within processes running inside this feature.
getAnchorPayload	[androidJvm] fun getAnchorPayload(uuid: UUID): String? Gets the payload data of a specified anchor.
getAnchorUpdate	[androidJvm] fun getAnchorUpdate(uuid: UUID): AnchorUpdate Gets the latest tracking update for a specified anchor.
getDevicePoseAsGeolocation	[androidJvm] fun getDevicePoseAsGeolocation(pose: Pose): ARDKResult<GeolocationData, VpsGraphOperationError> Use VPS to get an estimated geolocation for a pose in AR space.
getSessionId	[androidJvm] fun getSessionId(): UUID? Gets the unique session identifier for this VPS session.
removeAnchor	[androidJvm] fun removeAnchor(uuid: UUID) Request to stop tracking an anchor.
start	[androidJvm] fun start() Starts the VPS session.
stop	[androidJvm] fun stop() Stops the VPS session.
trackAnchor	[androidJvm] fun trackAnchor(payload: String): UUID Requests to start tracking an anchor specified by a payload.