Unity용 Cloud Anchors 개발자 가이드 (AR Foundation)

앱에서 클라우드 앵커를 사용하는 방법을 알아보세요.

기본 요건

계속 진행하기 전에 기본 AR 개념과 ARCore 세션 구성 방법을 이해해야 합니다.

클라우드 앵커를 처음 사용하는 경우 앵커 및 클라우드 앵커의 작동 방식을 이해해야 합니다.

ARCore API 사용 설정

앱에서 클라우드 앵커를 사용하기 전에 먼저 애플리케이션에서 ARCore API를 사용 설정해야 합니다.

세션 구성에서 클라우드 앵커 기능 사용 설정

앱에서 Cloud Anchors 기능을 사용 설정했다면 ARCore API와 통신할 수 있도록 앱의 AR 세션 구성에서 Cloud Anchors 기능을 사용 설정합니다.

클라우드 앵커 호스팅

호스팅은 ARAnchorManager.HostCloudAnchorAsync() 호출로 시작합니다. ARCore는 ARCore API에 시각적 데이터, 기기 포즈, 앵커 포즈를 업로드합니다. 그러면 API가 이 정보를 처리하여 3D 기능 맵을 생성하고 궁극적으로 앵커의 고유한 클라우드 앵커 ID를 기기에 반환합니다.

ARCore Cloud Anchor Management API를 사용하여 호스팅된 앵커의 전체 기간을 연장할 수도 있습니다.

앱은 다음 단계에 따라 클라우드 앵커 호스팅을 완료해야 합니다.

  1. ARAnchorManager.HostCloudAnchorAsync()을 호출합니다.
  2. 코루틴을 시작하여 프로미스에서 결과를 얻을 때까지 기다립니다. 자세한 내용은 Unity의 코루틴을 참고하세요.
  3. 결과 상태를 확인하여 작업이 성공했는지 확인하고 실패한 경우 오류 코드를 해석합니다.
  4. 결과 클라우드 앵커 ID를 다른 클라이언트와 공유하고 이를 사용하여 ARAnchorManagerExtensions.ResolveCloudAnchorAsync()로 클라우드 앵커를 확인합니다.

특성 포인트의 매핑 품질 확인

ARCoreExtensions.FeatureMapQuality은 지정된 카메라 포즈에서 이전 몇 초 동안 ARCore가 본 특징점의 품질을 나타냅니다. 더 높은 품질의 기능을 사용하여 호스팅되는 클라우드 앵커는 일반적으로 더 정확하게 결정됩니다. ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting()를 사용하여 지정된 카메라 포즈의 특성 맵 품질을 추정합니다.

값 설명
Insufficient 이전 몇 초 동안의 포즈에서 식별된 특징점의 품질이 낮습니다. 이 상태는 ARCore가 클라우드 앵커를 해결하기가 더 어려울 수 있음을 나타냅니다. 호스팅하려는 클라우드 앵커의 원하는 위치를 다양한 각도에서 볼 수 있도록 기기를 움직이도록 사용자에게 안내하세요.
Sufficient 이전 몇 초 동안의 포즈에서 식별된 특징 포인트의 품질은 ARCore가 클라우드 앵커를 성공적으로 해결하는 데 충분할 가능성이 높지만 결정된 포즈의 정확성은 떨어질 가능성이 있습니다. 호스팅하려는 클라우드 앵커의 원하는 위치를 다양한 각도에서 볼 수 있도록 기기를 움직이도록 사용자에게 안내하세요.
Good 이전 몇 초 동안의 포즈에서 식별된 특징 포인트의 품질은 ARCore가 높은 수준의 정확도로 클라우드 앵커를 성공적으로 해결하는 데 충분할 가능성이 높습니다.

이전에 호스팅된 앵커 확인

ARAnchorManagerExtensions.ResolveCloudAnchorAsync()를 호출하여 호스팅된 클라우드 앵커를 확인합니다. ARCore API는 앵커의 3D 지형지물 맵과 장면의 시각적 특징을 주기적으로 비교하여 앵커를 기준으로 사용자의 위치와 방향을 정확히 찾습니다. 일치하는 항목을 찾으면 API는 호스팅된 클라우드 앵커의 포즈를 반환합니다.

여러 클라우드 앵커에 대한 확인을 순서대로 시작할 수 있습니다. 한 번에 최대 40개의 클라우드 앵커 작업이 동시에 존재할 수 있습니다.

작업 취소 또는 클라우드 앵커 삭제

ARCloudAnchor.OnDestroy()는 ARCloudAnchor 구성요소가 포함된 게임 객체에서 삭제되면 자동으로 호출됩니다. 이렇게 하면 기본 네이티브 클라우드 앵커 객체가 분리되고 해제됩니다.

클라우드 앵커 작업의 결과 상태 확인

CloudAnchorState를 사용하여 오류를 포함하여 호스팅 또는 해결 작업의 결과 상태를 확인합니다.

값 설명
ErrorResolvingCloudIdNotFound ARCore API에서 제공된 클라우드 앵커 ID를 찾을 수 없어 문제를 해결하지 못했습니다.
ErrorHostingDatasetProcessingFailed 서버에서 지정된 앵커의 데이터 세트를 처리할 수 없어 호스팅이 실패했습니다. 기기가 환경에서 더 많은 데이터를 수집한 후에 다시 시도하세요.
ErrorHostingServiceUnavailable ARCore API에 연결할 수 없습니다. 다운로드할 수 없는 원인으로는 여러 가지가 있습니다. 기기가 비행기 모드이거나 인터넷에 연결되어 있지 않을 수 있습니다. 서버로 전송된 요청이 응답 없이 시간 초과되었을 수 있습니다. 네트워크 연결 불량, DNS 사용 불가, 방화벽 문제 등 기기의 ARCore API 연결 기능에 영향을 줄 수 있는 문제가 있을 수 있습니다.
ErrorInternal 이 앵커의 호스팅 또는 확인 작업이 내부 오류로 완료되었습니다. 앱은 이 오류를 복구하려고 시도해서는 안 됩니다.
ErrorNotAuthorized 잘못된 승인으로 인해 앱이 ARCore API와 통신할 수 없습니다. Project Settings(프로젝트 설정) > XR > ARCore Extensions(ARCore 확장)에서 유효한 승인 전략을 확인합니다.
ErrorResolvingPackageTooNew 클라우드 앵커를 확인하는 데 사용된 ARCore 확장 프로그램 패키지가 최신 버전이며 호스팅하는 데 사용되는 버전과 호환되지 않으므로 클라우드 앵커를 해결할 수 없습니다.
ErrorResolvingPackageTooOld 클라우드 앵커를 확인하는 데 사용된 ARCore 확장 프로그램 패키지가 오래되었고 호스팅하는 데 사용되는 버전과 호환되지 않으므로 클라우드 앵커를 확인할 수 없습니다.
ErrorResourceExhausted 애플리케이션이 지정된 Google Cloud 프로젝트에 할당된 요청 할당량을 소진했습니다. Google Developers Console에서 프로젝트의 ARCore API 추가 할당량을 요청해야 합니다.
Success 이 앵커의 호스팅 또는 확인 작업이 완료되었습니다.

호스트 및 요청 해결용 API 할당량

ARCore API의 요청 대역폭 할당량은 다음과 같습니다.

할당량 유형 최대 시간 적용 대상
앵커 수 unlimited N/A 프로젝트
앵커 host 요청 30 분 IP 주소 및 프로젝트
앵커 resolve 요청 300 분 IP 주소 및 프로젝트

우수한 사용자 경험을 위한 권장사항

앱에서 우수한 사용자 환경을 제공하기 위해 다음 단계를 따르도록 안내하세요.

  • 세션 시작 후 객체 배치 등을 통해 앵커 호스팅을 시도하기 전에 몇 초 동안 기다립니다. 이렇게 하면 추적이 안정화될 때까지 시간이 다소 걸립니다.
  • 앵커를 호스팅할 위치를 선택할 때는 서로 쉽게 구분할 수 있는 시각적 지형지물이 있는 영역을 찾으세요. 최상의 결과를 얻으려면 빈 흰색 벽과 같이 시각적 특징이 부족한 반사 표면이나 표면을 피하세요.

  • 카메라를 관심 중심에 학습시킨 상태로 유지하고 관심 중심을 중심으로 기기를 이동하여 환경을 다양한 각도에서 매핑하고, 이와 거의 동일한 물리적 거리를 유지합니다. 이렇게 하면 더 많은 시각적 데이터를 캡처하고 해상도를 더 강력하게 만들 수 있습니다.

  • 클라우드 앵커를 호스팅하고 확인하는 동안 실제 환경에 충분한 조명이 있는지 확인합니다.

지원 중단 정책

  • ARCore SDK 1.12.0 이상으로 빌드된 앱에는 Cloud Anchor API 지원 중단 정책이 적용됩니다.
  • ARCore SDK 1.11.0 이하로 빌드된 앱은 SDK에서 지원 중단된 이전 ARCore API를 사용하므로 클라우드 앵커를 호스팅하거나 확인할 수 없습니다.

다음 단계