class Anchor

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

The representation of the current state of an Anchor.

Public companion functions
AnchorCreateResult
create(session: Session, pose: Pose)

Creates and attaches an Anchor at the given pose.
List<UUID>

Retrieves all the UUID instances from Anchor objects that have been persisted by persist that are still present in the local storage.
AnchorCreateResult
load(session: Session, uuid: UUID)

Loads an Anchor from local storage, using the given uuid.
Unit
unpersist(session: Session, uuid: UUID)

Deletes a persisted Anchor denoted by uuid from local storage.

Public functions
Unit

Detaches this anchor.
open operator Boolean
equals(other: Any?)
open Int
suspend UUID

Stores this anchor in the application's local storage so that it can be shared across sessions.

Public properties
StateFlow<Anchor.State>

The current State of this anchor.

Extension functions
ListenableFuture<UUID>

Stores this anchor in the application's local storage so that it can be shared across sessions.

Extension properties
Flowable<Anchor.State>

The current State of this anchor.

Public companion functions

create

Added in 1.0.0-alpha09
fun create(session: Session, pose: Pose): AnchorCreateResult

Creates and attaches an Anchor at the given pose.

import androidx.xr.arcore.Anchor
import androidx.xr.arcore.AnchorCreateIllegalState
import androidx.xr.arcore.AnchorCreateNotAuthorized
import androidx.xr.arcore.AnchorCreateResourcesExhausted
import androidx.xr.arcore.AnchorCreateSuccess
import androidx.xr.arcore.AnchorCreateTrackingUnavailable
import androidx.xr.arcore.AnchorCreateUnsupportedLocation
import androidx.xr.arcore.AnchorLoadInvalidUuid
import androidx.xr.runtime.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.
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 AnchorCreateIllegalState -> {
        // This result indicates the session was in an invalid state, which usually means that
        // the session has been paused or destroyed.
    }
    is AnchorCreateNotAuthorized -> {
        // This result indicates that the activity is lacking sufficient permissions to create
        // an anchor. It is recommended that applications both check for appropriate permissions
        // before attempting to create an Anchor as well as handling this result; it is possible
        // for permissions to be granted initially and then revoked at runtime, so even
        // applications that check for permission in advance can still potentially get this
        // result.
    }
    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.
    }
    is AnchorCreateUnsupportedLocation -> {
        // This result indicates that the underlying runtime does not support creating anchors
        // in this particular location.
    }
    is AnchorLoadInvalidUuid -> {
        // This result only occurs when calling `Anchor.load()` to load a persistent anchor with
        // an invalid UUID.
    }
}
Parameters
session: Session

the Session that is used to create the anchor.
pose: Pose

the Pose that describes the location and orientation of the anchor.
Returns
AnchorCreateResult

a subtype of AnchorCreateResult based on the result of the operation. If the operation is successful, the result will be of type AnchorCreateSuccess with the created Anchor as its property.

getPersistedAnchorUuids

Added in 1.0.0-alpha09
fun getPersistedAnchorUuids(session: Session): List<UUID>

Retrieves all the UUID instances from Anchor objects that have been persisted by persist that are still present in the local storage.

Throws
kotlin.IllegalStateException

if Session.config is set to Config.AnchorPersistenceMode.DISABLED.

load

Added in 1.0.0-alpha09
fun load(session: Session, uuid: UUID): AnchorCreateResult

Loads an Anchor from local storage, using the given uuid. The anchor will attempt to be attached in the same physical location as the anchor that was previously persisted. The uuid should be the return value of a previous call to persist.

Throws
kotlin.IllegalStateException

if Session.config is set to Config.AnchorPersistenceMode.DISABLED.

unpersist

Added in 1.0.0-alpha09
fun unpersist(session: Session, uuid: UUID): Unit

Deletes a persisted Anchor denoted by uuid from local storage.

Throws
kotlin.IllegalStateException

if Session.config is set to Config.AnchorPersistenceMode.DISABLED or the provided uuid is invalid.

Public functions

detach

Added in 1.0.0-alpha09
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 anchor in the application's local storage so that it can be shared across sessions.

Returns
UUID

the UUID that uniquely identifies this anchor.
Throws
kotlin.IllegalStateException

if Session.config is set to Config.AnchorPersistenceMode.DISABLED, or if there was an unexpected error persisting the anchor (e.g. ran out of memory).

Public properties

state

Added in 1.0.0-alpha09
val state: StateFlow<Anchor.State>

The current State of this anchor.

Extension functions

persistAsync

fun Anchor.persistAsync(session: Session): ListenableFuture<UUID>

Stores this anchor in the application's local storage so that it can be shared across sessions.

Returns
ListenableFuture<UUID>

a ListenableFuture that returns a UUID that uniquely identifies this anchor.
Throws
kotlin.IllegalStateException

if Session.config is set to Config.AnchorPersistenceMode.DISABLED, or if there was an unexpected error persisting the anchor (e.g. ran out of memory).

Extension properties

stateAsFlowable

val Anchor.stateAsFlowable: Flowable<Anchor.State>

The current State of this anchor.