Unity용 ARCore Geospatial Creator를 사용하면 Google 지도 데이터를 새로운 3D 타일 형식으로 표시하여 Unity 편집기에서 지리정보 콘텐츠를 미리 볼 수 있습니다. 이를 통해 앱을 빌드하는 동안 실제로 콘텐츠가 배치될 위치를 시각화할 수 있습니다.
Geospatial Creator는 AR 기초용 ARCore 확장 프로그램의 일부로 제공됩니다. 이 빠른 시작에서는 Unity에서 Geospatial Creator를 사용하여 ARCore Geospatial 샘플 앱에 지리정보 AR 콘텐츠를 추가하는 방법을 설명합니다.
지리정보 샘플 대신 사용하려는 기존 앱이 있는 경우 먼저 Unity용 지리정보 개발자 가이드를 따라야 합니다. 앱이 Geospatial API를 사용하도록 구성한 후에는 아래의 Add Required Dependencies(필수 종속 항목 추가) 단계로 건너뛰고 거기서부터 진행합니다.
기본 요건
'AR 기반용 ARCore 확장 프로그램 시작하기'에 따라 AR 환경을 만들도록 Unity 환경을 구성합니다.
ARCore 확장 프로그램은 이전 버전의 Unity를 지원하지만 Geospatial Creator를 사용하려면 Unity 2021.3 이상이 필요합니다.
API 승인
ARCore Geospatial API 및 Google Map Tiles API를 사용하려면 API 액세스를 설정해야 합니다.
Google 지도 타일 API
Map Tiles API는 지원되는 위치를 실사처럼 3D로 표현합니다. Unity 편집기에서 이러한 타일을 사용하여 AR 장면 주변 영역을 미리 봅니다.
API를 사용 설정하고 지도 타일에 관해 자세히 알아보려면 Map Tiles API 페이지를 참고하세요.
ARCore Geospatial API
ARCore Geospatial API는 런타임에 앱에서 지리정보 앵커를 만들고 상호작용하는 데 사용됩니다.
Geospatial API를 사용 설정하려면 애플리케이션에서 ARCore API를 설정합니다. 키 없음 (권장) 또는 API 키 승인 방법을 사용할 수 있습니다.
Geospatial 샘플 앱 확장
이 가이드에서는 Geospatial Creator를 사용하여 ARCore Geospatial 샘플 앱에 지리정보 콘텐츠를 추가하는 방법을 설명합니다.
지리정보 샘플 구성
먼저 ARCore 지리정보 샘플 앱을 숙지합니다. 새 Unity 프로젝트에서 Unity Package Manager를 열고 ARCore 확장 프로그램 패키지를 선택합니다. Package Manager 세부정보 패널에서 Samples(샘플)를 펼치고 지리정보 샘플을 Unity 프로젝트로 가져옵니다.
앱을 실행하기 전에 프로젝트에서 ARCore 및 지리정보 기능을 사용 설정해야 합니다. 편집 > 프로젝트 설정...을 사용합니다. > XR 플러그인 관리로 이동합니다. 적절한 체크박스를 선택하여 Android용 ARCore 플러그인 제공업체 또는 iOS용 ARKit 플러그인 제공업체를 사용 설정합니다.
그런 다음 Edit(수정) > Project Settings(프로젝트 설정)에서... > XR 플러그인 관리에서 ARCore 확장 프로그램 패널을 엽니다. 'Geospatial(공간)'이 선택되어 있는지 확인하고(아직 Geospatial Creator를 사용 설정할 필요는 없음) API 사용자 인증 정보를 입력합니다. 자세한 내용은 Android 및 iOS용 'Geospatial Unity API 사용 설정' 문서를 참고하세요.
ARCore를 사용하는 모든 Unity 앱에는 다른 플랫폼별 플레이어 설정이 몇 가지 필요합니다. 필요한 변경사항은 문서의 플레이어 설정 구성 섹션을 참고하세요.
이 시점에서는 지리정보 샘플을 실행하는 데 필요한 것 외에 장면에 게임 객체가 없습니다. 이제 앱을 빌드하고 실행하면 됩니다. 올바르게 구성된 경우 런타임에 앱이 기기의 카메라 뷰를 표시합니다. 이동하면 화면 상단에 표시되는 지리 공간 정확도가 개선됩니다. 화면을 탭하면 이동하는 동안 원래 위치에 유지되는 지리정보 앵커가 생성됩니다.
이제 Geospatial Creator를 사용하여 Unity 편집기 내에서 정교한 AR 콘텐츠를 만들고 시각화하는 방법을 알아보겠습니다. 이 콘텐츠는 앱에서 전 세계의 특정 위도 / 경도 위치에 표시됩니다.
필수 종속 항목 추가
Geospatial Creator는 Cesium이라는 서드 파티 Unity 패키지를 사용하여 Unity 편집기의 장면 창에서 Google 지도 타일을 렌더링합니다. Geospatial Creator 기능을 사용 설정하기 전에 프로젝트에 Cesium 패키지를 추가하겠습니다.
Cesium의 GitHub 페이지에서 최신 버전의 Cesium for Unity 패키지를 설치하는 것이 좋습니다.
- 사전 컴파일된 Unity용 Cesium
.tgz의 최신 버전을 GitHub 출시 페이지에서 다운로드합니다. 현재 권장되는 Cesium for Unity 패키지 버전은 1.1.0입니다. - Unity의 'Window' 메뉴를 클릭한 후 'Package Manager'(패키지 관리자)를 선택하여 Unity Package Manager를 엽니다.
- '+' 아이콘을 클릭하고 'tarball에서 패키지 추가'를 선택합니다.
- 1단계에서 다운로드한 Cesium for Unity .tgz 파일을 선택합니다.
- Text Mesh Pro와 같은 추가 종속 항목을 설치하라는 메시지가 표시될 수 있습니다.
Geospatial Creator 사용 설정
이제 Geospatial Creator를 사용 설정할 준비가 되었습니다.
- Build Settings 대화상자에서 선택한 플랫폼이 'Android' 또는 'iOS'인지 확인합니다. 현재 다른 플랫폼에서는 Geospatial Creator 기능을 사용할 수 없습니다.
- Project Settings(프로젝트 설정) > XR Plug-in Management(XR 플러그인 관리) > ARCore Extensions(ARCore 확장)로 이동합니다.
- 이전 단계에서 ARCore Android 또는 iOS API 키를 설정하지 않았다면 지금 설정해야 합니다.
- 'Geospatial(공간)' 및 'Geospatial Creator' 전환 버튼을 모두 사용 설정합니다. Geospatial Creator 전환 버튼을 클릭하여 사용 설정하면 프로젝트가 Geospatial Creator와 호환되는지 확인하는 비모달 마법사가 표시됩니다.
- 마법사에서 '마침'을 클릭합니다.
마법사를 완료하면 Unity가 스크립트 컴파일을 트리거합니다. 재컴파일이 완료될 때까지 기다린 후에 계속 진행합니다. 선택한 플랫폼이 'Android' 또는 'iOS'가 아닌 경우 지금 해당 플랫폼으로 전환합니다.
지도 타일을 사용하여 Geospatial Creator 출처 추가
장면에는 정확히 1개의 'Geospatial Creator Origin' 객체가 필요합니다. 이 객체는 실제 위도, 경도, 고도 값을 Unity 게임 좌표로 변환하기 위한 기준점으로 사용됩니다.
Geospatial Creator Origin을 장면에 추가하려면 게임 객체 > XR > Geospatial Creator Origin을 선택합니다. 새로 만든 객체에는 특정 위도, 경도, 고도를 게임 좌표의 출발지 위치와 연결하는 위치정보가 필요합니다. Geospatial Creator Origin의 Inspector(검사기) 창에서 Add Cesium Georeference Component(Cesium Georeference 구성요소 추가) 버튼을 클릭하여 지리 참조를 추가합니다.
Cesium Georeference는 AR 객체의 기준점일 뿐만 아니라 Cesium 3D Tileset 객체를 장면에 추가합니다. 이 객체는 편집기의 장면 뷰에서 Google 지도 타일을 렌더링하므로 AR 콘텐츠가 표시될 세상의 정확한 위치를 시각화할 수 있습니다. Geospatial Creator Origin 검사기에는 앞에서 설정한 Map Tiles API 키를 추가할 수 있는 필드가 있습니다. 이 키를 설정하면 장면 뷰에 지도 타일이 로드됩니다.
이제 위도, 경도, 높이 필드를 앱에서 AR 콘텐츠를 표시하려는 위치 근처에 위치하도록 변경합니다.
이제 편집기의 Scene View에서 출발지의 지정된 위도와 경도에 지도 타일이 표시됩니다. 런타임 시 앱에서 AR 카메라를 사용한다고 가정하므로 Geospatial Creator는 이미 'EditorOnly' 태그를 사용하여 Cesium 3D 지도 타일 세트 객체를 구성했습니다. 따라서 게임에서 런타임에 타일이 다운로드되거나 렌더링되지 않습니다. 이는 Cesium3DTileset 객체의 검사기에서 변경할 수 있습니다. Cesium의 Georeference 및 3D Tileset GameObjects에 관한 자세한 내용은 Cesium for Unity 문서를 참고하세요.
Geospatial Creator 앵커 추가 및 배치
이제 장면에 AR 콘텐츠를 배치할 준비가 되었습니다. GameObject > XR > Geospatial Creator Anchor를 클릭하여 장면 계층 구조에 앵커를 추가합니다. 앵커의 검사기에서 정확한 위도, 경도, 높이를 지정할 수 있습니다. 객체의 변환이 장면의 올바른 위치로 즉시 업데이트되며 객체가 있는 세상의 정확한 위치를 확인할 수 있습니다.
앵커의 위도와 경도를 미세 조정할 때 가까운 장소를 선택하면 런타임 시 위치가 올바른 위치에 있는지 확인할 수 있습니다. Geospatial Creator 앵커의 고도를 설정할 때 다음 세 가지 옵션이 있습니다.
- 지형은 지정된 위도와 경도의 지면 수준에 앵커를 배치합니다. 지면 수준은 런타임 시 시각적 위치 확인 시스템에 의해 결정됩니다. ARCore의 Geospatial API를 처음 사용하는 경우 앵커가 높은 수준의 수직 정확도로 지면에서 직접 리졸브되므로 '지형'을 선택하는 것이 좋습니다. '고도 오프셋' 필드를 사용하면 고정량(미터)만큼 지면 수준 위나 아래에 앵커를 배치할 수 있습니다. 예를 들어 오프셋을 '1.0'으로 지정하면 앵커가 지형에서 1미터 위에 '플로팅'됩니다.
- 루프톱은 지정된 위도와 경도의 구조물 상단을 기준으로 앵커를 배치합니다. 지형 앵커와 마찬가지로 '고도 오프셋' 필드를 사용하면 지붕 위치를 기준으로 앵커를 미터 단위로 위 또는 아래로 이동할 수 있습니다.
- WGS84는 WGS84 좌표계를 기반으로 특정 절대 고도(미터 단위)에 앵커를 배치합니다. WSG84의 높이가 '0'일 때 반드시 평균 해수면을 나타내는 것은 아니며 GPS의 고도와 일치하지 않을 수 있으므로 객체를 이런 식으로 배치하려면 시행착오를 거쳐야 할 수 있습니다. 또한 렌더링된 3D 타일의 위도와 경도는 매우 정확하지만 3D 타일을 참조로 사용하여 객체를 지면 수준에 배치하려고 하면 최대 몇 미터의 높이 오류가 발생할 수 있습니다.
ARCore 지리정보 앵커의 다양한 유형에 관한 자세한 내용은 지리정보 개발자 가이드를 참고하세요.
지형 및 루프톱 앵커에는 모두 WGS84 고도 필드가 있습니다. 이 값은 편집기 모드에서만 장면 뷰에서 객체의 높이를 설정하는 데 사용됩니다. 지형 및 옥상 높이는 런타임에만 결정되므로 WGS84 고도 필드를 사용하면 앱을 개발하는 동안 특정 높이에 앵커를 시각화할 수 있습니다. WGS84 고도 필드는 런타임 시 지형 및 루프톱 앵커의 경우 무시됩니다.
앵커에 도형 추가
지금 앱을 빌드하고 실행하면 AR 지원 앱에 앵커가 표시되지 않습니다. 이는 연결된 도형이 없기 때문입니다. 앵커에 간단한 3D 프리미티브를 추가해 보겠습니다. 장면 계층 구조에서 AR Geospatial Creator 앵커 객체를 마우스 오른쪽 버튼으로 클릭합니다. 컨텍스트 메뉴에서 3D Object > Cube를 선택합니다. 장면 뷰에 회색 큐브가 앵커의 하위 요소로 표시됩니다. 편집기에서 객체의 위치나 회전을 이동하려면 하위 큐브 프리미티브 대신 루트 앵커 객체를 이동하는 것이 좋습니다. 이렇게 하면 위도 / 경도에서 게임 좌표로의 변환에서 발생하는 오류를 줄이는 데 도움이 됩니다.
물론 더 복잡한 도형과 임의의 구성요소 및 하위 요소를 앵커에 추가할 수도 있습니다.
앱 빌드 및 실행
실제 세계에서 앵커를 볼 시간입니다. 앱을 빌드 및 실행한 다음 큐브를 볼 것으로 예상되는 위치로 이동합니다. 거기에 있나요? 축하합니다. Geospatial Creator로 더 복잡한 AR 환경을 빌드할 준비가 되었습니다.
문제가 있는 경우 문제 해결 가이드를 참고하세요.
이제 다양한 도형으로 AR Geospatial Creator 앵커를 더 추가할 수 있습니다. 여러 옥상 및 지형 앵커와 오프셋을 실험해 보세요. 객체를 애니메이션 처리하거나 객체와의 상호작용을 사용 설정하는 스크립트를 추가합니다.
Geospatial Creator 앵커 및 ARGeospatialAnchor 클래스 이해
복잡한 대화형 AR 환경을 구성할 때는 Geospatial Creator 앵커와 ARCore ARGeospatialAnchor C# 클래스 간의 관계를 이해하는 것이 좋습니다.
ARGeospatialAnchor는 ARAnchorManager에서 함수 중 하나를 호출하여 런타임에만 만들 수 있으며 AR 세션이 안정화된 후에만 만들 수 있습니다. Geospatial Creator 앵커는 AR 세션이 ARGeospatialAnchor 객체를 확인할 준비가 될 때까지 기다리는 장면에 있는 자리표시자로 생각할 수 있습니다.
세션이 준비되면 자리표시자는 자동으로 ARAnchorManager를 호출하여 ARGeospatialAnchor를 만들고 확인합니다.
런타임 앵커가 결정된 직후 장면 계층 구조의 Geospatial Creator 앵커가 새 GameObject에 하위 요소로 연결됩니다.
즉, Geospatial Creator 앵커의 모든 구성요소나 하위 요소가 새 ARGeospatialAnchor GameObject의 하위 구성요소 또는 하위 구성요소가 됩니다. 예를 들어 Geospatial Creator 앵커에 연결된 도형 프리미티브의 transform는 ARGeospatialAnchor의 transform에서 상속되므로 런타임 AR 세션의 예상 위치에 배치됩니다.
런타임 시 특정 ARGeospatialAnchor GameObject를 식별해야 하는 경우 name 속성이 Geospatial Creator를 사용하여 만든 앵커와 일치하는 객체를 장면에서 검색할 수 있습니다. AR 세션이 초기화되면 이 객체의 parent는 상응하는 ARGeospatialAnchor 객체가 됩니다.
문제 해결
앵커가 움직이는 이유는 무엇인가요?
특히 앱이 처음 실행될 때 앵커가 느리게 '드리프트'되거나
갑작스럽게 몇 미터 점프하는 것처럼 보일 수 있습니다. 이는 VPS 세션에서 여전히 카메라의 정확한 위치를 결정하고 미세 조정하는 중일 때 발생합니다. 여러 프레임에서 수평 및 수직 정확성이 개선됨에 따라 앵커가 더 정확한 위치에 다시 그려지므로 움직임이 떠오르게 됩니다. 위치 정확도가 특정 임곗값에 도달할 때까지 객체를 다르게 렌더링하거나 전혀 렌더링하지 않을 수 있습니다. 이렇게 하려면 ARCoreEarthManager.CameraGeospatialPose 속성을 쿼리하여 현재 프레임 업데이트의 정확성을 확인하면 됩니다.
앵커의 고도가 잘못 표시되는 이유는 무엇인가요?
Geospatial Creator 앵커에 '수동' 고도 유형을 사용할 때 앵커의 고도는 WGS84에 따라 미터 단위로 설정됩니다. 특정 위치에서 지도 타일에 표시되는 겉으로 보이는 지면과 Google의 VPS(Visual Positioning System)에서 보고한 실제 지면 수준 간에 최대 몇 미터의 불일치가 발생할 수 있습니다. 지리정보 앵커가 런타임에 잘못 배치된 것으로 보이면 샘플 앱에서 디버깅 오버레이를 사용하여 직접 VPS 높이를 검증하는 것이 좋습니다. 그런 다음 Unity 편집기에서 고도를 해당 위치의 알려진 VPS 높이와 일치하도록 변경할 수 있습니다.
지도 타일이 편집기의 장면 뷰에서 제대로 렌더링되지 않음
Cesium3DTileset가 카드를 로드하는 것 같지만 장면 뷰에서 단색 자홍색으로 렌더링되는 경우 Unity의 셰이더 그래프 패키지를 프로젝트에 추가합니다. 이 패키지는 Cesium에 필요하지만 Unity의 기본 제공 렌더기를 사용하는 프로젝트에는 기본적으로 포함되어 있지 않습니다.
셰이더 그래프를 추가하려면 Unity Package Manager (Window > 패키지 관리자)를 엽니다. Package Manager 창 상단의 드롭다운 메뉴에서 'Packages: Unity Registry'를 선택하여 Unity Package Registry에서 사용할 수 있는 패키지를 탐색해야 합니다. com.unity.shadergraph 패키지를 검색하여 최신 버전을 설치합니다. 패키지가 로드되면 3D 타일이 Scene View에서 제대로 다시 로드되고 렌더링되어야 합니다.
앱이 런타임에 카메라 뷰 대신 검은색 화면을 표시함
Unity의 범용 렌더링 파이프라인 (URP)은 기본적으로 AR 카메라용으로 구성되어 있지 않습니다. 런타임 시 카메라 출력 대신 검은색 화면이 표시되면 장면의 각 URP 렌더기에 AR Background Renderer Feature를 추가해야 합니다.
지형지물을 추가하려면 프로젝트에서 '렌더러'를 검색합니다. 각 URP 렌더기 객체의 경우 Inspector에서 'Add Renderer Feature' 버튼을 클릭하고 AR 백그라운드 렌더기를 추가합니다.
원점에서 멀리 배치된 앵커가 잘못 배치된 것처럼 보이는 이유는 무엇인가요?
WGS84 좌표에서 Unity 게임 좌표로 변환할 때 부동 소수점 산술 정밀도로 인해 오류가 발생할 수 있습니다. 부동 소수점 연산 정밀도는 출처가 AR 앵커 근처에 있도록 하여 최소화할 수 있습니다. 거리가 20km를 넘으면 부정확할 수 있습니다. AR 환경이 장거리에 걸쳐 있는 경우 장면마다 고유한 앵커가 있는 여러 장면을 사용하는 것이 좋습니다.