기존 ARCore Cloud Anchor API 클라우드 엔드포인트는 지원 중단되었으며 2023년 8월 31일 이후에는 지원되지 않습니다. 앱에서 이 API를 사용하는 경우 최대한 빨리 새로운 ARCore API 클라우드 엔드포인트를 사용하도록 업데이트해야 합니다.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

iOS용 Cloud Anchors 개발자 가이드

iOS용 ARCore SDK는 클라우드 앵커를 제공하기 위해 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 앵커를 호스팅하고 확인하는 데 사용되는 프로세스를 이해해야 합니다.
시스템 요구사항, 설정, 설치 안내는 빠른 시작을 참고하세요.
클라우드 앵커 샘플 중 하나를 확인하세요.

앱에서 Cloud Anchors 사용 설정

Cloud Anchors API를 사용하려면 GARSessionConfiguration 그런 다음 아래의 설명에 따라 cloudAnchorMode 속성을 설정하세요. iOS에서 ARCore 세션을 구성합니다. setConfiguration:error: (GARSession)를 사용하여 구성을 설정합니다.

애플리케이션에 ARCore API도 사용 설정해야 합니다.

앵커 호스팅 및 확인

ARCore Cloud Anchor API를 사용하여 클라우드 앵커를 호스팅하고 확인할 수 있습니다. 이 API에는 완료된 작업의 콜백 메서드와 폴링할 수 있는 Future 객체가 포함되어 있습니다.

앵커 호스팅

ARAnchor를 호스팅하면 지정된 실제 공간의 공통 좌표 체계에 앵커가 배치됩니다.

호스트 요청은 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을 사용하거나 폴링 옵션이 필요하며 앱이 최소 30fps로 실행되는 경우 다음 패턴을 사용하여 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 주소 및 프로젝트
앵커 요청 해결	300	분	IP 주소 및 프로젝트

알려진 문제 및 해결 방법

iOS용 ARCore SDK로 작업할 때 몇 가지 알려진 문제가 있습니다.

기본 스키마 설정으로 인해 간헐적으로 앱이 비정상 종료됩니다.

GPU 프레임 캡처 및 Metal API 검증 스키마 설정은 다음을 통해 사용 설정됩니다. 경우에 따라 SDK 내에서 앱이 비정상 종료될 수 있습니다.

앱 비정상 종료 진단

비정상 종료가 발생한 것으로 의심될 때마다 스택 트레이스를 살펴보세요. 스택 트레이스에 MTLDebugComputeCommandEncoder가 있으면 다음과 같은 오류일 수 있습니다. 기본 스키마 설정으로 변경합니다.

해결 방법

Product > Scheme > Edit Scheme… 페이지로 이동합니다.
Run 탭을 엽니다.
Options를 클릭하여 현재 설정을 확인합니다.
GPU Frame Capture 및 Metal API Validation가 모두 사용 중지되어 있는지 확인합니다.
앱을 빌드하고 실행합니다.

Cocoapods CHANGELOG에서 알려진 추가 문제를 확인하세요.

제한사항

iOS용 ARCore SDK는 ARKit setWorldOrigin(relativeTransform:) 메서드 호출을 지원하지 않습니다.

성능에 대한 고려사항

ARCore API를 사용 설정하면 메모리 사용량이 증가합니다. 네트워크 사용량과 CPU 사용률이 증가하여 기기의 배터리 사용량이 늘어날 수 있습니다.

다음 단계

ARCore iOS 참조 문서