了解如何在您自己的应用中使用云锚点。
前提条件
在继续操作之前，请确保您了解基本 AR 概念以及如何配置 ARCore 会话。
如果您刚开始接触 Cloud Anchors，请务必了解锚点和 Cloud Anchors 的运作方式。
启用 ARCore API
在您的应用中使用云锚点之前，您必须先在应用中启用 ARCore API。
在会话配置中启用云锚点功能
在应用中启用云锚点功能后，请在应用的 AR 会话配置中启用云锚点功能，以便应用能够与 ARCore API 通信：
托管 Cloud Anchors
托管服务从调用 ARAnchorManager.HostCloudAnchorAsync() 开始。ARCore 会将视觉数据、设备姿态和锚点姿态上传到 ARCore API。然后，API 会处理此信息以构建 3D 特征图，最终向设备返回锚点的唯一云锚点 ID。
您还可以使用 ARCore Cloud Anchor Management API 延长托管锚点的生命周期。
您的应用应按照以下步骤完成 Cloud Anchor 的托管：
- 调用
ARAnchorManager.HostCloudAnchorAsync()。 - 启动协程，等待 Promise 产生结果。如需了解详情，请参阅 Unity 中的协程。
- 检查结果状态，以确定操作是否成功，或在操作失败时解读错误代码。
- 与其他客户端共享结果云锚点 ID，并使用该 ID 通过
ARAnchorManagerExtensions.ResolveCloudAnchorAsync()解析云锚点。
检查特征点的映射质量
ARCoreExtensions.FeatureMapQuality 表示 ARCore 在过去几秒内从给定相机姿势看到的特征点的质量。使用更高质量的功能托管的云锚点通常可以更准确地解析。使用 ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting() 估算给定相机姿势的特征图质量。
| 值 | 说明 |
|---|---|
Insufficient |
从前几秒钟的姿势中识别的特征点质量较差。此状态表示 ARCore 解析云锚点的难度可能会更大。建议用户移动设备，以便从不同角度查看他们希望托管的 Cloud 锚点的理想位置。 |
Sufficient |
虽然已解析的姿势的准确性可能会降低，但前几秒内从位置方向识别到的特征点的质量或许足以让 ARCore 成功解析云锚点。建议用户移动设备，以便从不同角度查看他们希望托管的 Cloud 锚点的理想位置。 |
Good |
从前几秒钟内的姿势中识别的特征点质量可能足以让 ARCore 成功解析出高度准确的云锚点。 |
解析之前托管的锚点
调用 ARAnchorManagerExtensions.ResolveCloudAnchorAsync() 以解析托管的 Cloud 锚点。ARCore API 会定期将场景中的视觉特征与锚点的 3D 特征图进行比较，以精确定位用户相对于锚点的位置和方向。找到匹配项后，API 会返回托管云锚点的姿态。
您可以按顺序启动多个云锚点的解析。一次最多可以有 40 个并发的 Cloud Anchor 操作。
取消操作或移除 Cloud 锚点
当从包含 ARCloudAnchor 组件的游戏对象中移除该组件时，系统会自动调用 ARCloudAnchor.OnDestroy()。这会分离并释放底层原生 Cloud Anchor 对象。
检查 Cloud Anchor 操作的结果状态
使用 CloudAnchorState 检查托管或解析操作的结果状态，包括错误。
| 值 | 说明 |
|---|---|
ErrorResolvingCloudIdNotFound |
解析失败，因为 ARCore API 找不到提供的 Cloud Anchor ID。 |
ErrorHostingDatasetProcessingFailed |
托管失败，因为服务器无法成功处理给定锚点的数据集。请在设备从环境中收集更多数据后重试。 |
ErrorHostingServiceUnavailable |
无法访问 ARCore API。可能造成这种情况的原因有很多。设备可能处于飞行模式或未连接到互联网。发送到服务器的请求可能已超时，且未收到响应。网络连接不佳、DNS 不可用、防火墙问题或任何其他可能影响设备连接到 ARCore API 的因素。 |
ErrorInternal |
此锚点的托管或解析任务在完成时发生了内部错误。应用不应尝试从此错误中恢复。 |
ErrorNotAuthorized |
由于授权无效，应用无法与 ARCore API 通信。请依次前往 Project Settings > XR > ARCore Extensions，查看是否有有效的授权策略。 |
ErrorResolvingPackageTooNew |
无法解析云锚点，因为用于解析云锚点的 ARCore 扩展软件包比用于托管云锚点的版本更新且不兼容。 |
ErrorResolvingPackageTooOld |
无法解析云锚点，因为用于解析云锚点的 ARCore Extensions 软件包版本低于用于托管该云锚点的版本，并且与该版本不兼容。 |
ErrorResourceExhausted |
应用已耗尽为给定 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。
后续步骤
- 如需了解在您的应用中使用 ARCore 的更多方法，请参阅 ARCore Extensions for AR Foundation 参考文档。