在 Android NDK 应用中使用原始深度
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
Raw Depth API 为相机图像提供深度数据，其准确性比完整 Depth API 数据高，但不一定能覆盖每个像素。原始深度图像及其匹配的置信度图像也可以进一步处理，让应用仅使用准确度足够高的深度数据来满足具体用例的要求。
设备兼容性
原始深度数据可在所有支持 Depth API 的设备上使用。与完整的 Depth API 一样，原始 Depth API 不需要受支持的硬件深度传感器，例如飞行时间 (ToF) 传感器。不过，Raw Depth API 和完整 Depth API 均可利用设备可能具备的任何受支持硬件传感器。
原始深度 API 与完整深度 API
Raw Depth API 提供准确度更高的深度估计值，但原始深度图像可能不包含相机图像中所有像素的深度估计值。相比之下，Full Depth API 为每个像素提供估算的深度，但由于深度估算值的平滑和插值，每像素的深度数据可能不太准确。两个 API 中的深度图像格式和大小相同。只有内容不同。
下表使用厨房中的椅子和桌子的图片说明了 Raw Depth API 与完整 Depth API 之间的区别。
| API |
返回 |
相机图像 |
深度图片 |
置信度图片 |
|
原始深度 API
|
- 原始深度图像，包含相机图像中部分（而非全部）像素的非常准确的深度估算值。
- 为每个原始深度图像像素提供置信度的置信度图像。没有深度估算的相机图片像素置信度为 0。
|
|
|
|
|
全深度 API
|
- 一个“平滑”包含每个像素深度估算值的深度图像。
- 此 API 未提供任何置信度图片。
|
|
|
不适用
|
置信度图片
在 Raw Depth API 返回的置信度图像中，颜色较浅的像素具有较高的置信度值，白色像素表示完整的置信度，黑色像素表示没有置信度。一般来说，相机图像中纹理多的区域（例如树木）要比纹理不多的区域（例如空白墙）具有更高的原始深度置信度。没有纹理的表面产生的置信度通常为零。
如果目标设备具有受支持的硬件深度传感器，那么图片中距离相机足够近的区域的置信度可能会提高，即使在无纹理的表面上也是如此。
计算费用
Raw Depth API 的计算费用大约是完整 Depth API 计算费用的一半。
使用场景
借助原始深度 API，您可以获取深度图像，从而更详细地呈现场景中对象的几何图形。在打造 AR 体验时，原始深度数据非常有用，在这些体验中，几何图形理解任务需要更高的深度准确性和细节。一些用例包括：
前提条件
确保您了解 AR 基础概念
以及如何在继续之前配置 ARCore 现场录像。
启用景深数据
在新的 ARCore 会话中，检查用户的设备是否支持深度。由于处理能力限制，并非所有与 ARCore 兼容的设备都支持 Depth API。为节省资源，ARCore 默认停用深度。启用深度模式，让应用使用 Depth API。
int32_t is_depth_supported = 0;
// Check whether the user's device supports the Depth API.
ArSession_isDepthModeSupported(ar_session, AR_DEPTH_MODE_AUTOMATIC,
&is_depth_supported);
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);
if (is_depth_supported) {
ArConfig_setDepthMode(ar_session, ar_config, AR_DEPTH_MODE_AUTOMATIC);
}
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);
ArConfig_destroy(ar_config);
获取最新的原始深度图像
调用 ArFrame_acquireRawDepthImage16Bits() 以获取最新的原始深度图像。
int64_t previous_depth_image_timestamp_ns = -1;
int64_t depth_image_timestamp_ns;
ArImage* depth_image = NULL;
// Acquire the raw depth image for the current frame.
ArStatus acquire_image_status =
ArFrame_acquireRawDepthImage16Bits(ar_session, ar_frame, &depth_image);
if (acquire_image_status == AR_SUCCESS) {
// Optional: compare raw depth image timestamps. Use this check if your app
// uses only new depth data.
ArImage_getTimestamp(ar_session, depth_image, &depth_image_timestamp_ns);
if (depth_image_timestamp_ns != previous_depth_image_timestamp_ns) {
// Raw depth image is based on new depth data.
previous_depth_image_timestamp_ns = depth_image_timestamp_ns;
// …
}
// Release the acquired image.
ArImage_release(depth_image);
}
并非所有通过 Raw Depth API 返回的图像像素都包含深度数据，也并非每个 ARCore 帧都会包含新的原始深度图像。如需确定当前帧的原始深度图像是否为新的，请将其时间戳与上一原始深度图像的时间戳进行比较。如果时间戳不同，则原始深度图像基于新的深度数据。否则，深度图像是先前深度数据的重新投影。
“获取最新的置信度”图片
调用 ArFrame_acquireRawDepthConfidenceImage() 以获取置信度图片。您可以使用置信度图像来检查每个原始深度像素的准确率。置信度图片以 Y8 格式返回。每个像素都是一个 8 位无符号整数。0 表示置信度最低，而 255 表示置信度最高。
// Acquire the raw depth confidence image.
ArImage* confidence_image = NULL;
ArStatus acquire_image_status = ArFrame_acquireRawDepthConfidenceImage(
ar_session, ar_frame, &confidence_image);
if (acquire_image_status == AR_SUCCESS) {
// …
// Release the acquired image.
ArImage_release(confidence_image);
}
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-07-26。
[null,null,["最后更新时间 (UTC)：2025-07-26。"],[[["\u003cp\u003eThe Raw Depth API offers higher accuracy depth data compared to the full Depth API, but might not cover every pixel in the camera image.\u003c/p\u003e\n"],["\u003cp\u003eRaw depth images are accompanied by confidence images, allowing developers to filter data based on accuracy for specific use cases.\u003c/p\u003e\n"],["\u003cp\u003eWhile the Raw Depth API provides more detailed depth information, the full Depth API offers a depth estimate for every pixel, albeit with potential smoothing and interpolation affecting accuracy.\u003c/p\u003e\n"],["\u003cp\u003eThe Raw Depth API has a lower computational cost, roughly half of that associated with the full Depth API.\u003c/p\u003e\n"],["\u003cp\u003eUse cases for the Raw Depth API include 3D reconstruction, measurement, and shape detection, benefiting from its enhanced depth accuracy and detail.\u003c/p\u003e\n"]]],[],null,["# Use Raw Depth in your Android NDK app\n\nThe Raw Depth API provides depth data for a camera image that has higher accuracy than full Depth API data, but does not always cover every pixel. Raw depth images, along with their matching confidence images, can also be further processed, allowing apps to use only the depth data that has sufficient accuracy for their individual use case.\n\nDevice compatibility\n--------------------\n\nRaw Depth is available on all [devices that support the Depth API](/ar/devices). **The Raw Depth API, like the full Depth API, does not require a supported hardware depth sensor, such as a time-of-flight (ToF) sensor.** However, both the Raw Depth API and the full Depth API make use of any supported hardware sensors that a device may have.\n\nRaw Depth API vs full Depth API\n-------------------------------\n\nThe Raw Depth API provides depth estimates with higher accuracy, but raw depth images may not include depth estimates for all pixels in the camera image. In contrast, the full Depth API provides estimated depth for every pixel, but per-pixel depth data may be less accurate due to smoothing and interpolation of depth estimates. **The format and size of depth images are the same across both APIs.** Only the content differs.\n\nThe following table illustrates the differences between the Raw Depth API and the full Depth API using an image of a chair and a table in a kitchen.\n\n| API | Returns | Camera image | Depth image | Confidence image |\n|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|-------------|------------------|\n| Raw Depth API | - A raw depth image that contains a very accurate depth estimate for some, but not all, pixels in the camera image. - A confidence image that gives the confidence for every raw depth image pixel. Camera image pixels that do not have a depth estimate have a confidence of zero. | | | |\n| Full Depth API | - A single \"smoothed\" depth image that contains a depth estimate for every pixel. - No confidence image is provided with this API. | | | N/A |\n\n### Confidence images\n\nIn confidence images returned by the Raw Depth API, lighter pixels have higher confidence values, with white pixels representing full confidence and black pixels representing no confidence. In general, regions in the camera image that have more texture, such as a tree, will have higher raw depth confidence than regions that don't, such as a blank wall. Surfaces with no texture usually yield a confidence of zero.\n\nIf the target device has a supported hardware depth sensor, confidence in areas of the image close enough to the camera will likely be higher, even on textureless surfaces.\n\n### Compute cost\n\nThe compute cost of the Raw Depth API is about half of the compute cost for the full Depth API.\n\nUse cases\n---------\n\nWith the Raw Depth API, you can obtain depth images that provide a more detailed representation of the geometry of the objects in the scene. Raw depth data can be useful when creating AR experiences where increased depth accuracy and detail are needed for geometry-understanding tasks. Some use cases include:\n\n- 3D reconstruction\n- Measurement\n- Shape detection\n\nPrerequisites\n-------------\n\nMake sure that you understand [fundamental AR concepts](/ar/develop/fundamentals)\nand how to [configure an ARCore session](/ar/develop/c/session-config) before proceeding.\n\nEnable Depth\n------------\n\nIn [a new ARCore session](/ar/develop/c/session-config), check whether a user's device supports Depth. Not all ARCore-compatible devices support the Depth API due to processing power constraints. To save resources, depth is disabled by default on ARCore. Enable depth mode to have your app use the Depth API. \n\n```c\nint32_t is_depth_supported = 0;\n\n// Check whether the user's device supports the Depth API.\nArSession_isDepthModeSupported(ar_session, AR_DEPTH_MODE_AUTOMATIC,\n &is_depth_supported);\nArConfig* ar_config = NULL;\nArConfig_create(ar_session, &ar_config);\nif (is_depth_supported) {\n ArConfig_setDepthMode(ar_session, ar_config, AR_DEPTH_MODE_AUTOMATIC);\n}\nCHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);\nArConfig_destroy(ar_config);\n```\n\nAcquire the latest raw depth image\n----------------------------------\n\nCall [`ArFrame_acquireRawDepthImage16Bits()`](/ar/reference/c/group/ar-frame#arframe_acquirerawdepthimage16bits) to acquire the latest raw depth image. \n\n```c\nint64_t previous_depth_image_timestamp_ns = -1;\nint64_t depth_image_timestamp_ns;\nArImage* depth_image = NULL;\n\n// Acquire the raw depth image for the current frame.\nArStatus acquire_image_status =\n ArFrame_acquireRawDepthImage16Bits(ar_session, ar_frame, &depth_image);\n\nif (acquire_image_status == AR_SUCCESS) {\n // Optional: compare raw depth image timestamps. Use this check if your app\n // uses only new depth data.\n ArImage_getTimestamp(ar_session, depth_image, &depth_image_timestamp_ns);\n if (depth_image_timestamp_ns != previous_depth_image_timestamp_ns) {\n // Raw depth image is based on new depth data.\n previous_depth_image_timestamp_ns = depth_image_timestamp_ns;\n // ...\n }\n // Release the acquired image.\n ArImage_release(depth_image);\n}\n```\n\nNot all image pixels returned via the Raw Depth API will contain depth data, and not every ARCore frame will contain a new raw depth image. To determine whether the raw depth image for the current frame is new, compare its timestamp with the timestamp of the previous raw depth image. If the timestamps are different, the raw depth image is based on new depth data. Otherwise, the depth image is a reprojection of previous depth data.\n\nAcquire the latest confidence image\n-----------------------------------\n\nCall [`ArFrame_acquireRawDepthConfidenceImage()`](/ar/reference/c/group/ar-frame#arframe_acquirerawdepthconfidenceimage) to acquire the confidence image. You can use the confidence image to check the accuracy of each raw depth pixel. Confidence images are returned in Y8 format. Each pixel is an 8-bit unsigned integer. `0` indicates the least confidence, while `255` indicates the most. \n\n```c\n// Acquire the raw depth confidence image.\nArImage* confidence_image = NULL;\nArStatus acquire_image_status = ArFrame_acquireRawDepthConfidenceImage(\n ar_session, ar_frame, &confidence_image);\n\nif (acquire_image_status == AR_SUCCESS) {\n // ...\n // Release the acquired image.\n ArImage_release(confidence_image);\n}\n```"]]
