Android 云锚点开发者指南 (Kotlin/Java)

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

前提条件

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

如果您刚开始接触云锚点，请执行以下操作：

• 确保您了解锚点和云锚点的工作原理。
• 仔细阅读云锚点quickstart，了解系统要求、设置和安装说明。

启用 ARCore API

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

重要提示 ：托管和解析 TTL 大于 1 天的云锚点的应用必须使用无密钥授权。使用 API 密钥时，云锚点的最长生命周期为 24 小时。

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

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

Java

Config config = new Config(session);
config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED);
session.configure(config);

Kotlin

val config = Config(session)
config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED
session.configure(config)

托管云锚点

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

注意 ：在托管锚点时，上传到云端的视觉数据会在 24 小时内舍弃，并且之前上传的视觉数据绝不会发送到用户的设备。

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

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

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

检查特征点的映射质量

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

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

解析之前托管的锚点

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

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

取消操作或移除云锚点

调用 cancel() 以取消待处理的云锚点操作。调用 detach() 以从应用中移除已解析的云锚点。

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

使用 Anchor.CloudAnchorState 检查托管或解析操作的结果状态，包括错误。

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

后续步骤

• 参考“带永久性云锚点的 ARCore 云锚点”Codelab，创建一个云锚点应用。
• 通过云锚点快速入门中的两个示例应用，逐步介绍如何托管和解析云锚点。
• 使用 Cloud Anchors Management API 在 ARCore 应用之外管理云锚点。
• 如需了解在您的应用中使用 ARCore 的更多方法，请参阅 Android 参考文档。