# androidx.xr.arcore

*** ** * ** ***

## Interfaces

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchorable` | Trackable object that can have an `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor` attached. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Trackable` | An object that ARCore for Jetpack XR can track. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Trackable.State` | The subset of data that is common to the state of all `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Trackable` instances. |

## Classes

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor` | An anchor describes a fixed location and orientation in the real world. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor.State` | The representation of the current state of an `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor`. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorCreateResourcesExhausted` | Result of an unsuccessful attempt to create an `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor`. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorCreateSuccess` | Result of a successful attempt to create an anchor. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorCreateTrackingUnavailable` | Result of an unsuccessful attempt to create an `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Anchor`. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorResult` | Result of an attempt to create an anchor. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/ArDevice` | Contains the information of the device that locates it with respect to the real world. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/ArDevice.State` | Contains the current state of the AR Device tracking. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AugmentedImage` | Describes the system's current best knowledge of a real-world image |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AugmentedImage.State` | The representation of the current state of an `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AugmentedImage`. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AugmentedObject` | A representation of a physical object in real space. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AugmentedObject.State` | The representation of the current state of an AugmentedObject. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/CreateGeospatialPoseFromPoseInternalError` | Result of an unsuccessful `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#createGeospatialPoseFromPose(androidx.xr.runtime.math.Pose)` call. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/CreateGeospatialPoseFromPoseNotTracking` | Result of an unsuccessful `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#createGeospatialPoseFromPose(androidx.xr.runtime.math.Pose)` call. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/CreateGeospatialPoseFromPoseResult` | Result of a `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#createGeospatialPoseFromPose(androidx.xr.runtime.math.Pose)` call. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/CreateGeospatialPoseFromPoseSuccess` | Result of a successful `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#createGeospatialPoseFromPose(androidx.xr.runtime.math.Pose)` call. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/CreatePoseFromGeospatialPoseInternalError` | Result of an unsuccessful `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#createPoseFromGeospatialPose(androidx.xr.runtime.math.GeospatialPose)` call. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/CreatePoseFromGeospatialPoseNotTracking` | Result of an unsuccessful `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#createPoseFromGeospatialPose(androidx.xr.runtime.math.GeospatialPose)` call. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/CreatePoseFromGeospatialPoseResult` | Result of a call to `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#createPoseFromGeospatialPose(androidx.xr.runtime.math.GeospatialPose)`. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/CreatePoseFromGeospatialPoseSuccess` | Result of a successful `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#createPoseFromGeospatialPose(androidx.xr.runtime.math.GeospatialPose)` call. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Depth` | Depth information corresponding to a specific `https://developer.android.com/reference/kotlin/androidx/xr/arcore/RenderViewpoint`. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Depth.State` | Contains the current state of depth tracking. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Eye` | A representation of a user's eye. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Eye.State` | The representation of the current state of an `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Eye`. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Face` | Contains the tracking information of a detected human face. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Face.State` | The representation of the current state of `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Face`. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/FaceBlendShapeType` | Type of face blend shape. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/FaceConfidenceRegion` | Regions of face tracking confidence. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial` | Localization ability in Earth-relative coordinates. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial.GeospatialTrackingState` | Describes the state of Geospatial. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial.State` | State of Geospatial at a specific point in time. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/GeospatialSurface` | The type of surface on which to create an anchor. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Hand` | Contains the tracking information of one of the user's hands. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Hand.State` | The representation of the current state of a `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Hand`. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/HitResult` | Intersection between a ray and estimated real-world geometry. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/PerceptionState` | State of ARCore for Jetpack XR at a specific point in time. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane` | Describes the system's current best knowledge of a real-world planar surface. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane.State` | The representation of the current state of a `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane`. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/PlaneLabel` | A semantic description of a `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane`. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/PlaneType` | A simple summary of the normal vector of a `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Plane`. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/QrCode` | Describes the current best knowledge of a real-world QR code |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/QrCode.State` | The representation of the current state of a `https://developer.android.com/reference/kotlin/androidx/xr/arcore/QrCode`. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/RenderViewpoint` | Viewpoint used for rendering. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/RenderViewpoint.State` | Class that contains the current state of the render viewpoint. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation` | Base class for all tracked Spatial Annotations (Quads, Points, Masks, etc.). |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation.State` | State containing physical properties that update frame-to-frame. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationId` | A strongly-typed identifier mapped to a requested `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotation`. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationImageFormat` | Enumeration of supported input camera image formats. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationQuadAlignment` | Enumeration of supported 3D quad alignment modes. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationTrackingOptions` | Configuration options required to start tracking Spatial Annotations. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationTrackingOptions.Builder` | Builder for `https://developer.android.com/reference/kotlin/androidx/xr/arcore/SpatialAnnotationTrackingOptions`. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Tilt` | Vertical tilt state of the device. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/TiltGesture.State` | Tilt state and transition progress of the device. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/TrackingState` | Describes the state of the tracking performed. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/VpsAvailabilityAvailable` | Result of a successful `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#checkVpsAvailability(kotlin.Double,kotlin.Double)` call. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/VpsAvailabilityErrorInternal` | Result of an unsuccessful `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#checkVpsAvailability(kotlin.Double,kotlin.Double)` call. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/VpsAvailabilityNetworkError` | Result of an unsuccessful `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#checkVpsAvailability(kotlin.Double,kotlin.Double)` call. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/VpsAvailabilityNotAuthorized` | Result of an unsuccessful `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#checkVpsAvailability(kotlin.Double,kotlin.Double)` call. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/VpsAvailabilityResourceExhausted` | Result of an unsuccessful `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#checkVpsAvailability(kotlin.Double,kotlin.Double)` call. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/VpsAvailabilityResult` | Result of a `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#checkVpsAvailability(kotlin.Double,kotlin.Double)` call. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/VpsAvailabilityUnavailable` | Result of a successful `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Geospatial#checkVpsAvailability(kotlin.Double,kotlin.Double)` call. |

## Exceptions

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorInvalidUuidException` | Anchor was not loaded from a valid UUID. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorNotAuthorizedException` | Anchor was not created due to an authorization error. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorRuntimeFailureException` | Anchor was not created due to a runtime failure. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/AnchorUnsupportedLocationException` | Anchor was not created because the provided location is unsupported. |

## Objects

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/TiltGesture` | Container for device tilt gesture detection logic and the `https://developer.android.com/reference/kotlin/androidx/xr/arcore/Tilt` state representation. |

## Annotations

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/ExperimentalGesturesApi` | Marks declarations that are part of the experimental Tilt Gesture API. |

## Enums

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/HandJointType` | Type of hand joint. |
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/HandSide` | The handedness of the user's hand. |

## Top-level functions summary

|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/xr/arcore/HitResult>` | `https://developer.android.com/reference/kotlin/androidx/xr/arcore/package-summary#hitTest(androidx.xr.runtime.Session,androidx.xr.runtime.math.Ray)(session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session, ray: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Ray)` Performs a hit-test using the given `https://developer.android.com/reference/kotlin/androidx/xr/arcore/package-summary#hitTest(androidx.xr.runtime.Session,androidx.xr.runtime.math.Ray)`. |

## Extension properties summary

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/xr/arcore/PerceptionState?` | `https://developer.android.com/reference/kotlin/androidx/xr/runtime/CoreState.https://developer.android.com/reference/kotlin/androidx/xr/arcore/package-summary#(androidx.xr.runtime.CoreState).perceptionState()` State of the perception system at a specific point in time, corresponding to a `https://developer.android.com/reference/kotlin/androidx/xr/runtime/CoreState`. |

## Top-level functions

### hitTest

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/Interaction.kt+function:hitTest) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.0.0)

```
fun hitTest(session: Session, ray: Ray): List<HitResult>
```

Performs a hit-test using the given `https://developer.android.com/reference/kotlin/androidx/xr/arcore/package-summary#hitTest(androidx.xr.runtime.Session,androidx.xr.runtime.math.Ray)`.

A hit-test is a method of calculating the intersection of a ray with objects tracked by the session. Conducting a hit-test results in a list of hit objects, in other words, a hit-test does not stop at the first object hit.

```kotlin
import androidx.xr.arcore.Anchor
import androidx.xr.arcore.AnchorResult
import androidx.xr.arcore.ArDevice
import androidx.xr.arcore.Plane
import androidx.xr.arcore.PlaneLabel
import androidx.xr.arcore.hitTest
import androidx.xr.runtime.math.Pose
import androidx.xr.runtime.math.Ray
import androidx.xr.scenecore.scene

val arDevice = ArDevice.getInstance(session)

// Assume hitOrigin and hitDirection are in Activity Space.
// We need to transform the ray into Perception Space for hitTest.

// Transform the origin point from Activity Space to Perception Space.
val perceptionOrigin =
    session.scene.activitySpace
        .transformPoseTo(Pose(hitOrigin), session.scene.perceptionSpace)
        .translation

// Transform the direction vector from Activity Space to Perception Space.
val perceptionDirection =
    session.scene.activitySpace
        .transformPoseTo(Pose(hitDirection), session.scene.perceptionSpace)
        .translation
        .toNormalized() // Ensure the direction is normalized after transformation.

val ray = Ray(perceptionOrigin, perceptionDirection)

hitTest(session, ray)
    // Use a valid plane label as a test to filter out any unreliable hits.
    .firstOrNull { (it.trackable as? Plane?)?.state?.value?.label != PlaneLabel.UNKNOWN }
    ?.let { hitResult ->
        // Do something with the hit result, like create an anchor representing where the ray
        // intersected the plane. The hitResult.hitPose is in Perception Space.
        val anchorResult = Anchor.create(session, hitResult.hitPose)

        // Anchor creation can fail, so it is important to properly handle the return value of
        // and `Anchor.create()` call. See `Anchor.create()` for more information.
        yourAnchorResultHandler(anchorResult)

        // If rendering is needed, transform hitResult.hitPose from Perception Space
        // to the desired Scene Space (e.g., Activity Space).
        val activitySpaceHitPose =
            session.scene.perceptionSpace.transformPoseTo(
                hitResult.hitPose,
                session.scene.activitySpace,
            )
        renderSomething(activitySpaceHitPose)
    }
```

| Parameters |
|---|---|
| `session: https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` | the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session` to perform the hit-test in |
| `ray: https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Ray` | the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/math/Ray` to use for the hit-test |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/xr/arcore/HitResult>` | a list of `https://developer.android.com/reference/kotlin/androidx/xr/arcore/HitResult` objects, sorted by distance from the origin of the ray, nearest to farthest |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/xr/runtime/Session#config()` is set to `https://developer.android.com/reference/kotlin/androidx/xr/runtime/PlaneTrackingMode#DISABLED()` |

## Extension properties

### CoreState.perceptionState

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/PerceptionStateExtender.kt+symbol:perceptionState) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/xr-arcore#1.0.0)

```
val CoreState.perceptionState: PerceptionState?
```

State of the perception system at a specific point in time, corresponding to a `https://developer.android.com/reference/kotlin/androidx/xr/runtime/CoreState`.

This extension property provides a consistent snapshot of all available perception data (e.g., hands, eyes, trackables, depth, etc.) for the `https://developer.android.com/reference/kotlin/androidx/xr/runtime/CoreState#timeMark()` of the receiver. All perception state objects within a single `https://developer.android.com/reference/kotlin/androidx/xr/arcore/PerceptionState` instance are synchronized to that particular moment in time.