تست های آماری را در برنامه اندروید خود انجام دهید
با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
برای تعیین قرارگیری صحیح یک شی 3 بعدی در صحنه خود یک تست ضربه انجام دهید. قرارگیری صحیح تضمین می کند که محتوای AR در اندازه مناسب (ظاهری) ارائه می شود.
انواع نتیجه را بزنید
همانطور که در جدول زیر نشان داده شده است، یک تست ضربه می تواند چهار نوع مختلف از نتایج ضربه را به دست دهد.
نوع نتیجه را بزنید | توضیحات | جهت گیری | مورد استفاده | فراخوانی روش |
---|
عمق ( DepthPoint ) | از اطلاعات عمق کل صحنه برای تعیین عمق و جهت صحیح یک نقطه استفاده می کند | عمود بر سطح سه بعدی | یک شی مجازی را روی یک سطح دلخواه (نه فقط روی زمین و دیوار) قرار دهید. | برای این کار باید ArDepthMode فعال باشد.
Frame.hitTest(…) را در لیست برگشتی، DepthPoint را بررسی کنید |
Plane | برای تعیین عمق و جهت صحیح نقطه، به سطوح افقی و/یا عمودی برخورد می کند | عمود بر سطح سه بعدی | یک شی را با استفاده از هندسه کامل هواپیما روی یک صفحه (کف یا دیوار) قرار دهید. فوراً به مقیاس صحیح نیاز دارید. جایگزینی برای آزمون ضربه عمق | Frame.hitTest(…) Plane در لیست بازگشتی بررسی کنید |
نقطه ویژگی ( Point ) | برای تعیین موقعیت و جهت گیری صحیح یک نقطه، به ویژگی های بصری در اطراف نقطه ضربه کاربر متکی است | عمود بر سطح سه بعدی | یک شی را روی یک سطح دلخواه (نه فقط روی زمین و دیوار) قرار دهید. | Frame.hitTest(…) ، Point s را در لیست برگشتی بررسی کنید |
Instant Placement ( InstantPlacementPoint ) | از فضای صفحه برای قرار دادن محتوا استفاده می کند. در ابتدا از عمق تخمینی ارائه شده توسط برنامه استفاده می کند. فورا کار می کند، اما زمانی که ARCore بتواند هندسه صحنه واقعی را تعیین کند ژست و عمق واقعی تغییر می کند. | +Y به سمت بالا، مخالف گرانش | یک شی را بر روی یک صفحه (کف یا دیوار) با استفاده از هندسه کامل هواپیما قرار دهید، جایی که قرارگیری سریع بسیار مهم است، و تجربه می تواند عمق و مقیاس اولیه ناشناخته را تحمل کند. | Frame.hitTestInstantPlacement(float, float, float) |
با استفاده از ابزار TapHelper
برای به دست آوردن MotionEvent
از نمای AR، Frame.hitTest()
را برای اجرای یک تست ضربه فراخوانی کنید.
جاوا
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.
}
کاتلین
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)
}
نتایج ضربه را بر اساس نوع مورد علاقه خود فیلتر کنید. برای مثال، اگر می خواهید روی DepthPoint
s تمرکز کنید:
جاوا
// 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;
}
}
کاتلین
// 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.
}
یک تست ضربه با استفاده از یک پرتو و جهت دلخواه انجام دهید
تستهای ضربه معمولاً بهعنوان پرتوهای دستگاه یا دوربین دستگاه تلقی میشوند، اما میتوانید از Frame.hitTest(float[], int, float[], int)
برای انجام تست ضربه با استفاده از یک پرتو دلخواه در مختصات فضای جهان استفاده کنید. از یک نقطه فضای صفحه نمایش.
با استفاده از نتیجه ضربه یک Anchor ایجاد کنید
هنگامی که یک نتیجه موفق به دست آوردید، می توانید از حالت آن به عنوان ورودی برای قرار دادن محتوای AR در صحنه خود استفاده کنید. از HitResult.createAnchor()
برای ایجاد یک Anchor
جدید استفاده کنید و اطمینان حاصل کنید که محتوا به Trackable
زیرین نتیجه ضربه متصل می شود. به عنوان مثال، لنگر برای نتیجه ضربه هواپیما به هواپیمای شناسایی شده متصل میماند، بنابراین به نظر میرسد که بخشی از دنیای واقعی است.
بعدش چی
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-07-25 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-07-25 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eHit-tests determine correct placement of 3D objects in AR scenes by identifying real-world surfaces and their positions.\u003c/p\u003e\n"],["\u003cp\u003eThere are four types of hit-test results: Depth, Plane, Feature Point, and Instant Placement, each with its own characteristics and use cases.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers can filter hit-test results to focus on specific surface types like planes or depth points for precise object placement.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eHitResult.createAnchor()\u003c/code\u003e enables the creation of anchors at the identified hit points, allowing virtual content to be attached to real-world surfaces.\u003c/p\u003e\n"],["\u003cp\u003eStandard and arbitrary ray hit-tests are available, offering flexibility in how virtual objects are positioned within the AR environment.\u003c/p\u003e\n"]]],["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"],null,["# Perform hit-tests in your Android 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 ([`DepthPoint`](/ar/reference/java/com/google/ar/core/DepthPoint)) | 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.** [`Frame.hitTest(...)`](/ar/reference/java/com/google/ar/core/Frame#hitTest-motionEvent), check for [`DepthPoint`](/ar/reference/java/com/google/ar/core/DepthPoint)s in the return list |\n| [`Plane`](/ar/reference/java/com/google/ar/core/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 | [`Frame.hitTest(...)`](/ar/reference/java/com/google/ar/core/Frame#hitTest-motionEvent), check for [`Plane`](/ar/reference/java/com/google/ar/core/Plane)s in the return list |\n| Feature point ([`Point`](/ar/reference/java/com/google/ar/core/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) | [`Frame.hitTest(...)`](/ar/reference/java/com/google/ar/core/Frame#hitTest-motionEvent), check for [`Point`](/ar/reference/java/com/google/ar/core/Point)s in the return list |\n| Instant Placement ([`InstantPlacementPoint`](/ar/reference/java/com/google/ar/core/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 plane's full geometry where fast placement is critical, and the experience can tolerate unknown initial depth and scale | [`Frame.hitTestInstantPlacement(float, float, float)`](/ar/reference/java/com/google/ar/core/Frame#hitTestInstantPlacement-xPx-yPx-approximateDistanceMeters) |\n\nPerform a standard hit-test\n---------------------------\n\nCall [`Frame.hitTest()`](/ar/reference/java/com/google/ar/core/Frame#hitTest-motionEvent) to perform a hit-test, using the [`TapHelper`](https://github.com/google-ar/arcore-android-sdk/blob/c684bbda37e44099c273c3e5274fae6fccee293c/samples/hello_ar_java/app/src/main/java/com/google/ar/core/examples/java/common/helpers/TapHelper.java) utility to obtain [`MotionEvent`](https://developer.android.com/reference/android/view/MotionEvent)s from the AR view. \n\n### Java\n\n```java\nMotionEvent tap = tapHelper.poll();\nif (tap == null) {\n return;\n}\n\nif (usingInstantPlacement) {\n // When using Instant Placement, the value in APPROXIMATE_DISTANCE_METERS will determine\n // how far away the anchor will be placed, relative to the camera's view.\n List\u003cHitResult\u003e hitResultList =\n frame.hitTestInstantPlacement(tap.getX(), tap.getY(), APPROXIMATE_DISTANCE_METERS);\n // Hit-test results using Instant Placement will only have one result of type\n // InstantPlacementResult.\n} else {\n List\u003cHitResult\u003e hitResultList = frame.hitTest(tap);\n // TODO: Filter hitResultList to find a hit result of interest.\n}\n```\n\n### Kotlin\n\n```kotlin\nval tap = tapHelper.poll() ?: return\nval hitResultList =\n if (usingInstantPlacement) {\n // When using Instant Placement, the value in APPROXIMATE_DISTANCE_METERS will determine\n // how far away the anchor will be placed, relative to the camera's view.\n frame.hitTestInstantPlacement(tap.x, tap.y, APPROXIMATE_DISTANCE_METERS)\n // Hit-test results using Instant Placement will only have one result of type\n // InstantPlacementResult.\n } else {\n frame.hitTest(tap)\n }\n```\n\nFilter hit results based on the type you're interested in. For example, if you'd like to focus on `DepthPoint`s: \n\n### Java\n\n```java\n// Returned hit-test results are sorted by increasing distance from the camera or virtual ray's\n// origin.\n// The first hit result is often the most relevant when responding to user input.\nfor (HitResult hit : hitResultList) {\n Trackable trackable = hit.getTrackable();\n if (trackable instanceof DepthPoint) { // Replace with any type of trackable type\n // Do something with this hit result. For example, create an anchor at this point of\n // interest.\n Anchor anchor = hit.createAnchor();\n // TODO: Use this anchor in your AR experience.\n break;\n }\n}\n```\n\n### Kotlin\n\n```kotlin\n// Returned hit-test results are sorted by increasing distance from the camera or virtual ray's\n// origin.\n// The first hit result is often the most relevant when responding to user input.\nval firstHitResult =\n hitResultList.firstOrNull { hit -\u003e\n when (val trackable = hit.trackable!!) {\n is DepthPoint -\u003e true // Replace with any type of trackable type\n else -\u003e false\n }\n }\nif (firstHitResult != null) {\n // Do something with this hit result. For example, create an anchor at this point of interest.\n val anchor = firstHitResult.createAnchor()\n // TODO: Use this anchor in your AR experience.\n}\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 [`Frame.hitTest(float[], int, float[], int)`](/ar/reference/java/com/google/ar/core/Frame#hitTest-origin3-originOffset-direction3-directionOffset) to conduct a hit-test using an arbitrary ray in world space coordinates instead of a screen-space point.\n\nCreate an Anchor using the hit result\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 [`HitResult.createAnchor()`](/ar/reference/java/com/google/ar/core/HitResult) to create a new [`Anchor`](/ar/develop/anchors), ensuring that the content attaches to the underlying [`Trackable`](/ar/reference/java/com/google/ar/core/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.\n\nWhat's next\n-----------\n\n- Check out the [`hello_ar_java`](https://github.com/google-ar/arcore-android-sdk/tree/master/samples/hello_ar_java) and [`hello_ar_kotlin`](https://github.com/google-ar/arcore-android-sdk/tree/master/samples/hello_ar_kotlin) sample apps on GitHub."]]