Hit-tests place virtual objects in the real world

Platform-specific guides

Android (Kotlin/Java)

• Developer guide

Android NDK (C)

• Developer guide

Unity (AR Foundation)

• Developer guide

AR content must be correctly placed and sized to blend into a scene. Like real-world objects, virtual objects that are further away should appear smaller. You can perform a hit-test (or a raycast in AR Foundation for Unity) 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-tests find intersections between either real-world 3D geometry and a virtual ray consisting of an origin and direction. Rays with the device's camera as the origin are used most commonly, though ARCore includes an API for performing hit-tests with an arbitrary ray in world space coordinates.

Imagine that there is a ray originating from a user’s device camera that extends forward until it hits the 3D geometry of the scene, such as a floor, wall, or object. Once this happens, you receive a list of hit results, or intersections with detected scene geometry. The list is sorted by distance from the device, with the nearest intersection first. This is important because generally you can’t see objects occluded behind other objects, so most of the time the first result is the most significant.

Note: Hit-tests are typically performed as rays from the device or device camera, but it is possible to have an arbitrary ray origin and direction.

Contents of a hit result

An individual hit result is returned as a list with the following information for each result:

• Distance from the ray origin, in meters
• Pose (position and orientation) of the hit result
• The 3D geometry that you hit, in the form of a Trackable

You can then use the desired hit result to realistically place your 3D content using an Anchor.

Hit result types

There are four types of hit results: Depth, plane, feature point, and Instant Placement results. Each has its own use cases and tradeoffs, as shown by the following table.

Note: Depth hit results require Depth supported devices. On non-Depth supported devices, Depth supported devices that do not have depth data yet or on sessions where Depth has been disabled, use plane hit results instead.

Hit result type	Description	Orientation	Use case
Depth	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)
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
Feature 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)
Instant Placement (Persistent Raycast)	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

Device compatibility

Hit-tests work on all ARCore supported devices, but Depth hit-tests will require Depth supported devices.

Use hit results to place AR content

Once you have a hit result, you can use its pose as input to place AR content in your scene.