Anchor

Kotlin |Java

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 AnchorResult`	`create(@NonNull Session session, @NonNull Pose pose)` Creates and attaches an `Anchor` at the given `pose`.
`final void`	`detach()` Detaches this anchor.
`boolean`	`equals(Object other)`
`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.
`final @NonNull StateFlow<@NonNull Anchor.State>`	`getState()` the current `State` of this anchor
`int`	`hashCode()`
`static final @NonNull AnchorResult`	`load(@NonNull Session session, @NonNull UUID uuid)` Loads an `Anchor` from local storage, using the given `uuid`.
`final @NonNull UUID`	`persist()` 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.

Public methods

create

Added in 1.0.0-alpha14

public static final @NonNull AnchorResult 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.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.AnchorUnsupportedObjectException
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: AnchorUnsupportedObjectException) {
    // This exception is thrown when attempting to create an anchor from an object that does not
    // implement the Anchorable interface.
} catch (e: AnchorRuntimeFailureException) {
    // This exception is thrown when an unspecified error was encountered in the runtime while
    // attempting to create the anchor.
}

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 AnchorResult`	a subtype of `AnchorResult` based on the result of the operation

Throws
`AnchorCreateResourcesExhausted`	if the runtime has run out of resources while attempting to create the anchor
`AnchorCreateTrackingUnavailable`	if tracking was unavailable while attempting to create the anchor
`AnchorRuntimeFailureException`	if an unspecified error occurred in the runtime while attempting to create the anchor

detach

Added in 1.0.0-alpha14

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-alpha14

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.

Parameters
`@NonNull Session session`	the `Session` to retrieve the persisted anchor UUIDs from

Throws
`IllegalStateException`	if `Session.config` is set to `androidx.xr.runtime.AnchorPersistenceMode.DISABLED`.

getState

Added in 1.0.0-alpha14

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

the current State of this anchor

hashCode

public int hashCode()

load

Added in 1.0.0-alpha14

public static final @NonNull AnchorResult 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.

Parameters
`@NonNull Session session`	the `Session` to load the anchor from
`@NonNull UUID uuid`	the `UUID` of the anchor to load

Throws
`IllegalStateException`	if `Session.config` is set to `AnchorPersistenceMode.DISABLED`
`AnchorInvalidUuidException`	if `uuid` is not a `UUID` currently being tracked by the `Session`
`AnchorCreateResourcesExhausted`	if the runtime has run out of resources while attempting to create the anchor
`AnchorNotAuthorizedException`	if an authorization error occurred while attempting to create the anchor
`AnchorRuntimeFailureException`	if an unspecified error occurred in the runtime while attempting to create the anchor

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
`IllegalStateException`	if `Session.config` is set to `AnchorPersistenceMode.DISABLED`, or if there was an unexpected error persisting the anchor (e.g. ran out of memory)

unpersist

Added in 1.0.0-alpha14

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

Deletes a persisted Anchor denoted by uuid from local storage.

Parameters
`@NonNull Session session`	the `Session` to unpersist the anchor from
`@NonNull UUID uuid`	the `UUID` of the anchor to unpersist

Throws
`IllegalStateException`	if `Session.config` is set to `AnchorPersistenceMode.DISABLED`
`AnchorInvalidUuidException`	if the provided `uuid` is invalid

Anchor

Summary

Nested types

Public methods

Public methods

create

detach

equals

getPersistedAnchorUuids

getState

hashCode

load

persist

unpersist