iOS 云锚点开发者指南

探索 iOS 示例应用如何使用 ARCore Cloud Anchor API，并了解如何在您自己的应用中使用该 API。

如果您对 ARCore Cloud Anchor API 不熟悉，请先参阅快速入门，了解系统要求、设置和安装说明。

探索示例应用

演练示例应用，了解与使用云锚点有关的关键任务。云锚点。

会话设置

示例应用可以在会话设置过程中执行以下重要任务：

创建 GARSession
设置 GARSessionDelegate ，以便从托管和解析操作获取回调。
创建 ARSession 并运行
设置 ARSessionDelegate。
在 session:didUpdateFrame: 函数中将 ARFrame 传递至 GARSession 。

将 ARFrame 传递至 GARSession

确保您的应用可以持续将 ARFrame 传递至 GARSession。

为此，请使用以下推送模式：

-(void)someSetupMethod {
        arSession.delegate = self;
        garSession.delegate = self;
}

-(void)session:(ARSession *)arSession didUpdateFrame:(ARFrame *)arFrame {
        GARFrame *garFrame = [garSession update:arFrame];
        // … process the frame (optional)
}

在尝试托管或者解析锚点之前，您至少应将一个 ARFrame 传递至 GARSession。这可以留出时间，让 GARSession 与 ARSession 同步。

要详细了解 ARKit 中现实世界跟踪的最佳实践，请参阅 Apple 开发者文档中的关于增强现实和 ARKit。

如果您正在使用 Metal，或者需要轮询解决方案，请参阅本指南中的可选的轮询模式。

托管和解析锚点

ARCore Cloud Anchor API 提供了用于托管和解析云锚点的函数。此 API 还包含代理函数，用于提供已完成的托管和解析请求的结果。

托管锚点

托管 ARAnchor 会在给定物理空间的公用坐标系中对它进行映射。

托管请求会将可视映射数据发送到 Google 服务器，在表示当前物理空间的坐标系中映射 ARAnchor 的位置。成功的托管请求会返回一个已分配有云锚点 ID 的托管 GARAnchor。

- (void)addAnchorWithTransform:(matrix_float4x4)transform {
  self.arAnchor = [[ARAnchor alloc] initWithTransform:transform];
  [self.sceneView.session addAnchor:self.arAnchor];
  self.garAnchor = [self.gSession hostCloudAnchor:self.arAnchor error:nil];
  [self enterState:HelloARStateHosting];
}

解析锚点

解析云锚点可以让给定物理空间中的 Android 和 iOS 设备将之前托管的锚点添加到它们的场景中。

锚点解析请求会将一个云锚点 ID 与可视特征描述从当前帧发送到 Google 服务器。服务器会尝试将这些可视特征描述与它对当前托管的云锚点映射位置的理解相匹配。

成功的解析请求将返回一个具有有效转换和云锚点 ID 的 GARAnchor。示例应用可以将成功解析的 GARAnchor 添加到会话中。

- (void)resolveAnchorWithIdentifier:(NSString *)identifier {
  self.garAnchor = [self.gSession resolveCloudAnchorWithIdentifier:identifier error:nil];
}

托管和解析请求的代理函数

托管和解析请求使用 GARSessionDelegate 函数来提供请求成功和失败的回调。

托管

session:didHostAnchor:
session:didFailToHostAnchor:

解析

session:didResolveAnchor:
session:didFailToResolveAnchor:


-(void)session:(ARSession *)arSession didUpdateFrame:(ARFrame *)arFrame {
  [...]

-(void)session:(GARSession *)garSession didHostAnchor:(GARAnchor *)garAnchor {
        // successful host
}

-(void)session:(GARSession *)garSession didFailToHostAnchor:(GARAnchor *)garAnchor {
        // failed host
}

-(void)session:(GARSession *)garSession didResolveAnchor:(GARAnchor *)garAnchor {
        // successful resolve
}

-(void)session:(GARSession *)garSession didFailToResolveAnchor:(GARAnchor *)garAnchor {
        // failed resolve
}

API 配额

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

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

最佳实践

以下最佳实践有助于创造优质的云锚点用户体验。

一般

避免在平坦的发光面上托管或解析云锚点。
- 为了获得最佳结果，避免使用反光面或不具有可视特征的平面，例如空白的光滑白墙。
确保室内光线充足。
为了获得最佳结果，锚点托管和解析请求的光照条件应当一致。
在尝试托管或解析锚点之前，先将 ARFrame 传递至您的 GARSession。

托管

在托管锚点之前，请注意以下事项：

尝试从不同的角度观察锚点。
围绕锚点至少移动几秒钟。
确保您离锚点不会太远。

解析

解析锚点时，请注意以下事项：

确保您靠近托管锚点的位置。
- 如果您离云锚点的位置过远，云锚点可能无法正确解析。
- 如果您的手机摄像头对着与托管云锚点的位置不同但看上去相同的位置，云锚点可能无法正确解析。

已知问题与解决方法

默认模式设置导致应用间歇性崩溃

GPU Frame Capture 和 Metal API Validation 模式设置在默认情况下处于启用状态。这种情况有时会导致应用在 SDK 内崩溃。

诊断方法

如果发生崩溃，请查看您的堆叠追踪。
如果您在堆叠追踪中看到 MTLDebugComputeCommandEncoder，则崩溃很可能是由默认模式设置引起。请尝试以下解决方法。

解决方法

转到 Product > Scheme > Edit scheme…
打开 Run 标签。
点击 Options 以查看当前设置。
确保 GPU Frame Capture 和 Metal API Validation 已停用。
选择模式配置菜单。
重新构建并运行应用。

如需了解更多的已知问题，请参阅 Cocoapods 中的 CHANGELOG。

限制

ARCore SDK for iOS 不支持 ARKit setWorldOrigin(relativeTransform:) 函数调用。

可选的 GARSession 轮询模式

如果下面两种情况都适用于您的项目，请使用以下模式将 ARFrame 传递至 GARSession：

您正在使用 Metal，或者出于其他原因而需要轮询选项
您的应用以最低 30 fps 的速度运行（必需）

-(void)myOwnPersonalUpdateMethod {
        ARFrame *arFrame = arSession.currentFrame;
        GARFrame *garFrame = [garSession update:arFrame];
        // your update code here
}

后续步骤

请参阅 ARCore iOS API 参考了解更多详细信息。