iOS 云锚点开发者指南

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

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

前提条件

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

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

在应用中启用 Cloud Anchors

如需使用 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 为请求带宽提供以下配额：

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

已知问题与解决方法

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

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

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

诊断应用崩溃问题

每当您怀疑发生了崩溃时，请查看堆栈轨迹。如果您在堆栈轨迹中看到 MTLDebugComputeCommandEncoder，则崩溃很可能是由默认 scheme 设置引起。

临时解决方法

  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 使用率增加，设备的电池用量预计也会增加。

后续步骤