# 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)

*** ** * ** ***


```
class Anchor : Trackable<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 |
|---|
| `class https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor.State : https://developer.android.com/reference/kotlin/androidx/xr/arcore/Trackable.State` The representation of the current state of an `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor`. |

| ### Public companion functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorResult` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor#create(androidx.xr.runtime.Session,androidx.xr.runtime.math.Pose)(session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session, pose: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Pose)` Creates and attaches an `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor` at the given `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor.Companion#create(androidx.xr.runtime.Session,androidx.xr.runtime.math.Pose)`. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/java/util/UUID.html>` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor#getPersistedAnchorUuids(androidx.xr.runtime.Session)(session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session)` Retrieves persisted `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor` UUIDs in local storage. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorResult` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor#load(androidx.xr.runtime.Session,java.util.UUID)(session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session, uuid: https://developer.android.com/reference/java/util/UUID.html)` Loads an `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor` from local storage, using the given `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor.Companion#load(androidx.xr.runtime.Session,java.util.UUID)`. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor#unpersist(androidx.xr.runtime.Session,java.util.UUID)(session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session, uuid: https://developer.android.com/reference/java/util/UUID.html)` Deletes a persisted Anchor denoted by `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor.Companion#unpersist(androidx.xr.runtime.Session,java.util.UUID)` from local storage. |

| ### Public functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor#detach()()` Detaches this anchor. |
| `open operator https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor#equals(kotlin.Any)(other: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?)` |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor#hashCode()()` |
| `suspend https://developer.android.com/reference/java/util/UUID.html` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor#persist()()` Stores this `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor` in local storage for cross-session use. |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor#toString()()` Returns a string representation of `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor` for debugging. |

| ### Public properties |
|---|---|
| `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/Anchor.State>` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor#state()` the current `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor.State` of this anchor |

## Public companion functions

### create

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

```
fun create(session: Session, pose: Pose): AnchorResult
```

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

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

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

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

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

### getPersistedAnchorUuids

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

```
fun getPersistedAnchorUuids(session: Session): List<UUID>
```

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

| Parameters |
|---|---|
| `session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` | the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` to retrieve the persisted anchor UUIDs from |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<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/kotlin/androidx/xr/runtime/Session#config()` is set to `https://developer.android.com/reference/kotlin/androidx/xr/runtime/AnchorPersistenceMode#DISABLED()` |

### load

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

```
fun load(session: Session, uuid: UUID): AnchorResult
```

Loads an `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor` from local storage, using the given `https://developer.android.com/reference/kotlin/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/kotlin/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/kotlin/androidx/xr/arcore/Anchor#persist()`.

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

| Parameters |
|---|---|
| `session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` | the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` to load the anchor from |
| `uuid: https://developer.android.com/reference/java/util/UUID.html` | 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/kotlin/androidx/xr/runtime/Session#config()` is set to `https://developer.android.com/reference/kotlin/androidx/xr/runtime/AnchorPersistenceMode#DISABLED()` |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorInvalidUuidException` | if `https://developer.android.com/reference/kotlin/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/kotlin/androidx/xr/runtime/Session` |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorNotAuthorizedException` | if an authorization error occurred while attempting to create the anchor |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorRuntimeFailureException` | if an unspecified error occurred in the runtime while attempting to create the anchor |

### unpersist

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

```
fun unpersist(session: Session, uuid: UUID): Unit
```

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

| Parameters |
|---|---|
| `session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` | the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` to unpersist the anchor from |
| `uuid: https://developer.android.com/reference/java/util/UUID.html` | 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/kotlin/androidx/xr/runtime/Session#config()` is set to `https://developer.android.com/reference/kotlin/androidx/xr/runtime/AnchorPersistenceMode#DISABLED()` |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorInvalidUuidException` | if the provided `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor.Companion#unpersist(androidx.xr.runtime.Session,java.util.UUID)` is invalid |

## Public functions

### detach

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

```
fun detach(): Unit
```

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

### equals

```
open operator fun equals(other: Any?): Boolean
```

### hashCode

```
open fun hashCode(): Int
```

### persist

```
suspend fun persist(): UUID
```

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

| Returns |
|---|---|
| `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/kotlin/androidx/xr/runtime/Session#config()` is set to `https://developer.android.com/reference/kotlin/androidx/xr/runtime/AnchorPersistenceMode#DISABLED()`, or if there was an unexpected error persisting the anchor (e.g. ran out of memory) |

### toString

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

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

Note: Not intended for production use.

## Public properties

### state

```
open val state: StateFlow<Anchor.State>
```

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