# AugmentedObject

Artifact: [androidx.xr.arcore:arcore](https://developer.android.com/jetpack/androidx/releases/xr-arcore) [View Source](https://cs.android.com/search?q=file:androidx/xr/arcore/AugmentedObject.kt+class:androidx.xr.arcore.AugmentedObject) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.0.0)

*** ** * ** ***


```
public final class AugmentedObject implements Trackable<@NonNull AugmentedObject.State>
```

<br />

*** ** * ** ***

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 `https://developer.android.com/reference/androidx/xr/runtime/AugmentedObjectCategory` that describes what the object is.

## Summary

| ### Nested types |
|---|
| `public final class https://developer.android.com/reference/androidx/xr/arcore/AugmentedObject.State implements https://developer.android.com/reference/androidx/xr/arcore/Trackable.State` The representation of the current state of an AugmentedObject. |

| ### Public methods |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/AugmentedObject.State>` | `https://developer.android.com/reference/androidx/xr/arcore/AugmentedObject#getState()()` a `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html` that contains the latest `https://developer.android.com/reference/androidx/xr/arcore/AugmentedObject.State` of the AugmentedObject |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Collection.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/AugmentedObject>>` | `https://developer.android.com/reference/androidx/xr/arcore/AugmentedObject#subscribe(androidx.xr.runtime.Session)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session session)` Subscribes to a flow of AugmentedObjects. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/xr/arcore/AugmentedObject#toString()()` Returns a string representation of `https://developer.android.com/reference/androidx/xr/arcore/AugmentedObject` for debugging. |

## Public methods

### getState

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

a `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html` that contains the latest `https://developer.android.com/reference/androidx/xr/arcore/AugmentedObject.State` of the AugmentedObject

### subscribe

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.0.0)

```
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.

```kotlin
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.repeatOnLifecycle
import androidx.xr.arcore.AugmentedObject
import androidx.xr.arcore.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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/runtime/Session session` | the `https://developer.android.com/reference/androidx/xr/runtime/Session` to subscribe to |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Collection.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/xr/arcore/AugmentedObject>>` | a `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html` that emits a collection of AugmentedObjects |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if the given `https://developer.android.com/reference/androidx/xr/runtime/Session`'s `https://developer.android.com/reference/androidx/xr/runtime/Config#augmentedObjectCategories()` is empty |

### toString

```
public @NonNull String toString()
```

Returns a string representation of `https://developer.android.com/reference/androidx/xr/arcore/AugmentedObject` for debugging.

Note: Not intended for production use.