자체 앱에서 Cloud Anchors를 사용하는 방법을 알아보세요.
기본 요건
계속하기 전에 기본 AR 개념과 ARCore 세션을 구성하는 방법을 이해해야 합니다.
Cloud Anchors를 처음 사용하는 경우:
- 앵커 및 Cloud Anchors의 작동 방식을 이해해야 합니다.
- Cloud Anchors 빠른 시작에서 시스템 요구사항, 설정, 설치 안내를 확인하세요.
ARCore API 사용 설정
앱에서 클라우드 앵커를 사용하려면 먼저 애플리케이션에서 ARCore API를 사용 설정해야 합니다.
세션 구성에서 클라우드 앵커 기능 사용 설정
앱에서 클라우드 앵커 기능을 사용 설정하면 ARCore API와 통신할 수 있도록 앱의 AR 세션 구성에서 클라우드 앵커 기능을 사용 설정합니다.
자바
Config config = new Config(session); config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED); session.configure(config);
Kotlin
val config = Config(session) config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED session.configure(config)
클라우드 앵커 호스팅
호스팅은 hostCloudAnchorAsync() 호출로 시작됩니다. ARCore는 시각적 데이터, 기기 자세, 앵커 자세를 ARCore API에 업로드합니다. 그런 다음 API는 이 정보를 처리하여 3D 기능 지도를 만들고 궁극적으로 기기에 앵커의 고유한 클라우드 앵커 ID를 반환합니다.
ARCore Cloud Anchor Management API를 사용하여 호스팅된 앵커의 전체 기간을 연장할 수도 있습니다.
클라우드 앵커 호스팅을 완료하려면 앱에서 다음 단계를 따라야 합니다.
hostCloudAnchorAsync()을 호출합니다.- 콜백을 기다리거나 완료될 때까지 Future 상태를 계속 확인합니다.
- 결과 상태 확인 를 호출하여 작업 성공 여부를 확인하거나 실패 시 오류 코드를 해석합니다.
- 결과 클라우드 앵커 ID를 다른 클라이언트와 공유하고 이를 사용하여
resolveCloudAnchorAsync()
특성 지점의 매핑 품질 확인
Session.FeatureMapQuality는 특정 카메라 포즈에서 이전 몇 초 동안 ARCore가 본 특징점의 품질을 나타냅니다. 일반적으로 더 높은 품질의 기능을 사용하여 호스팅된 클라우드 앵커는 더 정확하게 확인됩니다. Session.estimateFeatureMapQualityForHosting()를 사용하여 특정 카메라 포즈의 특성 맵 품질을 추정합니다.
| 값 | 설명 |
|---|---|
INSUFFICIENT |
앞의 몇 초 동안 포즈에서 식별된 특징 포인트의 품질이 낮습니다. 이 상태는 ARCore가 클라우드 앵커를 확인하는 데 더 어려울 수 있음을 나타냅니다. 사용자가 호스팅하려는 Cloud Anchor의 원하는 위치를 다양한 각도에서 볼 수 있도록 기기를 움직이도록 안내합니다. |
SUFFICIENT |
이전 몇 초 동안 포즈에서 식별된 특징 포인트의 품질은 ARCore가 클라우드 앵커를 성공적으로 확인하는 데 충분할 수 있지만 결정된 포즈의 정확성은 낮아질 수 있습니다. 사용자가 호스팅하려는 Cloud Anchor의 원하는 위치를 다양한 각도에서 볼 수 있도록 기기를 움직이도록 안내합니다. |
GOOD |
이전 몇 초 동안의 포즈에서 식별된 지형지물 좌표의 품질은 ARCore가 높은 정확도로 클라우드 앵커를 확인하는 데 충분할 수 있습니다. |
이전에 호스팅된 앵커 확인
resolveCloudAnchorAsync()를 호출하여 호스팅된 클라우드 앵커를 확인합니다. ARCore API는 장면의 시각적 지형지물을 앵커의 3D 지형지물 맵과 주기적으로 비교하여 앵커를 기준으로 한 사용자의 위치와 방향을 정확하게 파악합니다. 일치하는 항목이 발견되면 API는 호스팅된 Cloud Anchor의 포즈를 반환합니다.
여러 Cloud Anchor의 확인을 순차적으로 시작할 수 있습니다. 한 번에 최대 40개의 클라우드 앵커 작업이 동시에 존재할 수 있습니다.
작업 취소 또는 클라우드 앵커 삭제
cancel()를 호출하여 대기 중인 클라우드 앵커 작업을 취소합니다.
detach()를 호출하여 앱에서 이미 확인된 Cloud Anchor를 삭제합니다.
클라우드 앵커 작업의 결과 상태 확인
Anchor.CloudAnchorState를 사용하여 오류를 포함하여 호스팅 또는 확인 작업의 결과 상태를 확인합니다.
| 값 | 설명 |
|---|---|
ERROR_CLOUD_ID_NOT_FOUND |
ARCore API에서 제공된 클라우드 앵커 ID를 찾을 수 없어 문제를 해결하지 못했습니다. |
ERROR_HOSTING_DATASET_PROCESSING_FAILED |
서버에서 지정된 앵커의 데이터 세트를 처리할 수 없어 호스팅에 실패했습니다. 기기가 환경에서 더 많은 데이터를 수집한 후 다시 시도해 보세요. |
ERROR_HOSTING_SERVICE_UNAVAILABLE |
ARCore API에 연결할 수 없습니다. 액세스할 수 없는 원인으로는 여러 가지가 있습니다. 기기가 비행기 모드이거나 인터넷에 연결되어 있지 않을 수 있습니다. 서버로 전송된 요청의 시간이 초과되어 응답이 없을 수 있습니다. 네트워크 연결 불량, DNS 사용 불가, 방화벽 문제 또는 ARCore API에 연결하는 기기의 기능에 영향을 줄 수 있는 다른 문제가 있을 수 있습니다. |
ERROR_INTERNAL |
이 앵커의 호스팅 또는 확인 작업이 내부 오류로 완료되었습니다. 앱은 이 오류 복구를 시도해서는 안 됩니다. |
ERROR_NOT_AUTHORIZED |
애플리케이션에서 제공한 승인이 유효하지 않습니다. ARCore API 승인 문제 해결을 참고하세요. |
ERROR_RESOLVING_SDK_VERSION_TOO_NEW |
앵커 확인에 사용된 SDK 버전이 앵커를 호스팅하는 데 사용된 버전보다 최신이며 이 버전과 호환되지 않으므로 클라우드 앵커를 해결할 수 없습니다. |
ERROR_RESOLVING_SDK_VERSION_TOO_OLD |
앵커를 확인하는 데 사용된 SDK 버전이 앵커를 호스팅하는 데 사용된 버전보다 오래되고 호환되지 않으므로 Cloud Anchor를 확인할 수 없습니다. |
ERROR_RESOURCE_EXHAUSTED |
애플리케이션이 특정 Google Cloud 프로젝트에 할당된 요청 할당량을 모두 사용했습니다. Google Developers Console에서 프로젝트의 ARCore API에 대한 할당량을 추가로 요청해야 합니다. |
SUCCESS |
앵커에 대한 호스팅 또는 확인 작업이 완료되었습니다. |
호스트 및 확인 요청에 대한 API 할당량
ARCore API에는 요청 대역폭에 관한 다음과 같은 할당량이 있습니다.
| 할당량 유형 | 최대 | 기간 | 적용 대상 |
|---|---|---|---|
| 앵커 수 | 무제한 | 해당 사항 없음 | 프로젝트 |
| 앵커 호스트 요청 | 30 | 분 | IP 주소 및 프로젝트 |
| 앵커 해결 요청 | 300 | 분 | IP 주소 및 프로젝트 |
우수한 사용자 환경을 위한 권장사항
앱에서 우수한 사용자 환경을 제공하려면 사용자에게 다음을 안내하세요.
- 세션이 시작된 후 몇 초간 기다린 후 앵커를 호스팅(예: 객체 배치)해 보세요. 이렇게 하면 모니터링이 안정화될 때까지 어느 정도 시간이 걸립니다.
- 앵커를 호스팅할 위치를 선택할 때 서로 쉽게 구별할 수 있는 시각적 요소가 있는 영역을 찾아보세요. 최상의 결과를 얻으려면 반사되는 표면이나 시각적 특징이 없는 표면(예: 흰색 벽)은 피하세요.
카메라를 관심 장소에 고정하고 관심 장소를 중심으로 기기를 움직여 다양한 각도에서 환경을 매핑합니다. 이때 기기와 관심 장소 사이의 물리적 거리는 거의 동일하게 유지합니다. 이렇게 하면 더 많은 시각적 데이터를 캡처하고 더 강력하게 해결할 수 있습니다.
클라우드 앵커를 호스팅하고 확인하는 동안 실제 환경에 충분한 조명이 있는지 확인하세요.
지원 중단 정책
- ARCore SDK 1.12.0 이상으로 빌드된 앱에는 Cloud Anchor API 지원 중단 정책이 적용됩니다.
- ARCore SDK 1.11.0 이하로 빌드된 앱은 SDK에서 지원 중단된 이전 ARCore API를 사용하기 때문에 클라우드 앵커를 호스팅하거나 확인할 수 없습니다.
다음 단계
- 영구 클라우드 앵커가 포함된 ARCore 클라우드 앵커 Codelab을 사용하여 클라우드 앵커 앱을 만듭니다.
- 클라우드 앵커 빠른 시작에서 두 가지 샘플 앱을 통해 클라우드 앵커를 호스팅하고 해결하는 방법을 알아봅니다.
- Cloud Anchors Management API를 사용하여 ARCore 앱 외부에서 Cloud Anchor를 관리합니다.
- 앱에서 ARCore를 사용하는 다른 방법은 Android 참조 문서를 참고하세요.