SpatialAnnotation

@ExperimentalSpatialAnnotationsApi
class SpatialAnnotation : Trackable

Base class for all tracked Spatial Annotations (Quads, Points, Masks, etc.).

Summary

Nested types

State containing physical properties that update frame-to-frame.

Public companion functions
suspend Unit
startTracking(
    session: Session,
    options: SpatialAnnotationTrackingOptions
)

Starts tracking one or more Spatial Annotations in 3D physical space.
Unit

Stops tracking the provided Spatial Annotations.
Unit

Stops tracking all actively tracked Spatial Annotations in the active session.
StateFlow<List<SpatialAnnotation>>
subscribe(session: Session)

Emits the Spatial Annotations that are currently being tracked in the session.

Public functions
open String

Public properties
SpatialAnnotationId

the caller-defined unique SpatialAnnotationId associated with this annotation
SpatialAnnotationQuadAlignment?

the runtime alignment configuration bound to this SpatialAnnotation, it will only have a value when the spatial tracking mode is set to quad
open StateFlow<SpatialAnnotation.State>

The current reactive state of the SpatialAnnotation

Public companion functions

startTracking

Added in 1.1.0-alpha01
suspend fun startTracking(
    session: Session,
    options: SpatialAnnotationTrackingOptions
): Unit

Starts tracking one or more Spatial Annotations in 3D physical space.

The app will not receive tracking updates for these annotations until this method completes. It is recommended to call this method before calling subscribe.

Parameters
session: Session

the active JXR session
options: SpatialAnnotationTrackingOptions

configuration generated via SpatialAnnotationTrackingOptions.Builder
Throws
IllegalStateException

if tracking cannot be started or is cancelled by the runtime
IllegalArgumentException

if the provided options are invalid

stopTracking

Added in 1.1.0-alpha01
fun stopTracking(session: Session, ids: List<SpatialAnnotationId>): Unit

Stops tracking the provided Spatial Annotations.

Parameters
session: Session

the Session executing the XR tracking
ids: List<SpatialAnnotationId>

the specific list of SpatialAnnotationIds to cease tracking
Throws
IllegalArgumentException

if the provided list of ids is empty, use stopTrackingAllAnnotations to halt all active tracking

stopTrackingAllAnnotations

Added in 1.1.0-alpha01
fun stopTrackingAllAnnotations(session: Session): Unit

Stops tracking all actively tracked Spatial Annotations in the active session.

Parameters
session: Session

the Session executing the XR tracking

subscribe

Added in 1.1.0-alpha01
fun subscribe(session: Session): StateFlow<List<SpatialAnnotation>>

Emits the Spatial Annotations that are currently being tracked in the session.

Only instances of SpatialAnnotation that are androidx.xr.arcore.TrackingState.TRACKING will be emitted in the Collection. Instances of the same SpatialAnnotation will remain between subsequent emits to the StateFlow as long as they remain tracking.

Parameters
session: Session

the Session to subscribe to
Returns
StateFlow<List<SpatialAnnotation>>

a StateFlow that emits a collection of tracked annotations
Throws
IllegalStateException

if SpatialAnnotationTrackingMode is set to SpatialAnnotationTrackingMode.DISABLED

Public functions

toString

open fun toString(): String

Public properties

id

Added in 1.1.0-alpha01
val id: SpatialAnnotationId

the caller-defined unique SpatialAnnotationId associated with this annotation

quadAlignment

Added in 1.1.0-alpha01
val quadAlignment: SpatialAnnotationQuadAlignment?

the runtime alignment configuration bound to this SpatialAnnotation, it will only have a value when the spatial tracking mode is set to quad

state

open val state: StateFlow<SpatialAnnotation.State>

The current reactive state of the SpatialAnnotation