iOS 云锚点开发者指南

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

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

前提条件

  • Xcode 13.0 或更高版本
  • 如果使用 Cocoapods,则需要 Cocoapods 1.4.0 或更高版本
  • 搭载 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 以及当前帧中的视觉数据。服务器会尝试将这些视觉数据与当前托管 Cloud Anchor 的位置映射的图像进行匹配。解析成功后,系统会向会话添加新的锚点并返回。

- (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 地址和项目

已知问题与解决方法

使用适用于 iOS 的 ARCore SDK 时,存在一些已知问题。

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

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

诊断应用崩溃问题

每当您怀疑发生了崩溃时,请查看堆栈轨迹。如果您在堆栈轨迹中看到 MTLDebugComputeCommandEncoder,则可能是因为默认架构设置。

临时解决方法

  1. 前往Product > Scheme > Edit Scheme…

  2. 打开 Run 标签页。

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

  4. 确保 GPU Frame CaptureMetal API Validation 均已停用。

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

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

限制

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

性能考虑因素

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

后续步骤