# SpatialAnnotation

Artifact: [androidx.xr.arcore:arcore](https://developer.android.com/jetpack/androidx/releases/xr-arcore) [View Source](https://cs.android.com/search?q=file:androidx/xr/arcore/SpatialAnnotation.kt+class:androidx.xr.arcore.SpatialAnnotation) Added in [1.1.0-alpha01](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.1.0-alpha01)

*** ** * ** ***


```
@ExperimentalSpatialAnnotationsApi
class SpatialAnnotation : Trackable<SpatialAnnotation.State>
```

<br />

*** ** * ** ***

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

## Summary

| ### Nested types |
|---|
| `class https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation.State : https://developer.android.com/reference/kotlin/androidx/xr/arcore/Trackable.State` State containing physical properties that update frame-to-frame. |

| ### Public companion functions |
|---|---|
| `suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation#startTracking(androidx.xr.runtime.Session,androidx.xr.arcore.SpatialAnnotationTrackingOptions)( session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session, options: https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationTrackingOptions )` Starts tracking one or more Spatial Annotations in 3D physical space. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation#stopTracking(androidx.xr.runtime.Session,kotlin.collections.List)(session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session, ids: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationId>)` Stops tracking the provided Spatial Annotations. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation#stopTrackingAllAnnotations(androidx.xr.runtime.Session)(session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session)` Stops tracking all actively tracked Spatial Annotations in the active `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation.Companion#stopTrackingAllAnnotations(androidx.xr.runtime.Session)`. |
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation>>` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation#subscribe(androidx.xr.runtime.Session)(session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session)` Emits the Spatial Annotations that are currently being tracked in the `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation.Companion#subscribe(androidx.xr.runtime.Session)`. |

| ### Public functions |
|---|---|
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation#toString()()` |

| ### Public properties |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationId` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation#id()` the caller-defined unique `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationId` associated with this annotation |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationQuadAlignment?` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation#quadAlignment()` the runtime alignment configuration bound to this `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation`, it will only have a value when the spatial tracking mode is set to quad |
| `open https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation.State>` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation#state()` The current reactive state of the `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation` |

## Public companion functions

### startTracking

Added in [1.1.0-alpha01](https://developer.android.com/jetpack/androidx/releases/xr-arcore#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 `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation#subscribe(androidx.xr.runtime.Session)`.

| Parameters |
|---|---|
| `session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` | the active JXR session |
| `options: https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationTrackingOptions` | configuration generated via `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationTrackingOptions.Builder` |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if tracking cannot be started or is cancelled by the runtime |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if the provided options are invalid |

### stopTracking

Added in [1.1.0-alpha01](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.1.0-alpha01)

```
fun stopTracking(session: Session, ids: List<SpatialAnnotationId>): Unit
```

Stops tracking the provided Spatial Annotations.

| Parameters |
|---|---|
| `session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` | the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` executing the XR tracking |
| `ids: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationId>` | the specific list of `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationId`s to cease tracking |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if the provided list of ids is empty, use `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation#stopTrackingAllAnnotations(androidx.xr.runtime.Session)` to halt all active tracking |

### stopTrackingAllAnnotations

Added in [1.1.0-alpha01](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.1.0-alpha01)

```
fun stopTrackingAllAnnotations(session: Session): Unit
```

Stops tracking all actively tracked Spatial Annotations in the active `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation.Companion#stopTrackingAllAnnotations(androidx.xr.runtime.Session)`.

| Parameters |
|---|---|
| `session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` | the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` executing the XR tracking |

### subscribe

Added in [1.1.0-alpha01](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.1.0-alpha01)

```
fun subscribe(session: Session): StateFlow<List<SpatialAnnotation>>
```

Emits the Spatial Annotations that are currently being tracked in the `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation.Companion#subscribe(androidx.xr.runtime.Session)`.

Only instances of `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation` that are `https://developer.android.com/reference/kotlin/androidx/xr/arcore/TrackingState#TRACKING()` will be emitted in the `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-collection/index.html`. Instances of the same `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation` will remain between subsequent emits to the `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html` as long as they remain tracking.

| Parameters |
|---|---|
| `session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` | the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` to subscribe to |

| Returns |
|---|---|
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation>>` | a `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html` that emits a collection of tracked annotations |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/xr/runtime/SpatialAnnotationTrackingMode` is set to `https://developer.android.com/reference/kotlin/androidx/xr/runtime/SpatialAnnotationTrackingMode#DISABLED()` |

## Public functions

### toString

```
open fun toString(): String
```

## Public properties

### id

Added in [1.1.0-alpha01](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.1.0-alpha01)

```
val id: SpatialAnnotationId
```

the caller-defined unique `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationId` associated with this annotation

### quadAlignment

Added in [1.1.0-alpha01](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.1.0-alpha01)

```
val quadAlignment: SpatialAnnotationQuadAlignment?
```

the runtime alignment configuration bound to this `https://developer.android.com/reference/kotlin/androidx/xr/arcore/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 `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation`