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

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

前提条件

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

如果您刚接触 Cloud Anchors，请按以下步骤操作：

启用 ARCore API

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

在会话配置中启用 Cloud Anchor 功能

在应用中启用云锚点功能后，请在应用的 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)

托管云锚点

托管服务从调用 hostCloudAnchorAsync() 开始。ARCore 会将视觉数据、设备姿态和锚点姿态上传到 ARCore API。然后，该 API 会处理这些信息以构建 3D 地图项，最终将锚点的唯一 Cloud Anchor ID 返回给设备。

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

您的应用应按照以下步骤完成 Cloud Anchor 的托管：

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

检查地图注点的映射质量

Session.FeatureMapQuality 表示 ARCore 在过去几秒内从给定相机姿势看到的特征点的质量。使用质量更高的地图项托管的云锚点通常可以更准确地解析。使用 Session.estimateFeatureMapQualityForHosting() 估算给定相机姿势的特征图质量。

值 说明
INSUFFICIENT 前几秒内根据姿势识别的特征点质量较差。此状态表示 ARCore 解析云锚点的难度可能会更大。建议用户移动设备，以便从不同角度查看他们希望托管的 Cloud 锚点的理想位置。
SUFFICIENT 从前几秒钟的姿势中识别的特征点质量可能足以让 ARCore 成功解析云锚点，但解析出的姿势的准确性可能会降低。建议用户移动设备，以便从不同角度查看他们希望托管的 Cloud 锚点的理想位置。
GOOD 从前几秒钟内的姿势中识别的特征点质量可能足以让 ARCore 成功解析出高度准确的云锚点。

解析之前托管的锚点

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

您可以按顺序为多个 Cloud 锚点发起解析。一次最多可以有 40 个并发的 Cloud Anchor 操作。

取消操作或移除 Cloud 锚点

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

检查 Cloud Anchor 操作的结果状态

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

值 说明
ERROR_CLOUD_ID_NOT_FOUND 解析失败，因为 ARCore API 找不到提供的 Cloud Anchor 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 无法解析 Cloud 锚点，因为用于解析锚点的 SDK 版本比用于托管该锚点的版本更高，并且与该版本不兼容。
ERROR_RESOLVING_SDK_VERSION_TOO_OLD 无法解析 Cloud 锚点，因为用于解析锚点的 SDK 版本低于用于托管该锚点的版本，并且与该版本不兼容。
ERROR_RESOURCE_EXHAUSTED 应用已耗尽为给定 Google Cloud 项目分配的请求配额。您应通过 Google Developers Console 为您的项目申请额外的 ARCore API 配额。
SUCCESS 此锚点的托管或解析任务已成功完成。

托管和解析请求的 API 配额

ARCore API 为请求带宽提供以下配额：

配额类型 最大值 时长 适用对象
锚点数量 无限制 不适用 项目
锚点托管请求 30 分钟 IP 地址和项目
锚点解析请求 300 分钟 IP 地址和项目

确保良好用户体验的最佳实践

请指示用户执行以下操作，以确保在您的应用中获得良好的用户体验：

  • 会话开始后，请等待几秒钟，然后再尝试托管锚点（通过放置对象等）。这样可以让跟踪有时间稳定下来。
  • 选择要托管锚点的位置时，请尽量选择视觉特征容易区分开来的区域。为了获得最佳效果，请避免使用反光面或不具有可视特征的平面，例如空白的白墙。

  • 让相机始终在兴趣中心训练，并围绕兴趣中心移动设备来移动设备，以便从不同角度绘制环境地图，同时保持大致相同的物理距离。这有助于捕获更多视觉数据，并提高解析的准确性。

  • 在托管和解析 Cloud Anchors 时，请确保实际环境中的光线充足。

废弃政策

  • 使用 ARCore SDK 1.12.0 或更高版本构建的应用受 Cloud Anchor API 弃用政策的约束。
  • 由于 SDK 使用的是已废弃的旧版 ARCore API，因此使用 ARCore SDK 1.11.0 或更低版本构建的应用无法托管或解析 Cloud Anchor。

后续步骤