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