iOS 云锚点开发者指南

ARCore SDK for iOS 与 ARKit 交互以提供云锚点功能，让您可以在同一环境中的 iOS 和 Android 设备之间共享锚点。

了解如何在您自己的应用中使用 ARCore Cloud Anchor API 或 ARCore 云锚点服务。

前提条件

  • Xcode 13.0 或更高版本
  • CocoaPods 1.4.0 或更高版本（如果使用 Cocoapods）
  • 运行 iOS 12.0 或更高版本且与 ARKit 兼容的 Apple 设备（部署目标必须为 iOS 12.0 或更高版本）

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

在应用中启用云锚点

如需使用 Cloud Anchors API，您必须创建一个 GARSessionConfiguration 并为其设置 cloudAnchorMode 属性，如在 iOS 中配置 ARCore 会话中所述。使用 setConfiguration:error: (GARSession) 设置配置。

您还必须为您的应用启用 ARCore API。

托管和解析锚点

您可以使用 ARCore Cloud Anchor API 托管和解析云锚点。该 API 包含已完成操作的回调方法以及可轮询的 Future 对象。

托管锚点

托管 ARAnchor 会将锚点置于任何给定物理空间的通用坐标系中。

主机请求会向 Google 服务器发送视觉数据，该服务器会在坐标系中对 ARAnchor 的位置进行映射，该坐标系代表当前物理空间。成功的托管请求会返回一个新的云锚点 ID，您可以共享该 ID 并在之后用于解析锚点。

- (void)addAnchorWithTransform:(matrix_float4x4)transform {
  self.arAnchor = [[ARAnchor alloc] initWithTransform:transform];
  [self.sceneView.session addAnchor:self.arAnchor];

  __weak ExampleViewController *weakSelf = self;
  self.hostFuture = [self.cloudAnchorManager
      hostCloudAnchor:self.arAnchor
           completion:^(NSString *anchorId, GARCloudAnchorState cloudState) {
             [weakSelf handleHostAnchor:anchorId cloudState:cloudState];
           }
                error:nil];
  [self enterState:HelloARStateHosting];
}

解析锚点

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

解析请求会向 Google 服务器发送云锚点 ID 以及当前帧中的可视数据。服务器会尝试将此视觉数据与当前托管的云锚点映射位置的图像进行匹配。解析成功后，系统会向会话添加一个新锚点并返回。

- (void)resolveAnchorWithIdentifier:(NSString *)identifier {
  GARResolveCloudAnchorFuture *garFuture =
      [self.gSession resolveCloudAnchorWithIdentifier:identifier
                                    completionHandler:completion
                                                error:&error];
}

// Pass the ARFRame to the ARCore session every time there is a frame update.
// This returns a GARFrame that contains a list of updated anchors. If your
// anchor's pose or tracking state changed, your anchor will be in the list.
- (void)cloudAnchorManager:(CloudAnchorManager *)manager didUpdateFrame:(GARFrame *)garFrame {
  for (GARAnchor *garAnchor in garFrame.updatedAnchors) {
    if ([garAnchor isEqual:self.garAnchor] && self.resolvedAnchorNode) {
      self.resolvedAnchorNode.simdTransform = garAnchor.transform;
      self.resolvedAnchorNode.hidden = !garAnchor.hasValidTransform;
    }
  }
}

可选的 GARSession 轮询模式

如果您使用的是 Metal，或者需要轮询选项，并且您的应用以至少 30 fps 的速率运行，请使用以下模式将 ARFrame 传递给 GARSession：

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

API 配额

ARCore API 具有以下请求带宽配额：

配额类型 最大值 时长 应用对象
锚点数量 无限制 不适用 项目
锚点 host 请求 30 分钟 IP 地址和项目
锚标记 resolve 请求 300 分钟 IP 地址和项目

已知问题与解决方法

使用 ARCore SDK for iOS 时存在一些已知问题。

默认方案设置导致应用间歇性崩溃

GPU Frame Capture 和 Metal API 验证方案设置默认处于启用状态，这有时可能会导致应用在 SDK 中崩溃。

诊断应用崩溃

每当您怀疑发生了崩溃，请查看您的堆栈轨迹。如果您在堆栈轨迹中看到 MTLDebugComputeCommandEncoder，则可能是由于默认架构设置造成的。

临时解决方法

  1. 转到 Product > Scheme > Edit Scheme…。

  2. 打开 Run 标签页。

  3. 点击 Options 即可查看当前设置。

  4. 确保 GPU Frame Capture 和 Metal API Validation 均已停用。

  5. 构建并运行您的应用。

如需了解其他已知问题，请参阅 Cocoapods CHANGELOG。

限制

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

性能考虑因素

启用 ARCore API 后，内存使用量会增加。预计设备的电池用量会因较高的网络用量和 CPU 利用率而增加。

后续步骤