Android NDK 云锚点开发者指南 (C)

了解如何在您的应用中使用云锚点

前提条件

确保您了解基本 AR 概念以及如何配置 ARCore 会话,然后再继续。

如果您刚开始接触云锚点,请务必了解锚点云锚点的工作原理。

启用 ARCore API

在您的应用中使用云锚点之前,您必须先在应用中启用 ARCore API

在会话配置中启用云锚点功能

在您的应用中启用云锚点功能后,在应用的 AR 会话配置中启用云锚点功能,以便它能够与 ARCore API 通信:

// Create a new ARCore session.
ArSession* session = NULL;
CHECK(ArSession_create(env, context, &session) == AR_SUCCESS);

// Create a session config.
ArConfig* config = NULL;
ArConfig_create(session, &config);
ArSession_getConfig(session, config);

// Enable Cloud Anchor mode.
ArConfig_setCloudAnchorMode(session, config,
                            AR_CLOUD_ANCHOR_MODE_ENABLED);

// Configure the session.
ArSession_configure(session, config);
ArConfig_destroy(config);

托管云锚点

Hosting 会首先调用 ArSession_hostCloudAnchorAsync()。ARCore 会将视觉数据、设备姿势和锚点姿势上传到 ARCore API。然后,API 会处理此信息来构建 3D 特征图,并最终将锚点的唯一云锚点 ID 返回给设备。

您还可以使用 ARCore Cloud Anchor Management API 延长托管锚点的生命周期。

您的应用应按照以下步骤托管云锚点:

  1. 调用 ArSession_hostCloudAnchorAsync()
  2. 等待回调或持续检查 Future 状态,直到回调完成。
  3. 检查结果状态以确定操作是否成功,或者在操作失败时解释错误代码。
  4. 与其他客户端共享结果云锚点 ID,并通过 ArSession_resolveCloudAnchorAsync() 使用该 ID 解析云锚点。

检查特征点的映射质量

ArFeatureMapQuality 表示 ARCore 在最近几秒内从给定摄像头姿势看到的特征点的质量。使用质量更高的特征托管的云锚点通常更容易得到准确解析。使用 ArSession_estimateFeatureMapQualityForHosting() 可获取指定镜头位置方向的特征图质量估算值。

说明
INSUFFICIENT 从前几秒钟的姿势中识别出的特征点质量不佳。此状态表示 ARCore 解析云锚点可能会比较困难。鼓励用户移动设备,以便从不同角度查看他们希望托管的云锚点的所需位置。
SUFFICIENT 虽然解析后的姿势的准确度可能会降低,但前几秒钟从姿势中识别出的特征点的质量可能足以让 ARCore 成功解析云锚点。鼓励用户移动设备,以便从不同角度查看他们希望托管的云锚点的所需位置。
GOOD 从前几秒钟姿态中识别出的特征点的质量可能足以让 ARCore 以高准确度成功解析云锚点。

解析之前托管的锚点

调用 ArSession_resolveCloudAnchorAsync() 以解析托管的云锚点。ARCore API 会定期将场景中的视觉特征与锚点的 3D 特征图进行比较,以精确定位用户相对于锚点的位置和方向。找到匹配项后,API 会返回托管的云锚点的姿势。

您可以依序启动多个云锚点的解析。最多可以同时存在 40 个并发的云锚点操作。

取消操作或移除云锚点

调用 ArFuture_cancel() 以取消待处理的云锚点操作。调用 ArAnchor_detach() 可停止跟踪并忘记一个已解析的云锚点。必须通过调用 ArAnchor_release() 单独释放对锚点的引用。

检查云锚点操作的结果状态

使用 ArCloudAnchorState 检查托管或解决操作的结果状态,包括错误。

说明
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND 由于 ARCore API 找不到提供的云锚点 ID,解析失败。
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED 由于服务器无法成功处理给定锚点的数据集,因此托管失败。请在设备从环境中收集到更多数据后重试。
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE 无法访问 ARCore API。可能造成这种情况的原因有很多。设备可能处于飞行模式或未连接到互联网。发送到服务器的请求可能已超时,没有响应。可能是网络连接状况不佳、DNS 不可用、防火墙问题,或者其他可能影响设备能否连接到 ARCore API 的因素。
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL 此锚点的托管或解析任务已完成,但发生内部错误。应用不应尝试从此错误中恢复。
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED 请参阅排查 ARCore API 授权问题
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW 无法解析云锚点,因为用于解析云锚点的 SDK 版本比用于托管云锚点的版本新,并且与之不兼容。
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD 无法解析云锚点,因为用于解析云锚点的 SDK 版本比用于托管云锚点的版本旧,并且与之不兼容。
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED 应用已用尽分配给指定 Google Cloud 项目的请求配额。您应从 Google Developers Console 为您的项目申请额外的 ARCore API 配额。
AR_CLOUD_ANCHOR_STATE_SUCCESS 此锚点的托管或解析任务已成功完成。

主机和解析请求的 API 配额

ARCore API 具有以下请求带宽配额:

配额类型 最大值 时长 应用对象
锚点数量 无限制 不适用 个项目
锚点 host 请求 30 分钟 IP 地址和项目
锚标记 resolve 请求 300 分钟 IP 地址和项目

提供良好用户体验的最佳实践

指导用户采取以下行动,以确保您的应用提供良好的用户体验:

  • 在会话开始后等待几秒钟,然后再尝试托管锚点(通过放置对象等)。这会给跟踪留出一些时间来稳定下来。
  • 选择托管锚点的位置时,尝试找到具有可轻松区分的视觉特征的区域。为了获得最佳效果,请避免使用反光表面或缺少视觉特征的表面,例如空白白墙。
  • 使相机保持在目标中心处的训练,并围绕目标中心移动设备,从不同的角度绘制环境地图,同时保持与您的物理距离大致相同的距离。这将有助于捕获更多视觉数据并提高解析可靠性。

  • 在托管和解析云锚点时,请确保现实环境中有足够的照明。

废弃政策

  • 使用 ARCore SDK 1.12.0 或更高版本构建的应用适用 Cloud Anchor API 弃用政策
  • 由于 SDK 使用的是已弃用的旧版 ARCore API,因此使用 ARCore SDK 1.11.0 或更低版本构建的应用无法托管或解析云锚点。

后续步骤