# Anchor

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/Anchor.kt+class:androidx.xr.arcore.Anchor) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.0.0)

*** ** * ** ***


```
public final class Anchor implements Trackable<@NonNull Anchor.State>
```

<br />

*** ** * ** ***

An anchor describes a fixed location and orientation in the real world.

To stay at a fixed location in physical space, the numerical description of this position may update as ARCore for XR updates its understanding of the physical world.

## Summary

| ### Nested types |
|---|
| `public final class https://developer.android.com/reference/androidx/xr/arcore/Anchor.State implements https://developer.android.com/reference/androidx/xr/arcore/Trackable.State` The representation of the current state of an `https://developer.android.com/reference/androidx/xr/arcore/Anchor`. |

| ### Public methods |
|---|---|
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/AnchorResult` | `https://developer.android.com/reference/androidx/xr/arcore/Anchor#create(androidx.xr.runtime.Session,androidx.xr.runtime.math.Pose)(@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/runtime/math/Pose pose)` Creates and attaches an `https://developer.android.com/reference/androidx/xr/arcore/Anchor` at the given `https://developer.android.com/reference/androidx/xr/arcore/Anchor.Companion#create(androidx.xr.runtime.Session,androidx.xr.runtime.math.Pose)`. |
| `final void` | `https://developer.android.com/reference/androidx/xr/arcore/Anchor#detach()()` Detaches this anchor. |
| `boolean` | `https://developer.android.com/reference/androidx/xr/arcore/Anchor#equals(kotlin.Any)(https://developer.android.com/reference/java/lang/Object.html other)` |
| `static final @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/java/util/UUID.html>` | `https://developer.android.com/reference/androidx/xr/arcore/Anchor#getPersistedAnchorUuids(androidx.xr.runtime.Session)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session session)` Retrieves persisted `https://developer.android.com/reference/androidx/xr/arcore/Anchor` UUIDs in local storage. |
| `@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/Anchor.State>` | `https://developer.android.com/reference/androidx/xr/arcore/Anchor#getState()()` the current `https://developer.android.com/reference/androidx/xr/arcore/Anchor.State` of this anchor |
| `int` | `https://developer.android.com/reference/androidx/xr/arcore/Anchor#hashCode()()` |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/AnchorResult` | `https://developer.android.com/reference/androidx/xr/arcore/Anchor#load(androidx.xr.runtime.Session,java.util.UUID)(@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/UUID.html uuid)` Loads an `https://developer.android.com/reference/androidx/xr/arcore/Anchor` from local storage, using the given `https://developer.android.com/reference/androidx/xr/arcore/Anchor.Companion#load(androidx.xr.runtime.Session,java.util.UUID)`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/UUID.html` | `https://developer.android.com/reference/androidx/xr/arcore/Anchor#persist()()` Stores this `https://developer.android.com/reference/androidx/xr/arcore/Anchor` in local storage for cross-session use. |
| `@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/Anchor#toString()()` Returns a string representation of `https://developer.android.com/reference/androidx/xr/arcore/Anchor` for debugging. |
| `static final void` | `https://developer.android.com/reference/androidx/xr/arcore/Anchor#unpersist(androidx.xr.runtime.Session,java.util.UUID)(@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/UUID.html uuid)` Deletes a persisted Anchor denoted by `https://developer.android.com/reference/androidx/xr/arcore/Anchor.Companion#unpersist(androidx.xr.runtime.Session,java.util.UUID)` from local storage. |

## Public methods

### create

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

```
public static final @NonNull AnchorResult create(@NonNull Session session, @NonNull Pose pose)
```

Creates and attaches an `https://developer.android.com/reference/androidx/xr/arcore/Anchor` at the given `https://developer.android.com/reference/androidx/xr/arcore/Anchor.Companion#create(androidx.xr.runtime.Session,androidx.xr.runtime.math.Pose)`.

Returns `https://developer.android.com/reference/androidx/xr/arcore/AnchorCreateResourcesExhausted` if the runtime has run out of resources while attempting to create the anchor.

Returns `https://developer.android.com/reference/androidx/xr/arcore/AnchorCreateTrackingUnavailable` if tracking was unavailable while attempting to create the anchor.

```kotlin
import androidx.xr.arcore.Anchor
import androidx.xr.arcore.AnchorCreateResourcesExhausted
import androidx.xr.arcore.AnchorCreateSuccess
import androidx.xr.arcore.AnchorCreateTrackingUnavailable
import androidx.xr.arcore.AnchorRuntimeFailureException
import androidx.xr.arcore.AnchorUnsupportedLocationException
import androidx.xr.arcore.TrackingState
import androidx.xr.runtime.math.Pose
import androidx.xr.scenecore.scene

// We need to first translate the pose from activity space to perception space.
val perceptionPose =
    session.scene.activitySpace.transformPoseTo(pose, session.scene.perceptionSpace)

// Now we can try and create the anchor.
// Anchor creation can fail for a variety of reasons, so we need to handle those various cases.
try {
    when (val anchorResult = Anchor.create(session, perceptionPose)) {
        is AnchorCreateSuccess -> {
            // Our call succeeded, and we can now make use of our new anchor. In this example,
            // we are simply going to convert our pose back to activity space and then pass it
            // to a rendering function for rendering.
            val anchor = anchorResult.anchor
            yourCoroutineScope.launch {
                anchor.state.collect {
                    // Early out if tracking is lost on the anchor; we only want to render it
                    // when we have confidence it is in the correct position.
                    if (it.trackingState != TrackingState.TRACKING) return@collect

                    // Convert our anchor pose back into activity space.
                    val activityPose =
                        session.scene.perceptionSpace.transformPoseTo(
                            it.pose,
                            session.scene.activitySpace,
                        )

                    // Render the anchor.
                    yourAnchorRenderingFunction(activityPose)
                }
            }
        }
        is AnchorCreateResourcesExhausted -> {
            // In order to conserve resources, runtimes impose a limit on how many anchors may
            // be in use concurrently. When that limit is reached, subsequent `Anchor.create()`
            // will fail with this result. Depending on your use case, you can either notify the
            // user that no more anchors can be created, or you can try and free up resources by
            // removing older anchors if they're no longer necessary.
        }
        is AnchorCreateTrackingUnavailable -> {
            // This result indicates that tracking is currently unavailable. Depending on the
            // situation, tracking may or may not return, so this result could just indicate a
            // temporary problem. Repeatedly getting this result for a prolonged period of time
            // may indicate a non-recoverable loss of tracking, which will likely severely
            // impact application functionality.
        }
        else -> {
            // Exhaustive when not allowed for AnchorResult.
        }
    }
} catch (e: AnchorUnsupportedLocationException) {
    // This exception is thrown when the underlying runtime does not support creating an anchor
    // at the provided location.
} catch (e: AnchorRuntimeFailureException) {
    // This exception is thrown when an unspecified error was encountered in the runtime while
    // attempting to create the anchor.
}
```

| 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` that is used to create the anchor |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/math/Pose pose` | the `https://developer.android.com/reference/androidx/xr/runtime/math/Pose` that describes the location and orientation of the anchor |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/AnchorResult` | a subtype of `https://developer.android.com/reference/androidx/xr/arcore/AnchorResult` based on the result of the operation |

| Throws |
|---|---|
| `https://developer.android.com/reference/androidx/xr/arcore/AnchorRuntimeFailureException` | if an unspecified error occurred in the runtime while attempting to create the anchor |

### detach

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

```
public final void detach()
```

Detaches this anchor. This anchor will no longer be updated or tracked.

### equals

```
public boolean equals(Object other)
```

### getPersistedAnchorUuids

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

```
public static final @NonNull List<@NonNull UUID> getPersistedAnchorUuids(@NonNull Session session)
```

Retrieves persisted `https://developer.android.com/reference/androidx/xr/arcore/Anchor` UUIDs in local storage.

| 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 retrieve the persisted anchor UUIDs from |

| Returns |
|---|---|
| `@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/java/util/UUID.html>` | a list of `https://developer.android.com/reference/java/util/UUID.html`s representing the persisted anchors |

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

### getState

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

the current `https://developer.android.com/reference/androidx/xr/arcore/Anchor.State` of this anchor

### hashCode

```
public int hashCode()
```

### load

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

```
public static final @NonNull AnchorResult load(@NonNull Session session, @NonNull UUID uuid)
```

Loads an `https://developer.android.com/reference/androidx/xr/arcore/Anchor` from local storage, using the given `https://developer.android.com/reference/androidx/xr/arcore/Anchor.Companion#load(androidx.xr.runtime.Session,java.util.UUID)`.

The anchor will attempt to be attached in the same physical location as the anchor that was previously persisted. The `https://developer.android.com/reference/androidx/xr/arcore/Anchor.Companion#load(androidx.xr.runtime.Session,java.util.UUID)` should be the return value of a previous call to `https://developer.android.com/reference/androidx/xr/arcore/Anchor#persist()`.

Returns `https://developer.android.com/reference/androidx/xr/arcore/AnchorCreateResourcesExhausted` if the runtime has run out of resources while attempting to create the anchor.

| 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 load the anchor from |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/UUID.html uuid` | the `https://developer.android.com/reference/java/util/UUID.html` of the anchor to load |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if `https://developer.android.com/reference/androidx/xr/runtime/Session#config()` is set to `https://developer.android.com/reference/androidx/xr/runtime/AnchorPersistenceMode#DISABLED()` |
| `https://developer.android.com/reference/androidx/xr/arcore/AnchorInvalidUuidException` | if `https://developer.android.com/reference/androidx/xr/arcore/Anchor.Companion#load(androidx.xr.runtime.Session,java.util.UUID)` is not a `https://developer.android.com/reference/java/util/UUID.html` currently being tracked by the `https://developer.android.com/reference/androidx/xr/runtime/Session` |
| `https://developer.android.com/reference/androidx/xr/arcore/AnchorNotAuthorizedException` | if an authorization error occurred while attempting to create the anchor |
| `https://developer.android.com/reference/androidx/xr/arcore/AnchorRuntimeFailureException` | if an unspecified error occurred in the runtime while attempting to create the anchor |

### persist

```
public final @NonNull UUID persist()
```

Stores this `https://developer.android.com/reference/androidx/xr/arcore/Anchor` in local storage for cross-session use.

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/UUID.html` | the `https://developer.android.com/reference/java/util/UUID.html` that uniquely identifies this anchor |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if `https://developer.android.com/reference/androidx/xr/runtime/Session#config()` is set to `https://developer.android.com/reference/androidx/xr/runtime/AnchorPersistenceMode#DISABLED()`, or if there was an unexpected error persisting the anchor (e.g. ran out of memory) |

### toString

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

Returns a string representation of `https://developer.android.com/reference/androidx/xr/arcore/Anchor` for debugging.

Note: Not intended for production use.

### unpersist

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

```
public static final void unpersist(@NonNull Session session, @NonNull UUID uuid)
```

Deletes a persisted Anchor denoted by `https://developer.android.com/reference/androidx/xr/arcore/Anchor.Companion#unpersist(androidx.xr.runtime.Session,java.util.UUID)` from local storage.

| 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 unpersist the anchor from |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/UUID.html uuid` | the `https://developer.android.com/reference/java/util/UUID.html` of the anchor to unpersist |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if `https://developer.android.com/reference/androidx/xr/runtime/Session#config()` is set to `https://developer.android.com/reference/androidx/xr/runtime/AnchorPersistenceMode#DISABLED()` |
| `https://developer.android.com/reference/androidx/xr/arcore/AnchorInvalidUuidException` | if the provided `https://developer.android.com/reference/androidx/xr/arcore/Anchor.Companion#unpersist(androidx.xr.runtime.Session,java.util.UUID)` is invalid |