AugmentedObject

public final class AugmentedObject implements Trackable

A representation of a physical object in real space.

Augmented Objects are detected by the XR system and provide information about their pose, extents, and label.

The pose represents the position and orientation of the center point of the object.

The extents describe the size of the object, as axis-aligned half-widths.

The label is an instance of androidx.xr.runtime.AugmentedObjectCategory that describes what the object is.

Summary

Nested types
public final class AugmentedObject.State implements Trackable.State

The representation of the current state of an AugmentedObject.

Public methods
@NonNull AnchorCreateResult

Creates an androidx.xr.arcore.runtime.Anchor that is attached to this trackable, using the given initial pose.
@NonNull StateFlow<@NonNull AugmentedObject.State>

A StateFlow that contains the latest State of the AugmentedObject.
static final @NonNull StateFlow<@NonNull Collection<@NonNull AugmentedObject>>

Subscribes to a flow of AugmentedObjects.

Public methods

createAnchor

public @NonNull AnchorCreateResult createAnchor(@NonNull Pose pose)

Creates an androidx.xr.arcore.runtime.Anchor that is attached to this trackable, using the given initial pose.

Throws
kotlin.IllegalStateException

if Session.config.augmentedObjectCategories is empty.

getState

public @NonNull StateFlow<@NonNull AugmentedObject.State> getState()

A StateFlow that contains the latest State of the AugmentedObject.

import androidx.lifecycle.Lifecycle
import androidx.lifecycle.repeatOnLifecycle
import androidx.xr.arcore.AugmentedObject
import androidx.xr.runtime.TrackingState
import androidx.xr.runtime.math.Pose
import androidx.xr.scenecore.scene

// Use a coroutine to listen to changes to the set of detected objects.
yourCoroutineScope.launch {
    val activeObjects = mutableMapOf<AugmentedObject, Job>()

    lifecycle.repeatOnLifecycle(Lifecycle.State.RESUMED) {
        val supervisor = SupervisorJob()
        val supervisorScope = CoroutineScope(yourCoroutineScope.coroutineContext + supervisor)
        try {
            AugmentedObject.subscribe(session).collect { augmentedObjects ->
                // The list of detected objects has changed.
                for (obj in augmentedObjects) {

                    // If an object doesn't exist in our set of active objects, set up a
                    // coroutine to respond to its state changes.
                    if (!activeObjects.contains(obj)) {
                        val job =
                            supervisorScope.launch {
                                obj.state.collect {
                                    // if the object is not currently reporting as tracked, then
                                    // we don't want to render it.
                                    if (it.trackingState != TrackingState.TRACKING)
                                        return@collect

                                    // Transform the pose from its original coordinate space to
                                    // one suitable for rendering to the display.
                                    val pose =
                                        it.centerPose.let { p ->
                                            session.scene.perceptionSpace.transformPoseTo(
                                                p,
                                                session.scene.activitySpace,
                                            )
                                        }

                                    // This function is where you'll actually render the object
                                    // to the display.
                                    renderFunction(pose, it.extents, it.category)
                                }
                            }
                        activeObjects[obj] = job
                    }

                    // Likewise, if a object exists in the `activeObjects` map, but not in our
                    // `augmentedObjects` list, it needs to be removed, and its corresponding
                    // job canceled.
                    for (obj in activeObjects.keys.toList()) {
                        if (augmentedObjects.none { it == obj }) {
                            activeObjects.remove(obj)?.cancel()
                        }
                    }
                }
            }
        } finally {
            // cancel any coroutines still running.
            supervisor.cancel()
            activeObjects.clear()
        }
    }
}

subscribe

Added in 1.0.0-alpha09
public static final @NonNull StateFlow<@NonNull Collection<@NonNull AugmentedObject>> subscribe(@NonNull Session session)

Subscribes to a flow of AugmentedObjects.

The flow emits a new collection of AugmentedObjects whenever the underlying XR system detects new objects or updates the state of existing ones. This typically happens on each frame update of the XR system.

import androidx.lifecycle.Lifecycle
import androidx.lifecycle.repeatOnLifecycle
import androidx.xr.arcore.AugmentedObject
import androidx.xr.runtime.TrackingState
import androidx.xr.runtime.math.Pose
import androidx.xr.scenecore.scene

// Use a coroutine to listen to changes to the set of detected objects.
yourCoroutineScope.launch {
    val activeObjects = mutableMapOf<AugmentedObject, Job>()

    lifecycle.repeatOnLifecycle(Lifecycle.State.RESUMED) {
        val supervisor = SupervisorJob()
        val supervisorScope = CoroutineScope(yourCoroutineScope.coroutineContext + supervisor)
        try {
            AugmentedObject.subscribe(session).collect { augmentedObjects ->
                // The list of detected objects has changed.
                for (obj in augmentedObjects) {

                    // If an object doesn't exist in our set of active objects, set up a
                    // coroutine to respond to its state changes.
                    if (!activeObjects.contains(obj)) {
                        val job =
                            supervisorScope.launch {
                                obj.state.collect {
                                    // if the object is not currently reporting as tracked, then
                                    // we don't want to render it.
                                    if (it.trackingState != TrackingState.TRACKING)
                                        return@collect

                                    // Transform the pose from its original coordinate space to
                                    // one suitable for rendering to the display.
                                    val pose =
                                        it.centerPose.let { p ->
                                            session.scene.perceptionSpace.transformPoseTo(
                                                p,
                                                session.scene.activitySpace,
                                            )
                                        }

                                    // This function is where you'll actually render the object
                                    // to the display.
                                    renderFunction(pose, it.extents, it.category)
                                }
                            }
                        activeObjects[obj] = job
                    }

                    // Likewise, if a object exists in the `activeObjects` map, but not in our
                    // `augmentedObjects` list, it needs to be removed, and its corresponding
                    // job canceled.
                    for (obj in activeObjects.keys.toList()) {
                        if (augmentedObjects.none { it == obj }) {
                            activeObjects.remove(obj)?.cancel()
                        }
                    }
                }
            }
        } finally {
            // cancel any coroutines still running.
            supervisor.cancel()
            activeObjects.clear()
        }
    }
}
Parameters
@NonNull Session session

The Session to subscribe to.
Throws
kotlin.IllegalStateException

if the given Session's Config.augmentedObjectCategories is empty.