휴대형 AR 템플릿은 iOS 및 Android 디바이스용 증강현실 프로젝트를 제작하기 위한 출발점으로 사용할 수 있습니다. 휴대형 증강현실 템플릿 퀵스타트에서는 템플릿 구성 및 모바일 디바이스로의 디플로이 과정을 단계별로 설명했다면, 이번 가이드에서는 이 템플릿의 작동 원리와 핵심 기능이 구현된 부분, 그리고 그 기능을 수정하는 방법 등 보다 기술적인 가이드를 제공합니다.
기초
휴대형 AR 템플릿은 다음과 같은 두 부분으로 표시됩니다.
-
사용자의 카메라에서 받은 피드
-
언리얼 엔진의 3D 월드 내에 존재하는 가상 씬
사용자의 카메라 피드는 AR 세션 을 시작할 때 자동으로 캡처되며, 가상 씬은 그 위에 렌더링됩니다. 사용자를 나타내는 폰에는 가상 씬 내의 오브젝트와 인터랙션하는 로직이 갖춰져 있으며, 여기에는 초기 스캔 및 배치 가능한 오브젝트에 의해 정의되는 평면이 포함됩니다. HUD는 이렇게 컴포짓된 디스플레이에 오버레이되어 환경설정 옵션 및 기타 툴을 제공합니다.
휴대형 AR 템플릿에서 사용자가 어떤 과정을 거치는지에 대한 자세한 내용은 휴대형 증강현실 템플릿 퀵스타트를 참고하세요.
애플리케이션 워크플로
휴대형 AR 템플릿은 에디터에서, 그리고 애플리케이션의 스타트업 시 모두 직접 HandheldARBlankMap 에서 열립니다. 이 맵에는 모바일 디바이스 구성에 대한 문서를 지정하는 데 사용되는 헬퍼 액터 이외의 액터는 전혀 갖추고 있지 않습니다. 주요 기능은 게임 모드를 BP_ARGameMode 에 오버라이드하여 해당 애플리케이션이 애플리케이션 실행 및 가상 씬의 구성을 담당하는 게임 프레임워크 클래스를 사용하도록 하는 것입니다.
BP_ARGameMode는 사용자의 뷰포트에 BP_MainMenu 를 추가하여 UI 초기화를 담당하는 BP_ARPawn 으로 플레이어를 시작합니다. BP_MainMenu가 구성되면 사용자에게 환경 스캔을 시작하라는 알림을 제공합니다. 그러면 AR 세션 이 시작되고 사용자의 카메라 피드를 표시하며, 환경 내에서 사용 가능한 평면을 기반으로 일련의 평면을 정의하도록 BP_ARPawn에 알립니다.
BP_ARPawn은 단순 스테이트 머신을 사용하여 현재 애플리케이션에서 사용자 과정이 어떤 단계에 있는지 트래킹합니다. 이 스테이트 머신은 다음과 같은 요인을 트래킹합니다.
-
사용자가 자신의 환경을 스캔하고 가상 씬 내에 평면을 구성했는지 여부
-
사용자가 인터랙션할 평면을 선택했는지 여부
-
사용자가 선택된 평면에 오브젝트를 배치했는지 여부
폰은 사용자 과정에서 사용자의 진행 상황에 따라 애플리케이션이 입력에 대응하는 방식을 변경하고 HUD에 구성 단계를 따라 진행하라는 알림을 트리거합니다.
액터
AR 폰
휴대형 AR 템플릿은 BP_ARPawn 이라는 커스텀 폰을 사용합니다. 이 폰은 초기화, 가상 씬의 빌드 및 업데이트, 사용자의 입력 처리 등을 담당합니다.
초기화
AR 폰은 BeginPlay 시 사용자의 뷰포트에 BP_MainMenu를 추가합니다. 그러면 BP_MainMenu는 AR 씬의 구성 및 애플리케이션의 현재 스테이트를 기반으로 알림 처리를 담당합니다.
스테이트 제어
AR 폰은 단순 스테이트 머신을 구현하여 위 섹션에서 제시된 사용자 과정에서 다양한 단계를 지원합니다. 스테이트는 스테이트(State) 카테고리에서 일련의 부울에 의해 제어됩니다.
여기에는 다음이 포함됩니다.
-
ScanningIsDone: 초기 스캔 프로세스가 완료되었으며 가상 씬에 평면이 배치되었습니다.
-
PlaneIsSelected: 사용자가 평면을 선택했습니다.
-
ObjectIsPlaced: 사용자가 평면에 가상 오브젝트를 배치했으며, 이제 해당 오브젝트와 인터랙션할 수 있습니다.
사용자가 HUD 알림을 따르면 위 부울은 false에서 true로 바뀌며, 사용자 과정에서의 다음 단계로 넘어가도록 애플리케이션을 트리거합니다. 폰은 터치 입력을 처리할 때와 Tick 이벤트를 처리하여 씬을 업데이트할 때 위 부울을 레퍼런스합니다.
카메라 뎁스 씬 텍스처
AR 폰은 가상 씬에서 오브젝트를 배치하는 데 사용되는 카메라 뎁스 씬 텍스처를 가져오는 역할도 담당합니다. 이 정보는 사용자가 애플리케이션에 카메라 사용 권한을 허용하면 즉시, 애플리케이션이 AR 스캔을 마치기 전에 가져옵니다. 뎁스 텍스처는 CameraDepthTexture 에 저장되며, 폰이 평면의 비주얼을 업데이트할 때 평면 후보 생성(Create Plane Candidate) 함수에서 사용됩니다. CameraDepthTexture를 사용할 수 없는 경우에는 대신 CameraDepthFallback 을 사용합니다.
라이트 강도 추정
Tick 이벤트 동안 AR 폰은 피드 라이트 추정(Feed Light Estimate) 함수를 호출합니다. 이 함수는 AR 세션에서 현재 라이트 추정 데이터를 얻습니다. 데이터가 유효한 경우 이 함수는 카메라 피드를 기반으로 맵의 디렉셔널 라이트 및 스카이라이트의 컬러 및 강도 세팅을 업데이트합니다. 그러면 사용자의 현실 세계 환경의 라이팅과 대략적으로 일치하는 라이팅이 가상 씬에 생성됩니다.
AR 평면 생성
AR 세션이 환경 스캔을 마치면 AR 폰이 가상 씬에 PlaneCandidate 액터의 업데이트를 시작합니다. 이 프로세스에서는 환경에서 트래킹되는 오브젝트가 유효한 AR 평면 지오메트리(AR Plane Geometry) 에 적합한지 확인합니다. 일반적으로 디바이스의 센서는 5~20개의 오브젝트를 탐지할 수 있습니다.
그런 다음, 폰은 평면 후보 생성 을 호출하여 BP_Plane 액터를 스폰하고 가상 씬의 적절한 위치에 배치합니다. 평면 후보는 초당 1회 업데이트됩니다. 이 프로세스는 화면의 시각적 복잡성을 줄이기 위해 AR 폰이 항상 한 번에 하나의 평면만 AR 세션에 의해 트래킹되는 가장 가까운 오브젝트 위주로 트래킹하도록 구성됩니다. 사용자는 환경을 돌아다니면서 서로 다른 평면 후보가 나타나고 사라지는 것을 보게 됩니다.
사용자가 평면 후보를 하나 선택하면 BP_Plane은 대신 SelectedPlane 으로 그 자리에 고정됩니다.
제스처 처리 및 가상 씬 조작하기
AR 폰은 유일하게 입력을 사용하는 블루프린트이기 때문에 모든 제스처 인식을 담당합니다.
InputTouch 이벤트는 사용자가 평면을 선택했는지 여부에 따라 평면 선택이나 가상 오브젝트 배치 중 하나의 단일 터치 입력을 처리합니다. 두 손가락을 사용하는 제스처와 스와이프는 사용자가 가상 오브젝트를 선택할 때까지 사용할 수 없기 때문에 이 터치 입력은 매우 단순하며 특별한 입력 액션이 전혀 필요하지 않습니다.
사용자가 평면을 배치했고 가상 오브젝트를 선택한 후에는 입력은 OneFingerAction 및 TwoFingerAction 입력 액션과 TwoFingerMapping 입력 축에 의해 처리됩니다. 이러한 입력은 프로젝트 세팅(Project Settings) > 입력(Input) 카테고리의 입력 바인딩에 정의되어 있습니다.
OneFingerAction과 TwoFingerAction 입력 액션은 AR 폰의 이벤트 그래프에서 이벤트로 표시됩니다. 이 이벤트는 평면 및 오브젝트와 인터랙션할 때 어떤 함수도 트리거하지 않습니다. 대신 AR 폰이 일반 입력을 처리하는 동안 적절한 제스처 타입을 선택하는 데 사용할 수 있는 데이터를 기록합니다.
Tick 이벤트는 인식된 제스처 리셋(Reset Recognized Gesture) 을 호출하여 이전 제스처에 대한 정보를 정리하고 한 손가락 제스처 인식(One Finger Gesture Recognition) 및 두 손가락 제스처 인식(Two Finger Gesture Recognition) 함수를 호출하여 입력 액션 이벤트에서 수집한 데이터를 처리합니다. 여기에는 터치 입력의 위치, 방향 및 이동 거리에 대한 델타가 포함됩니다.
이러한 함수는 제스처에 적합한 열거형인 현재 트랜스포메이션(Current Transformation) 을 설정합니다. 그런 다음 현재 트랜스포메이션의 스위치는 이동(Translate), 회전(Rotate) 또는 스케일(Scale) 함수를 선택된 배치 가능 오브젝트에서 사용할지 선택합니다. 오브젝트 자체가 이러한 트랜스포메이션 함수를 처리합니다.
배치 가능 오브젝트
BP_Placeable 블루프린트는 휴대형 AR 템플릿의 모든 배치 가능 오브젝트(평면 포함)의 베이스 클래스입니다. 이 블루프린트는 배치 가능 가상 오브젝트와 관련된 모든 것을 캡슐화합니다. 여기에는 비주얼, 트랜스포메이션 로직, 위젯 컴포넌트와의 HUD 인터랙션 로직 등이 포함됩니다. BeginPlay 시 배치 가능 오브젝트는 사용자가 제품 에셋 할당(Assign Product Asset) 함수를 사용하여 생성하는 제품 타입을 기반으로 에셋을 선택합니다. 선택된 모델은 템플릿을 구성할 때 선택한 카테고리에 따라 달라집니다.
| 애플리케이션 카테고리 | 모델 |
|---|---|
| 게임(Games) | 
|
| 자동차, 제품 디자인 및 제조(Automotive, Product Design, and Manufacturing) | 
|
| 건축, 엔지니어링 및 건설(Architecture, Engineering, and Construction) | 
|
비주얼 제어하기
배치 가능 오브젝트는 비주얼 설정(Set Visuals) 함수를 사용하여 모델의 머티리얼 및 이와 함께 표시되는 UI 위젯의 디스플레이를 모두 제어합니다. 이 함수는 배치 가능 위치 설정(Set Placeable Position), 배치 가능 회전 설정(Set Placeable Rotation) 및 배치 가능 스케일 설정(Set Placeable Scale) 에서 호출됩니다.
인터랙션이 활성화되어 있는 경우, Tick 이벤트는 인터랙션 업데이트(Update Interaction) 를 호출합니다. 이 함수는 사용자의 배치 가능 오브젝트를 이동, 회전 및 스케일하는 방법을 기반으로 하는 새로운 정보로 해당 배치 가능 오브젝트의 UI 위젯을 업데이트합니다. 각 트랜스포메이션에 적합한 텍스트를 구하는 유틸리티 함수는 다양합니다.
AR 평면에 오브젝트 배치하기
AR 폰이 InputTouch 이벤트에서 BP_Placeable 액터를 스폰하고 배치 가능 오브젝트(Placeable Object) 변수에 할당합니다.
AR 평면
휴대형 AR 템플릿은 BP_Plane 액터를 사용하여 가상 평면을 나타냅니다. 이러한 가상 평면은 평면 후보 업데이트(Update Plane Candidate) 및 평면 후보 생성 함수를 사용하여 AR 폰에 의해 생성됩니다. 그런 다음 평면 후보 생성이 평면 초기화(Initialize Plane) 를 호출하여 BP_Plane의 머티리얼 및 컬러 구성을 처리합니다.
BP_Plane에 어태치된 스태틱 메시는 트라이앵글 2개로 구성된 단순 평면으로, 복합 콜리전이 켜져 있고 콜리전 프리셋(Collision Presets) 이 BlockAllDynamic 으로 설정되어 있습니다. 따라서 어떤 타입의 트레이스로든 평면의 표면을 탐지할 수 있습니다.
BP_Plane 액터의 디폴트 스테이트는 선택되지 않은 스테이트입니다. 이 스테이트에서는 DM_Scan 을 머티리얼 인스턴스로 사용하여 현재 디바이스가 환경 스캔 중임을 물결 표시로 나타냅니다.
플랫폼 스캔 머티리얼 구하기(Get Platform Scan Material) 함수는 사용자가 Android 또는 iOS 디바이스를 사용하는지 여부에 따라 DM_Scan을 ScanMaterial01 이나 ScanMaterial02 중 하나로 설정합니다.
평면 초기화 함수는 AR 폰이 취한 카메라 씬 뎁스를 사용하여 환경에 더 알맞게 시각적으로 잘라내기 위해 DM_Scan을 설정하려고 시도합니다. 또한 AR 폰에서 평면 컬러 구하기(Get Plane Color) 를 사용하여 컬러도 설정합니다. 이 함수는 AR 지오메트리 인덱스를 가져와 컬러를 선택하는 데 사용합니다. AR 툴키트가 환경에서 새 지오메트리를 찾으면 컬러는 바뀔 수 있습니다.
사용자가 오브젝트를 배치할 평면을 선택하면 AR 폰은 BPPlane 선택됨(BPPlane Is Selected) 이벤트 디스패처를 호출합니다. 메인 메뉴는 이 이벤트를 사용하여 배치 오브젝트 스테이트로 전환합니다. 사용자가 오브젝트를 평면에 배치하면 해당 평면이 숨겨지므로 디스플레이가 더 몰입적이 됩니다. 이상적으로는 평면이 표시되지 않는 상황에서도 충분히 직관적으로 느껴질 정도로 스캔된 오브젝트가 사용자의 환경에 가깝게 일치되어야 합니다.
사용자가 배치 가능 오브젝트에 이동 함수를 사용하는 경우 AR 폰은 머티리얼 이동으로 전환(Switch to Material Translate) 함수를 호출하여 평면의 머티리얼 인스턴스를 DM_Scan에 비해 외곽선이 덜 거슬리는 DM_Plain 으로 변경합니다. 이를 통해 사용자는 오브젝트를 움직일 수 있는 경계를 더 쉽게 확인할 수 있게 됩니다.
HUD 및 UI 위젯
이 섹션에서는 휴대형 AR 템플릿에서의 HUD 구성 요소에 대한 레퍼런스를 제공합니다. 아래에서는 스타일링이나 모드 변경 등 UI 클래스가 체계화되는 방식과 핵심 기능을 제공하는 방식에 대해 설명합니다.
UI 스타일 및 BP_StylizedUI
휴대형 AR 템플릿의 모든 메뉴는 BP_StylisedUI를 부모 클래스로 사용합니다. 이 클래스는 UI 스타일을 라이트, 다크 및 게임 테마로 변경하는 데 필요한 모든 함수와 관련 데이터를 캡슐화합니다. 이 테마는 범용 UI 컬러, 폰트 및 아이콘 관련 정보를 갖춘 DT_Styles 데이터 테이블에 포함됩니다.
스타일 데이터 구하기(Get Style Data) 함수는 현재 선택된 스타일에 관련된 정보를 가져와 다른 함수에서 사용하기 위해 이 정보를 출력합니다.
BP_MainMenu 는 스타일 전환 호출(Call Switch Style) 함수를 사용하여 각 서브메뉴마다 스타일 전환을 트리거합니다.
그러면 서브메뉴는 자신의 UI를 변경할 이벤트를 BP_StylizedUI에 의해 정의된 스타일 전환(Switch Style) 이벤트 디스패처에 바인딩합니다.
UI_CapsuleButton 같은 다른 위젯은 부모 메뉴에 의해 수동으로 호출되는 자체 스타일 변경(Change Style) 함수를 정의합니다.
이 디자인은 UI 스타일을 정의하는 데이터 기반 메서드를 제공하며, UI 스타일 및 레이아웃을 대규모로 변경하는 작업을 지원하는 데 필요한 복제를 최소화할 수 있게 해줍니다.
메인 메뉴
BP_MainMenu는 다른 모든 메뉴의 컨테이너 겸 매니저 역할을 합니다. AR 폰이 뷰포트에 추가되면 다른 모든 메뉴를 초기화하고, 메뉴별 이벤트 디스패처를 바인딩하고, 사용자 과정에서 대응되는 특정 단계에 이벤트 디스패처를 바인딩합니다. 또한 AR 세션을 시작하는 작업도 담당합니다. 하지만 자체적인 스타일 시각적 요소가 전혀 없기 때문에 BP_StylizedUI 대신 베이스 사용자 위젯(User Widget) 클래스를 확장합니다.
초기화 및 이벤트 바인딩
초기화됨(On Initialized) 이벤트 동안 메인 메뉴는 UI를 초기화하고, 디폴트 UI 스타일을 라이트(Light) 로 설정하고, 이벤트 디스패처를 UI의 모든 주요 기능에 바인딩합니다. 여기에는 템플릿의 사용자 과정의 단계 초기 튜토리얼 팝업 표시, 스크린샷 찍기나 다른 서브 메뉴로의 전환 및 세팅 변경 확인 등의 워크플로가 포함됩니다.
이것은 굉장히 광범위한 이벤트 그래프지만, 서브 메뉴의 시각적 요소와 애플리케이션의 주요 기능을 밀접하게 연결해주는 역할을 한다고 생각하면 됩니다.
AR 세션 시작하기
사용자가 BP_StartMenu 의 버튼을 눌러 스캔을 시작하면 AR 세션이 시작됩니다.
스테이트 변경사항 처리하기
메인 메뉴의 Tick 함수는 AR 세션이 실행 중(Running) 스테이트에 도달하는지 수신합니다. 해당 스테이트에 도달하면 BP_StartMenu에 스캔 중 스테이트에 진입하도록 알리고, UI에 대해 장식성 변경사항을 트리거하여 스테이트 변경사항을 하이라이트합니다.
또한 Tick 함수는 이와 비슷하게 사용자가 오브젝트를 배치하기 시작하는 시점도 수신합니다. 이러한 변경사항은 AR 폰에서 검색된 스테이트 머신에 대응합니다.
서브 메뉴
메인 메뉴에는 서브 메뉴가 다수 임베딩되어 있습니다. 이 메뉴는 내부적인 스타일링 목적을 제외하면 주로 기능을 처리하는 이벤트 디스패처에 따라 장식성 요소와 레이아웃을 처리합니다. 모든 서브 메뉴는 BP_StylizedUI를 기반으로 스타일을 변경하는 작업을 지원하기 위한 일반 함수를 제공합니다.
시작 메뉴
BP_StartMenu는 사용자가 애플리케이션을 실행했을 때 처음 표시되는 메뉴로서 오버레이를 처리하고, 사용자 과정을 진행하도록 안내하며, 단계를 진행할 때마다 피드백을 제공합니다. 시작 메뉴는 화면 전체에 오버레이되며 각 개별 사용자 과정 스테이트에 대한 별도의 오버레이를 포함합니다. 예를 들어 시작 메뉴는 사용자가 평면에 사용할 환경을 스캔 중인 경우 UI_Scanning 을 표시하고, 평면을 선택하여 오브젝트를 배치할 준비가 되면 UI_PlaceObject 를 표시합니다.
하단 메뉴
사용자가 사용자 과정을 진행하여 오브젝트를 배치하면 BP_BottomMenu 가 화면 하단에 표시되어 옵션 메뉴(Options Menu), 정보 메뉴(Info Menu), 스냅샷(Snapshot) 및 기능 리셋(Reset functions)에 액세스할 수 있게 해줍니다.
하단 메뉴는 라이트 및 다크 테마에 의해 사용되는 가로 레이아웃에 대한 별도의 오버레이와 게임 테마에 사용되는 원형 레이아웃도 갖추고 있습니다. 이러한 두 가지 레이아웃의 버튼 버전은 중복을 피하기 위해 동일한 커스텀 이벤트를 바인딩합니다.
옵션 메뉴
BP_OptionMenu 는 사용자가 하단 메뉴에서 '옵션(Options)' 버튼을 탭할 때 표시되는 메뉴입니다. 이 메뉴는 UI 스타일 전환 기능을 포함한 몇 가지 환경설정 옵션을 제공합니다. 이 메뉴의 UI 버튼은 메인 메뉴의 기능에 바인딩되어 AR 폰 및 UI의 다른 부분에서 트리거해야 할 수도 있는 다른 함수에 더 나은 비저빌리티를 제공합니다.
정보 메뉴
BP_InfoMenu 는 사용자가 하단 메뉴에서 정보(Info) 버튼을 탭할 때 표시되는 메뉴입니다. 이 메뉴는 배치 가능 오브젝트를 사용하여 작업하는 제스처를 표시합니다.
버튼
UI_CapsuleButton 및 UI_ToggleButton 은 모든 메뉴에서 사용됩니다. 스타일 변경 및 특정 버튼의 행동(토글 등) 같이 광범위한 공통 기능을 지원할 수 있도록 커스터마이징할 수 있습니다.