Android NDK 앱에서 Hit Test 실행
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
히트 테스트를 실행하여 장면에서 3D 개체가 올바르게 배치되는지 확인합니다. 올바른 위치에 배치해야 AR 콘텐츠가 적절한 (눈에 띄는) 크기로 렌더링됩니다.
조회 결과 유형
아래 표와 같이 Hit Test는 네 가지 유형의 조회 결과를 생성할 수 있습니다.
ArFrame_hitTest를 호출하여 히트 테스트를 실행합니다.
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);
}
관심 있는 유형을 기준으로 조회수 결과를 필터링합니다. 예를 들어 ArPlane에 집중하려면 다음을 실행합니다.
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);
임의의 광선과 방향을 사용하여 히트 테스트 수행
Hit Test는 일반적으로 기기 또는 기기 카메라의 광선으로 취급되지만, ArFrame_hitTestRay를 사용하여 화면 공간 지점 대신 공간 좌표에서 임의의 광선을 사용하여 Hit Test를 실행할 수 있습니다.
HitResult에 앵커 연결
조회 결과가 있으면 해당 포즈를 입력으로 사용하여 장면에 AR 콘텐츠를 배치할 수 있습니다. ArHitResult_acquireNewAnchor를 사용하여 조회 위치에 새 앵커를 만듭니다.
다음 단계
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-07-26(UTC)
[null,null,["최종 업데이트: 2025-07-26(UTC)"],[[["\u003cp\u003eUse hit-tests to accurately place 3D objects in your AR scene by determining their correct position and orientation in the real world.\u003c/p\u003e\n"],["\u003cp\u003eHit-tests offer four types of results: Depth, Plane, Feature Point, and Instant Placement, each suited for different placement scenarios and surface types.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eArFrame_hitTest\u003c/code\u003e and \u003ccode\u003eArFrame_hitTestInstantPlacement\u003c/code\u003e are the primary methods used to perform hit-tests, with the former focusing on precision and the latter on speed.\u003c/p\u003e\n"],["\u003cp\u003eOnce a hit-test is performed, filter the results based on your desired trackable type (e.g., planes) and create an anchor to attach your AR content to the hit location.\u003c/p\u003e\n"],["\u003cp\u003eAnchors are created from successful hit-tests using \u003ccode\u003eArHitResult_acquireNewAnchor\u003c/code\u003e, allowing virtual objects to remain persistently placed in the real world.\u003c/p\u003e\n"]]],["Hit-tests determine 3D object placement in AR scenes, ensuring correct size. Four result types exist: Depth (for arbitrary surfaces), Plane (for floors/walls), Feature Point (for user-tapped surfaces), and Instant Placement (for rapid, initially estimated placement). Use `ArFrame_hitTest` or `ArFrame_hitTestInstantPlacement` to perform hit tests and filter results based on `ArTrackableType`. `ArFrame_hitTestRay` enables tests with arbitrary rays. `ArHitResult_acquireNewAnchor` creates an Anchor at the hit location for AR content placement.\n"],null,["# Perform hit-tests in your Android NDK app\n\nPerform a [hit-test](/ar/develop/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.\n\nHit result types\n----------------\n\nA hit-test can yield four different types of hit results, as shown by the following table.\n\n| Hit result type | Description | Orientation | Use case | Method calls |\n|---------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Depth ([`AR_TRACKABLE_DEPTH_POINT`](/ar/reference/c/group/ar-trackable#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`](/ar/reference/c/group/ar-config#ardepthmode) must be enabled for this to work.** [`ArFrame_hitTest`](/ar/reference/c/group/ar-frame#arframe_hittest), check for [`ArDepthPoint`](/ar/reference/c/group/ar-depth-point#ardepthpoint)s in the return list |\n| Plane ([`AR_TRACKABLE_PLANE`](/ar/reference/c/group/ar-trackable#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`](/ar/reference/c/group/ar-frame#arframe_hittest), check for [`ArPlane`](/ar/reference/c/group/ar-plane)s in the return list |\n| Feature point ([`AR_TRACKABLE_POINT`](/ar/reference/c/group/ar-trackable#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`](/ar/reference/c/group/ar-frame#arframe_hittest), check for [`ArPoint`](/ar/reference/c/group/ar-point)s in the return list |\n| Instant Placement ([`AR_TRACKABLE_INSTANT_PLACEMENT_POINT`](/ar/reference/c/group/ar-trackable#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`](/ar/reference/c/group/ar-frame#arframe_hittestinstantplacement) |\n\nPerform a standard hit-test\n---------------------------\n\nCall [`ArFrame_hitTest`](/ar/reference/c/group/ar-frame#arframe_hittest) to perform a hit test. \n\n```c\nArHitResultList* hit_result_list = NULL;\nArHitResultList_create(ar_session, &hit_result_list);\nCHECK(hit_result_list);\nif (is_instant_placement_enabled) {\n ArFrame_hitTestInstantPlacement(ar_session, ar_frame, x, y,\n k_approximate_distance_meters,\n hit_result_list);\n} else {\n ArFrame_hitTest(ar_session, ar_frame, x, y, hit_result_list);\n}\n```\n\nFilter hit results based on the type you're interested in. For example, if you'd like to focus on `ArPlane`s: \n\n```c\nint32_t hit_result_list_size = 0;\nArHitResultList_getSize(ar_session, hit_result_list, &hit_result_list_size);\n\n// Returned hit-test results are sorted by increasing distance from the camera\n// or virtual ray's origin. The first hit result is often the most relevant\n// when responding to user input.\nArHitResult* ar_hit_result = NULL;\nfor (int32_t i = 0; i \u003c hit_result_list_size; ++i) {\n ArHitResult* ar_hit = NULL;\n ArHitResult_create(ar_session, &ar_hit);\n ArHitResultList_getItem(ar_session, hit_result_list, i, ar_hit);\n\n if (ar_hit == NULL) {\n LOGE(\"No item was hit.\");\n return;\n }\n\n ArTrackable* ar_trackable = NULL;\n ArHitResult_acquireTrackable(ar_session, ar_hit, &ar_trackable);\n ArTrackableType ar_trackable_type = AR_TRACKABLE_NOT_VALID;\n ArTrackable_getType(ar_session, ar_trackable, &ar_trackable_type);\n // Creates an anchor if a plane was hit.\n if (ar_trackable_type == AR_TRACKABLE_PLANE) {\n // Do something with this hit result. For example, create an anchor at\n // this point of interest.\n ArAnchor* anchor = NULL;\n ArHitResult_acquireNewAnchor(ar_session, ar_hit, &anchor);\n\n // TODO: Use this anchor in your AR experience.\n\n ArAnchor_release(anchor);\n ArHitResult_destroy(ar_hit);\n ArTrackable_release(ar_trackable);\n break;\n }\n ArHitResult_destroy(ar_hit);\n ArTrackable_release(ar_trackable);\n}\nArHitResultList_destroy(hit_result_list);\n```\n\nConduct a hit-test using an arbitrary ray and direction\n-------------------------------------------------------\n\nHit-tests are typically treated as rays from the device or device camera, but you can use [`ArFrame_hitTestRay`](/ar/reference/c/group/ar-frame#arframe_hittestray) to conduct a hit-test using an arbitrary ray in world space coordinates instead of a screen-space point.\n\nAttach an Anchor to a HitResult\n-------------------------------\n\nOnce you have a hit result, you can use its pose as input to [place AR content](/ar/develop/anchors) in your scene. Use [`ArHitResult_acquireNewAnchor`](/ar/reference/c/group/ar-hit-result#arhitresult_acquirenewanchor) to create a new [Anchor](/ar/develop/anchors) at the hit location.\n\nWhat's next\n-----------\n\n- Check out the [`hello_ar_c`](https://github.com/google-ar/arcore-android-sdk/tree/master/samples/hello_ar_c) sample app on GitHub."]]
