[ Web Proxy ]
URL:
Viewing: https://developers.google.com/ar/develop/java/hit-test/developer-guide [Back]  [Original]
Perform hit-tests in your Android app  |  ARCore  |  Google for Developers Skip to main content
ARCore [ARCore]
ARCore Geospatial Creator for Unity Documentation Reference
Search:
ARCore [ARCore]
Send feedback

Perform hit-tests in your Android app Stay organized with collections Save and categorize content based on your preferences.

outlined_flag

Perform a hit-test to determine the correct placement of a 3D object in your scene. Correct placement ensures that the AR content is rendered at the appropriate (apparent) size.

Hit result types

A hit-test can yield four different types of hit results, as shown by the following table.

Hit result type Description Orientation Use case Method calls
Depth (DepthPoint) Uses depth information from the entire scene to determine a points correct depth and orientation Perpendicular to the 3D surface Place a virtual object on an arbitrary surface (not just on floors and walls) ArDepthMode must be enabled for this to work.

Frame.hitTest(), check for DepthPoints in the return list
Plane Hits horizontal and/or vertical surfaces to determine a points correct depth and orientation Perpendicular to the 3D surface Place an object on a plane (floor or wall) using the planes full geometry. Need correct scale immediately. Fallback for the Depth hit-test Frame.hitTest(), check for Planes in the return list
Feature point (Point) Relies on visual features around the point of a user tap to determine a points correct position and orientation Perpendicular to the 3D surface Place an object on an arbitrary surface (not just on floors and walls) Frame.hitTest(), check for Points in the return list
Instant Placement (InstantPlacementPoint) Uses screen space to place content. Initially uses estimated depth provided by the app. Works instantly, but pose and actual depth will change once ARCore is able to determine actual scene geometry +Y pointing up, opposite to gravity Place an object on a plane (floor or wall) using the planes full geometry where fast placement is critical, and the experience can tolerate unknown initial depth and scale Frame.hitTestInstantPlacement(float, float, float)

Perform a standard hit-test

Call Frame.hitTest() to perform a hit-test, using the TapHelper utility to obtain MotionEvents from the AR view.

Java

MotionEvent tap = tapHelper.poll();
if (tap == null) {
  return;
}

if (usingInstantPlacement) {
  // When using Instant Placement, the value in APPROXIMATE_DISTANCE_METERS will determine
  // how far away the anchor will be placed, relative to the camera's view.
  List<HitResult> hitResultList =
      frame.hitTestInstantPlacement(tap.getX(), tap.getY(), APPROXIMATE_DISTANCE_METERS);
  // Hit-test results using Instant Placement will only have one result of type
  // InstantPlacementResult.
} else {
  List<HitResult> hitResultList = frame.hitTest(tap);
  // TODO: Filter hitResultList to find a hit result of interest.
}

Kotlin

val tap = tapHelper.poll() ?: return
val hitResultList =
  if (usingInstantPlacement) {
    // When using Instant Placement, the value in APPROXIMATE_DISTANCE_METERS will determine
    // how far away the anchor will be placed, relative to the camera's view.
    frame.hitTestInstantPlacement(tap.x, tap.y, APPROXIMATE_DISTANCE_METERS)
    // Hit-test results using Instant Placement will only have one result of type
    // InstantPlacementResult.
  } else {
    frame.hitTest(tap)
  }

Filter hit results based on the type youre interested in. For example, if you'd like to focus on DepthPoints:

Java

// Returned hit-test results are sorted by increasing distance from the camera or virtual ray's
// origin.
// The first hit result is often the most relevant when responding to user input.
for (HitResult hit : hitResultList) {
  Trackable trackable = hit.getTrackable();
  if (trackable instanceof DepthPoint) { // Replace with any type of trackable type
    // Do something with this hit result. For example, create an anchor at this point of
    // interest.
    Anchor anchor = hit.createAnchor();
    // TODO: Use this anchor in your AR experience.
    break;
  }
}

Kotlin

// Returned hit-test results are sorted by increasing distance from the camera or virtual ray's
// origin.
// The first hit result is often the most relevant when responding to user input.
val firstHitResult =
  hitResultList.firstOrNull { hit ->
    when (val trackable = hit.trackable!!) {
      is DepthPoint -> true // Replace with any type of trackable type
      else -> false
    }
  }
if (firstHitResult != null) {
  // Do something with this hit result. For example, create an anchor at this point of interest.
  val anchor = firstHitResult.createAnchor()
  // TODO: Use this anchor in your AR experience.
}

Conduct a hit-test using an arbitrary ray and direction

Hit-tests are typically treated as rays from the device or device camera, but you can use Frame.hitTest(float[], int, float[], int) to conduct a hit-test using an arbitrary ray in world space coordinates instead of a screen-space point.

Create an Anchor using the hit result

Once you have a hit result, you can use its pose as input to place AR content in your scene. Use HitResult.createAnchor() to create a new Anchor, ensuring that the content attaches to the underlying Trackable of the hit result. For example, the anchor will remain attached to the detected plane for a Plane hit result, thus appearing to be part of the real world.

Whats next

Send feedback

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2024-10-31 UTC.

Need to tell us more? [[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-10-31 UTC."],[],["A hit-test determines the correct placement of 3D objects in AR scenes. It involves calling `Frame.hitTest()` or `Frame.hitTestInstantPlacement()` with screen coordinates or a custom ray. Hit results include `DepthPoint`, `Plane`, `Point`, and `InstantPlacementPoint`, each suited for different surfaces and scenarios. Results are filtered based on the desired type and are used to create `Anchor`s with `HitResult.createAnchor()`, allowing content to attach to `Trackable` objects and appear in the real world.\n"]]
Web Proxy Viewer  |  New URL  |  Original Page