了解如何在您自己的应用中使用云锚点。
前提条件
确保您了解 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 延长托管锚点的生命周期。
您的应用应按照以下步骤完成云锚点的托管：
- 调用
ArSession_hostCloudAnchorAsync()。 - 等待回调，或持续检查 Future 状态，直到完成为止。
- 检查结果状态 以确定操作是否成功，或者在操作失败时解释错误代码。
- 与其他客户端共享结果云锚点 ID，并使用该 ID 通过
ArSession_resolveCloudAnchorAsync()。
检查特征点的映射质量
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 或更低版本构建的应用无法托管或解析云锚点。
后续步骤
- 查看 Android NDK 参考文档，了解在您的应用中使用 ARCore 的更多方法。