프로젝트 애니웨어 XR | 언리얼 엔진 4.27 문서

프로젝트 애니웨어 XR(Project Anywhere XR)은 언리얼 엔진에서 월드를 3D 타일로 시각화하기 위한 지리공간 기술, 글로벌 3D 지형 및 데이터 스트리밍을 보여주는 개념 증명입니다. 프로젝트 애니웨어의 현재 버전은 HoloLens 2 애플리케이션에서 대규모 데이터 세트를 사용할 수 있다는 것을 보여줍니다.

이 프로젝트는 다음과 같은 플러그인을 활용하여 증강현실에서 여러분의 테이블탑에 월드를 구현합니다.

전제조건

시작하기 전에 다음이 준비되어야 합니다.

Cesium for Unreal 플러그인 1.6.0 버전 이상
Microsoft Mixed Reality UX Tools 플러그인
Windows 10 최신 버전
Microsoft tools for HoloLens 2
(선택사항) HoloLens 2 디바이스 최신 버전 업데이트

필요한 타사 플러그인은 언리얼 엔진 마켓플레이스에서 찾을 수 있습니다. 플러그인 없이 프로젝트를 시작하면, 플러그인을 다운로드하고 설치하라는 메시지가 표시됩니다.

HoloLens 2 디바이스가 없어도 Mixed Reality UXTools 플러그인에 포함된 Microsoft의 Hand Simulation을 통해 에디터 내 에뮬레이션으로 프로젝트를 실행할 수 있습니다.

프로젝트 구성

아래 단계에 따라 프로젝트 애니웨어 XR 샘플 콘텐츠로 프로젝트를 구성하고 에셋을 Cesium Ion 계정에 연결합니다.

에픽게임즈 런처에서 Project Anywhere XR 샘플을 다운로드하고 언리얼 에디터에서 새 프로젝트를 생성합니다.
Cesium Ion 계정에 로그인합니다.
Asset Depot 탭에서 다음과 같은 3D Tiles 에셋을 추가합니다.
- Aerometrex Denver Photogrammetry (#354307)
- Bing Maps Aerial (#2)
- Cesium OSM Buildings (#96188)
- Cesium world terrain (#1)
- Melbourne Photogrammetry (#69380)
주의 사항: 일부 에셋은 비상업적 용도로만 사용 가능합니다.
Access Tokens 탭으로 이동합니다.
Create Token 을 클릭해 Create token 패널을 엽니다.
Create token 패널에서 아래 단계를 진행합니다.
- Name 필드에 Project Anywhere XR 을 입력합니다.
- Scope 항목에서 아래 옵션을 활성화합니다.
  - assets:list
  - assets:read
  - profile:read
  - assets:write
  - geocode
- Resources 항목에서 Selected assets 을 선택하면 Available Assets 목록이 표시됩니다. 애플리케이션에서 사용하는 에셋에 대해서만 토큰을 활성화하는 것이 좋습니다.
- Available Assets 목록에서 아래 에셋을 선택합니다.
  - Aerometrex Denver Photogrammetry (#354307)
  - Bing Maps Aerial (#2)
  - Cesium OSM Buildings (#96188)
  - Cesium world terrain (#1)
  - Melbourne Photogrammetry (#69380)
- Create 를 클릭해 토큰을 엽니다.
Project Anywhere XR 을 클릭하고 Token 아래의 텍스트를 복사합니다.
언리얼 에디터의 월드 아웃라이너 에서 다음과 같은 Cesium3DTileset 액터를 선택합니다.
- Cesium OSM Buildings
- Cesium World Terrain
- Denver
- Melbourne Photogrammetry
디테일 패널에 각 액터의 공통 프로퍼티가 표시됩니다. Ion Access Token 프로퍼티에 Cesium Ion 계정에서 생성한 토큰을 붙여넣습니다.
Cesium World Terrain 액터와 Bing Maps Aerial 컴포넌트를 선택합니다.
디테일 패널로 이동해 Cesium Ion 계정에서 생성한 토큰을 Ion Access Token 프로퍼티에 붙여넣습니다.
4개의 Cesium3DTileset 액터와 Bing Maps Aerial 컴포넌트에 대해 토큰을 설정하고 나면, 뷰포트에 지형 데이터가 나타납니다.
툴바에서 현재 레벨 저장 을 클릭해 레벨의 변경 사항을 저장합니다.

프로젝트 보기

이 애플리케이션은 Microsoft의 Holographic Remoting Player를 통해 컴퓨터에서 HoloLens 2 디바이스로 콘텐츠를 스트리밍할 수 있도록 제작되었습니다. 콘텐츠를 스트리밍하면 컴퓨터로 대량의 데이터 세트를 로드해서 렌더를 만든 다음, 네트워크를 통해 렌더링한 프레임을 디바이스로 전송할 수 있습니다. 프로젝트를 애플리케이션으로 패키징한 뒤 디바이스로 디플로이하려면 데이터 세트가 디바이스의 메모리 용량을 넘지 않아야 합니다.

Holographic Remoting Player를 사용해 언리얼 에디터에서 디바이스로 스트리밍하는 방법은 Streaming to device with the Holographic Remoting Player를 참조하세요.

디바이스로 스트리밍할 때는 이미지 퀄리티를 높여 경험을 향상시킬 수 있도록 네트워크 전송 속도를 15,000kb/s로 늘립니다.

컴퓨터에 연결된 HoloLens 2 디바이스가 없다면 에디터 내 에뮬레이션으로 키보드와 마우스 입력을 사용해 프로젝트를 볼 수 있습니다. 에디터 내 에뮬레이션을 활성화하는 방법은 다음과 같습니다.

메인 메뉴에서 편집 > 프로젝트 세팅 을 선택해 프로젝트 세팅 창을 엽니다.
프로젝트 세팅 창의 플랫폼 에서 'Windows Mixed Reality'를 선택합니다.
Holographic Remoting 섹션에서 Enable Input Simulation 을 True 로 설정합니다.

에디터 내 에뮬레이션의 자세한 사용 방법은 Microsoft의 Input Simulation 문서를 참조하세요.

이 프로젝트의 에디터 내 시뮬레이션에는 다음과 같은 한계가 있습니다.

에디터 내 에뮬레이션은 캘리브레이션을 지원하지 않습니다. 자동으로 테이블탑을 배치하려면 캘리브레이션에 공간 메시가 필요합니다. 공간 메시는 애플리케이션이 주변 환경을 스캔할 때 생성됩니다.
애플리케이션은 에디터 내에서 플레이할 때 북마크 선택에 사용되는 핀치 인터랙션 이벤트를 수신하지 않습니다. 대신 키보드의 1 키와 2 키로 양손의 핀치 인터랙션을 에뮬레이트할 수 있습니다.

프로젝트가 시작되면 가상 테이블탑이 나타납니다. 월드 섹션은 테이블 위에 맵 형태로 아래와 같은 정보를 표시합니다.

맵 중앙의 지리적 좌표(위도/경도/고도)
맵에 표시되는 영역의 실제 길이

핸드 메뉴 사용하기

프로젝트에는 한쪽 손을 앞으로 펼치면 액세스할 수 있는 메뉴가 있습니다. 이 메뉴에는 구체적인 여러 위치가 핀으로 표시되어 있어서 선택하면 맵을 업데이트할 수 있는 지구 모델, 지구 모델을 회전시킬 수 있는 슬라이더, 테이블을 옮기거나 표시된 데이터의 상세 정보를 알 수 있는 버튼이 포함되어 있습니다. 메뉴는 HoloLens 2를 위한 UXTool Hand Menu를 사용해 블루프린트 BP_HandMenu 에서 정의됩니다.

아래 섹션에서는 메뉴와 상호작용하는 방법과 메뉴가 만들어진 방식을 설명합니다.

북마크를 통해 원하는 위치로 이동하기

지구 모델에는 구체적인 여러 위치가 핀으로 표시되어 있습니다. 위치를 선택하면 해당 위치가 테이블탑에 나타납니다.

위치를 선택하려면 손을 핀 가까이 가져갑니다. 핀이 빨갛게 변하고 위치 이름이 표시된 툴팁이 표시됩니다. 손가락으로 집으면 테이블탑의 맵이 업데이트되고 해당 위치가 나타납니다.

축을 중심으로 지구 모델을 회전시키려면 모델 아래의 슬라이더를 핀치하고 드래그합니다. 슬라이더를 놓으면 회전이 멈춥니다.

앱이 시작되면 BP_HandMenu 액터의 북마크 데이터 테이블 DT_Bookmarks_PAXR에 있는 항목을 바탕으로 핀이 다이내믹하게 스폰됩니다. 커스텀 UxtPressableButton인 핀 블루프린트 BP_Bookmark_Button 은 구체 컴포넌트에 어태치되어 있으므로, 핀도 자동으로 지구와 함께 회전합니다.

메뉴 버튼

아래 버튼은 사용되는 데이터와 주변 환경을 따라 테이블탑을 움직이는 기능에 대한 정보를 제공합니다.

메뉴 버튼	설명
데이터 속성	핸드 메뉴의 데이터 속성 버튼을 클릭하면 표시된 맵의 데이터 속성을 읽을 수 있습니다.
캘리브레이트	앱을 처음 실행하면 방의 디폴트 위치에 홀로그램 테이블이 표시됩니다. 이 버튼을 누르면 테이블을 뷰 바로 앞으로 자동 재배치할 수 있습니다. 자세한 사항은 방의 가상 테이블탑 이동하기 섹션을 참조하세요.
위로 이동	Z축을 따라 테이블 위치를 위로 움직입니다.
아래로 이동	Z축을 따라 테이블 위치를 아래로 움직입니다.
왼쪽으로 회전	Z축을 중심으로 테이블을 왼쪽으로 회전시킵니다.
오른쪽으로 회전	Z축을 중심으로 테이블을 오른쪽으로 회전시킵니다.

BP_HandMenu 블루프린트 살펴보기

메뉴는 HoloLens 2를 위한 UXTool Hand Menu를 바탕으로 블루프린트 BP_HandMenu에서 정의합니다. UxtPalmUpConstraint가 활성화되거나 비활성화되면 메뉴가 나타나고 사라집니다. 버튼 인터랙션은 BP_AnywhereXRPlayerController 에서 해당하는 액션으로 리다이렉트됩니다. BeginPlay에서 BP_HandMenu는 다음을 시작합니다.

변수 MRAnywhere Player Controller 에 BP_AnywhereXRPlayerController의 레퍼런스를 저장합니다.
Data Attribution 위젯을 생성하고 숨깁니다.
모든 메뉴 이벤트를 해당하는 이벤트 핸들러에 바인드합니다.
슬라이더 이벤트를 지구 모델의 회전에 바인드합니다.
DT_Bookmarks_PAXR 데이터 테이블의 모든 항목을 읽어온 다음, 이 항목을 사용해 해당하는 북마크를 스폰합니다.

방의 가상 테이블탑 움직이기

애플리케이션을 처음 실행하면 방의 디폴트 위치에 가상 테이블탑이 표시됩니다. 메뉴의 캘리브레이트 버튼이나 이동 및 회전 버튼을 사용하면 더 나은 곳으로 위치를 옮길 수 있습니다. 테이블탑 위치는 가급적 어두운 색의 테이블이 좋습니다. 테이블을 배치하면 ARPins가 테이블을 월드에 앵커합니다.

핸드 메뉴에서 캘리브레이트(Calibrate) 버튼을 눌러 캘리브레이션을 시작합니다. 캘리브레이션이 시작되면 현재 테이블탑은 숨겨지고, 캘리브레이션 프로세스를 위한 새 가상 테이블탑이 나타납니다. 새 테이블탑은 이전 테이블탑과 형태와 크기가 같으며, 보는 방향을 향해 배치됩니다. 머리 위치와 앵커 포인트 사이의 벡터에 따라 테이블탑 지도에서 북쪽이 결정됩니다.

아래 단계에 따라 테이블탑 위치와 북쪽 방향을 확정합니다.

머리를 움직여 캘리브레이션 테이블탑을 원하는 위치로 옮깁니다. 이 작업 도중에는 방의 공간 메시가 사용됩니다.

다시 탭하면 캘리브레이션 테이블탑을 놓고, 테이블 위치를 설정할 수 있습니다.

테이블탑 위치를 미세조정하려면 메뉴 버튼에서 이동 및 회전 버튼을 눌러 위치를 조정할 수 있습니다.

블루프린트 BP_AnywhereXRPlayerController에는 캘리브레이션과 테이블 이동을 위한 로직이 포함되어 있습니다. 아래 섹션에서는 캘리브레이션에 사용되는 일부 함수를 설명합니다.

캘리브레이션 함수

StartTable Calibration 함수는 핸드 메뉴의 캘리브레이트 버튼에서 호출됩니다. 호출되면 아래와 같은 작업을 수행합니다.

BP_AnchorGizmo를 스폰하고 디바이스 방향에 따라 자동으로 캘리브레이션 모드가 됩니다.
BP_AnchorGizmo의 Tap To Place가 트리거하는 Anchor Placed 이벤트에 자신을 바인드합니다.
가상 테이블탑을 비활성화하여 콜리전이 없도록 숨깁니다.

StartTable Calibration 함수의 블루프린트 그래프. 이미지를 클릭하면 최대화됩니다.

OnAnchorPlaced 함수는 사용자가 BP_AnchorGizmo를 배치할 때 호출됩니다. 호출되면 아래와 같은 작업을 수행합니다.

확정된 위치의 트랜스폼을 가져오고 함수 ChangeTableOrigin을 호출합니다.
BP_AnchorGizmo를 파괴합니다.
테이블탑을 새 위치에 활성화하여 다시 콜리전이 발생하도록 숨김을 해제합니다.

OnAnchorPlaced 함수의 블루프린트 그래프. 이미지를 클릭하면 최대화됩니다.

ChangeTableOrigin 함수는 OnAnchorPlaced에 의해 호출됩니다. 호출되면 아래와 같은 작업을 수행합니다.

모든 오브젝트가 올바르게 재배치되도록 테이블에 특정 Teleport 함수를 호출합니다.
로컬 스토어에 ARPin의 위치를 저장합니다.

ChangeTableOrigin 함수의 블루프린트 그래프. 이미지를 클릭하면 최대화됩니다.

가상 테이블의 맵과 상호작용하기

가상 테이블의 맵은 핸드 인터랙션을 사용한 패닝과 줌을 지원합니다. 회전이 구현되지 않았기 때문에 맵의 북쪽은 바뀌지 않습니다. 맵에는 인터랙션이 가능하다는 것을 알려주는 가상 힌트가 표시됩니다. 인터랙션은 지형이 아닌 플랫 테이블 지오메트리를 트레이스합니다.

맵을 패닝하려면 한 손으로 핀치하고 맵을 움직이려는 방향으로 손을 움직입니다. 핀치를 풀면 맵을 놓습니다.

맵을 줌 인하거나 줌 아웃하려면 양손으로 핀치한 다음, 두 손의 거리를 벌려 줌 아웃하고 두 손을 모아서 줌 인합니다. 핀치를 풀면 맵을 놓습니다.

맵의 인터랙션 로직은 BP_HolographicTable에서 정의합니다. 개발팀은 맵 인터랙션을 구현할 때 아래와 같은 사항을 고려해 디자인을 선택했습니다.

HoloLens 조작은 하나의 오브젝트에 대해서만 작동하지만, Cesium 3D 타일 세트는 여러 액터로 구성되어 있습니다. 애플리케이션은 테이블을 고정한 상태로 HoloLens 조작 인터랙션을 가져온 다음, 입력 이동 및 스케일 동작을 해당하는 타일 세트에 적용합니다.
지구는 구체이므로, 계속 패닝하다 보면 수평 모션으로 인해 결국 지구 표면에서 멀어지게 됩니다. 작은 스케일에서는 크게 문제가 되지 않지만, 최대 스케일로 줌 아웃하면 이 현상이 눈에 띄게 됩니다. 따라서 패닝 모션에 지구의 곡선이 고려되어야 하지만, 단계마다 곡선을 적용하면 비용이 커질 수 있습니다.

이 문제를 해결하기 위해, 모션이 지정된 한계치를 초과하면 애플리케이션이 타일 세트 액터의 원점을 테이블 중앙으로 재배치합니다. 이 효과는 눈에 보이지 않으며, 연산도 정확하게 이루어집니다.
맵에 산이 표시되므로 변수는 타원체와 지면 사이의 높이가 됩니다. 줌 인한 뒤에 타원체 원점을 테이블 중앙에 두면 지면이 테이블에서 너무 위로 뜨게 됩니다. 이 오프셋은 지구에서 위치마다 다릅니다. 지면이 항상 테이블과 맞도록 타일 세트를 수직으로 움직여도 되지만, 지구상의 모든 부분에 대해 최소 고도를 알 수는 없습니다.

이 문제를 해결하기 위해 애플리케이션은 라인 트레이스를 통해 지면의 높이를 파악한 다음, 현재 위치나 스케일과 관계없이 지면이 테이블과 맞도록 컨트롤 알고리즘을 적용합니다.
HoloLens 2 인터랙션은 눈에 보이는 모든 지오메트리와 충돌합니다. 맵에 표시되는 지형은 디폴트로 HoloLens 2의 레이캐스트가 테이블과 충돌하지 않도록 차단합니다.

이 문제를 해결하기 위해 프로젝트 세팅에는 타일 세트(TileSets) 라는 커스텀 콜리전 채널이 있습니다. 각 Cesium3DTiles의 콜리전 프로퍼티는 타일 세트 채널을 사용한 콜리전만 차단하고 비저빌리티 채널은 무시합니다.

이러한 디자인 결정으로 인해 가상 테이블탑과 상호작용하면 테이블탑은 모든 3D 타일의 목록을 가져오고, 타일을 수직, 수평으로 움직이며, 스케일을 조절해 줌 이펙트를 적용하고, 맵이 수평을 유지할 수 있도록 디스플레이스먼트 한계치를 넘어 모든 것이 재배치됩니다.

알려진 이슈

아래는 사용자가 접할 수 있는 문제와 그 해결 방법입니다.

출시(Shipping) 용으로 애플리케이션을 패키징할 때 시작 단계에서 치명적 오류 메시지가 표시된다면 두 가지 방법으로 문제를 해결할 수 있습니다.
- Cesium For Unreal 플러그인을 사용하는 모든 언리얼 에디터 인스턴스를 닫고 plugin, %LOCALAPPDATA%\UnrealEngine\4.27에 위치한 cesium-request 캐시 파일을 삭제합니다.
- 앱을 개발(Development) 용으로 패키징합니다.
VR 프리뷰를 사용해 에디터로 애플리케이션을 프리뷰할 때, 핸드 트래킹은 작동하지만 인터랙션이 등록되지 않는다면 HoloLens 2 디바이스와 언리얼 애플리케이션을 재시작합니다.