Perform hit-tests in your Android NDK app

  • Perform a hit-test to determine the correct placement of a 3D object in your scene, ensuring appropriate size rendering.

  • A hit-test can yield four different types of results: Depth, Plane, Feature point, and Instant Placement, each with specific use cases and descriptions.

  • Use ArFrame_hitTest for a standard hit-test or ArFrame_hitTestRay for a hit-test using an arbitrary ray.

  • You can filter hit results based on the type you are interested in, such as focusing on ArPlanes.

  • Attach an Anchor to a HitResult using ArHitResult_acquireNewAnchor to place AR content at the hit location.

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 (AR_TRACKABLE_DEPTH_POINT) Uses depth information from the entire scene to determine a point’s 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.

ArFrame_hitTest, check for ArDepthPoints in the return list
Plane (AR_TRACKABLE_PLANE) Hits horizontal and/or vertical surfaces to determine a point’s correct depth and orientation Perpendicular to the 3D surface Place an object on a plane (floor or wall) using the plane’s full geometry. Need correct scale immediately. Fallback for the Depth hit-test ArFrame_hitTest, check for ArPlanes in the return list
Feature point (AR_TRACKABLE_POINT) Relies on visual features around the point of a user tap to determine a point’s correct position and orientation Perpendicular to the 3D surface Place an object on an arbitrary surface (not just on floors and walls) ArFrame_hitTest, check for ArPoints in the return list
Instant Placement (AR_TRACKABLE_INSTANT_PLACEMENT_POINT) 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 plane’s full geometry where fast placement is critical, and the experience can tolerate unknown initial depth and scale ArFrame_hitTestInstantPlacement

Perform a standard hit-test

Call ArFrame_hitTest to perform a hit test.

ArHitResultList* hit_result_list = NULL;
ArHitResultList_create(ar_session, &hit_result_list);
CHECK(hit_result_list);
if (is_instant_placement_enabled) {
  ArFrame_hitTestInstantPlacement(ar_session, ar_frame, x, y,
                                  k_approximate_distance_meters,
                                  hit_result_list);
} else {
  ArFrame_hitTest(ar_session, ar_frame, x, y, hit_result_list);
}

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

int32_t hit_result_list_size = 0;
ArHitResultList_getSize(ar_session, hit_result_list, &hit_result_list_size);

// 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.
ArHitResult* ar_hit_result = NULL;
for (int32_t i = 0; i < hit_result_list_size; ++i) {
  ArHitResult* ar_hit = NULL;
  ArHitResult_create(ar_session, &ar_hit);
  ArHitResultList_getItem(ar_session, hit_result_list, i, ar_hit);

  if (ar_hit == NULL) {
    LOGE("No item was hit.");
    return;
  }

  ArTrackable* ar_trackable = NULL;
  ArHitResult_acquireTrackable(ar_session, ar_hit, &ar_trackable);
  ArTrackableType ar_trackable_type = AR_TRACKABLE_NOT_VALID;
  ArTrackable_getType(ar_session, ar_trackable, &ar_trackable_type);
  // Creates an anchor if a plane was hit.
  if (ar_trackable_type == AR_TRACKABLE_PLANE) {
    // Do something with this hit result. For example, create an anchor at
    // this point of interest.
    ArAnchor* anchor = NULL;
    ArHitResult_acquireNewAnchor(ar_session, ar_hit, &anchor);

    // TODO: Use this anchor in your AR experience.

    ArAnchor_release(anchor);
    ArHitResult_destroy(ar_hit);
    ArTrackable_release(ar_trackable);
    break;
  }
  ArHitResult_destroy(ar_hit);
  ArTrackable_release(ar_trackable);
}
ArHitResultList_destroy(hit_result_list);

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 ArFrame_hitTestRay to conduct a hit-test using an arbitrary ray in world space coordinates instead of a screen-space point.

Attach an Anchor to a HitResult

Once you have a hit result, you can use its pose as input to place AR content in your scene. Use ArHitResult_acquireNewAnchor to create a new Anchor at the hit location.

What’s next