# 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
public final class SpatialAnnotation implements Trackable<@NonNull SpatialAnnotation.State>
```

<br />

*** ** * ** ***

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

## Summary

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

| ### Public methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotationId` | `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation#getId()()` the caller-defined unique `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotationId` associated with this annotation |
| `final https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotationQuadAlignment` | `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation#getQuadAlignment()()` the runtime alignment configuration bound to this `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation`, it will only have a value when the spatial tracking mode is set to quad |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation.State>` | `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation#getState()()` The current reactive state of the `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation` |
| `static final void` | `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation#startTracking(androidx.xr.runtime.Session,androidx.xr.arcore.SpatialAnnotationTrackingOptions)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session session, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotationTrackingOptions options )` Starts tracking one or more Spatial Annotations in 3D physical space. |
| `static final void` | `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation#stopTracking(androidx.xr.runtime.Session,kotlin.collections.List)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session session, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotationId> ids )` Stops tracking the provided Spatial Annotations. |
| `static final void` | `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation#stopTrackingAllAnnotations(androidx.xr.runtime.Session)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session session)` Stops tracking all actively tracked Spatial Annotations in the active `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation.Companion#stopTrackingAllAnnotations(androidx.xr.runtime.Session)`. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation>>` | `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation#subscribe(androidx.xr.runtime.Session)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session session)` Emits the Spatial Annotations that are currently being tracked in the `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation.Companion#subscribe(androidx.xr.runtime.Session)`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation#toString()()` |

## Public methods

### getId

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

```
public final @NonNull SpatialAnnotationId getId()
```

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

### getQuadAlignment

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

```
public final SpatialAnnotationQuadAlignment getQuadAlignment()
```

the runtime alignment configuration bound to this `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation`, it will only have a value when the spatial tracking mode is set to quad

### getState

```
public @NonNull StateFlow<@NonNull SpatialAnnotation.State> getState()
```

The current reactive state of the `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation`

### startTracking

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

```
public static final void startTracking(
    @NonNull Session session,
    @NonNull SpatialAnnotationTrackingOptions options
)
```

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/androidx/xr/arcore/SpatialAnnotation#subscribe(androidx.xr.runtime.Session)`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session session` | the active JXR session |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotationTrackingOptions options` | configuration generated via `https://developer.android.com/reference/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)

```
public static final void stopTracking(
    @NonNull Session session,
    @NonNull List<@NonNull SpatialAnnotationId> ids
)
```

Stops tracking the provided Spatial Annotations.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session session` | the `https://developer.android.com/reference/androidx/xr/runtime/Session` executing the XR tracking |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotationId> ids` | the specific list of `https://developer.android.com/reference/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/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)

```
public static final void stopTrackingAllAnnotations(@NonNull Session session)
```

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

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session session` | the `https://developer.android.com/reference/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)

```
public static final @NonNull StateFlow<@NonNull List<@NonNull SpatialAnnotation>> subscribe(@NonNull Session session)
```

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

Only instances of `https://developer.android.com/reference/androidx/xr/arcore/SpatialAnnotation` that are `https://developer.android.com/reference/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/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session session` | the `https://developer.android.com/reference/androidx/xr/runtime/Session` to subscribe to |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/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/androidx/xr/runtime/SpatialAnnotationTrackingMode` is set to `https://developer.android.com/reference/androidx/xr/runtime/SpatialAnnotationTrackingMode#DISABLED()` |

### toString

```
public @NonNull String toString()
```