public final 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
public final class Anchor.State

The representation of the current state of an Anchor.

Public methods
static final @NonNull AnchorCreateResult
create(@NonNull Session session, @NonNull Pose pose)

Creates and attaches an Anchor at the given pose.
final void

Detaches this anchor.
boolean
equals(Object other)
static final @NonNull List<@NonNull UUID>

Retrieves all the UUID instances from Anchor objects that have been persisted by persist that are still present in the local storage.
final @NonNull StateFlow<@NonNull Anchor.State>

The current State of this anchor.
int
static final @NonNull AnchorCreateResult
load(@NonNull Session session, @NonNull UUID uuid)

Loads an Anchor from local storage, using the given uuid.
final @NonNull UUID

Stores this anchor in the application's local storage so that it can be shared across sessions.
static final void
unpersist(@NonNull Session session, @NonNull UUID uuid)

Deletes a persisted Anchor denoted by uuid from local storage.

Extension functions
final @NonNull ListenableFuture<@NonNull UUID>
GuavaAnchor.persistAsync(
    @NonNull Anchor receiver,
    @NonNull Session session
)

Stores this anchor in the application's local storage so that it can be shared across sessions.
final @NonNull Flowable<@NonNull Anchor.State>

The current State of this anchor.

Public methods

create

Added in 1.0.0-alpha09
public static final @NonNull AnchorCreateResult create(@NonNull Session session, @NonNull Pose pose)

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
@NonNull Session session

the Session that is used to create the anchor.
@NonNull Pose pose

the Pose that describes the location and orientation of the anchor.
Returns
@NonNull 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.

detach

Added in 1.0.0-alpha09
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-alpha09
public static final @NonNull List<@NonNull UUID> getPersistedAnchorUuids(@NonNull Session session)

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.

getState

Added in 1.0.0-alpha09
public final @NonNull StateFlow<@NonNull Anchor.State> getState()

The current State of this anchor.

hashCode

public int hashCode()

load

Added in 1.0.0-alpha09
public static final @NonNull AnchorCreateResult load(@NonNull Session session, @NonNull UUID uuid)

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.

persist

public final @NonNull UUID persist()

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

Returns
@NonNull 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).

unpersist

Added in 1.0.0-alpha09
public static final void unpersist(@NonNull Session session, @NonNull UUID uuid)

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.

Extension functions

GuavaAnchor.persistAsync

public final @NonNull ListenableFuture<@NonNull UUID> GuavaAnchor.persistAsync(
    @NonNull Anchor receiver,
    @NonNull Session session
)

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

Returns
@NonNull ListenableFuture<@NonNull 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).

RxJava3AnchorKt.getStateAsFlowable

public final @NonNull Flowable<@NonNull Anchor.State> RxJava3AnchorKt.getStateAsFlowable(@NonNull Anchor receiver)

The current State of this anchor.