AugmentedObject

class AugmentedObject : 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

The representation of the current state of an AugmentedObject.

Public companion functions
StateFlow<Collection<AugmentedObject>>
subscribe(session: Session)

Subscribes to a flow of AugmentedObjects.

Public functions
open AnchorCreateResult

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

Public properties
open StateFlow<AugmentedObject.State>

A StateFlow that contains the latest State of the AugmentedObject.

Public companion functions

subscribe

Added in 1.0.0-alpha09
fun subscribe(session: Session): StateFlow<Collection<AugmentedObject>>

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
session: Session

The Session to subscribe to.
Throws
kotlin.IllegalStateException

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

Public functions

createAnchor

open fun createAnchor(pose: Pose): AnchorCreateResult

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.

Public properties

state

open val state: StateFlow<AugmentedObject.State>

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()
        }
    }
}