헤드셋 확장 실행 검증(bring-up)

EasyAR가 기기에서 작동하도록 하기 위해 가장 중요하면서도 까다로운 작업은 입력 데이터의 정확성을 보장하는 것입니다. 새로운 기기에서 EasyAR를 처음 실행할 때 발생하는 문제의 90% 이상이 잘못된 데이터로 인해 발생합니다.

가능하다면, EasyAR 없이 기기 및 기기 인터페이스만을 사용하여 테스트 방법으로 직접 데이터 정확성을 검증하는 것이 좋습니다. 이 문서는 EasyAR 기능을 활용하여 데이터를 검증하는 경험적 방법을 소개합니다. 이 과정은 외부 입력 프레임 데이터를 이해하는 데 도움이 되지만, EasyAR 자체에도 오차가 존재하기 때문에 결합된 시스템을 사용하여 데이터 정확성을 검증하는 것은 최선의 선택이 아닙니다.

시작하기 전에

헤드셋에 EasyAR 지원 추가 개발을 완료하세요.
빠른 시작을 읽고 EasyAR Sense Unity 플러그인 사용법을 익히세요.
헤드셋 샘플 사용법을 숙지하세요.
Android 프로젝트 구성 방법을 이해하세요.

실행 기본 기능 예제

처음 기기에서 EasyAR 검증을 실행할 때는 다음 기능들을 순서대로 실행해야 하며, 특히 Mega를 서두르지 않는 것이 중요합니다. 왜냐하면 Mega는 일정한 오류 허용 범위를 가지므로 단시간 실행이나 단일 현실 시나리오에서는 문제를 발견하기 어렵기 때문입니다.

시야에 표시되는 세션 정보를 관찰하여 예상치 못한 상황이 발생하지 않는지 확인하고, 프레임 카운트가 지속적으로 증가하는지 확인하세요.
Image 즉 이미지 추적 기능을 실행하고, 휴대폰 실행 결과와 비교하여 일치하는지 확인하세요(iPhone을 기준으로 권장). 추적 상태와 대상 오버레이 표시에 주목하세요.

모션 퓨전이 활성화되지 않은 상태에서는 이미지 추적에 뚜렷한 지연이 발생할 수 있으며, 이는 예상된 현상입니다. 움직임 과정이 정확하고 기기가 멈췄을 때 위치가 정렬되면 됩니다.
Dense 즉 고밀도 공간 매핑 기능을 실행하고, 휴대폰 실행 결과와 비교하여 일치하는지 확인하세요(iPhone을 기준으로 권장). 메시 위치, 생성 속도 및 품질에 주목하세요.

입력 데이터 프레임 속도가 낮으면 메시 생성 속도가 느려질 수 있지만, 품질은 눈에 띄게 저하되지 않습니다.

이 기능은 일부 Android 기기에서 실행되지 않을 수 있으며, 메시 품질도 기기에 따라 달라집니다.

[!중요] 헤드셋 확장 패키지에서 사용하는 입력 확장은 사용자 정의 카메라 구현입니다.

사용자 정의 카메라 또는 헤드셋에서 평가판 제품(개인판 license, 평가판 XR license 또는 평가판 Mega 서비스 등)을 사용할 때, EasyAR Sense는 시작 후 100초(Mega 사용자는 EasyAR 비즈니스를 통해 승인 후 시간 조정 가능) 후에 응답을 중지합니다. 유료 버전의 EasyAR Sense와 유료 EasyAR Mega 서비스를 사용할 때는 이 제한이 없습니다.

Image 및 Dense 기능이 휴대폰에서와 동일하거나 더 나은 성능을 보인다면, 대부분의 EasyAR 기능이 기기에서 정상 작동한다는 의미이며 Mega 테스트를 시작해도 좋습니다.

실행 중 예외 상황 해결: 문제 분해

휴대폰에서 동일한 결과를 재현할 수 없는 경우, 다음은 근본 원인을 찾기 위해 참고할 수 있는 상세한 문제 분해 과정입니다. 항상 시스템 로그 출력에 주의를 기울이는 것이 좋습니다.

Step zero: 헤드셋 자체 시스템 오차 이해하기

기기를 AR/MR에 맞게 준비하기에서 설명한 모션 트래킹과 디스플레이 요구사항을 기억하시나요?

중요

모션 트래킹/VIO 오차는 항상 다양한 방식으로 EasyAR 알고리즘의 안정성에 영향을 미칩니다.

중요

디스플레이 시스템 오차는 가상 물체와 실제 물체가 완벽하게 정렬되지 못하게 할 수 있습니다.

오차가 큰 일부 경우에는, 가상 물체가 실제 물체 위 또는 아래에 떠 있는 것처럼 보이고, 계속해서 표류하는 것처럼 보일 수 있습니다. 이 현상은 EasyAR를 사용하지 않고 자체 VST만 켠 상태에서도 Pico 4E에서 관찰할 수 있습니다.

Step one: view session running status

UI 메시지의 세션 상태가 정상적으로 표시되기 위해 반드시 정상 작동해야 하는 기능 또는 데이터:

ExternalFrameSource의 가용성

ExternalFrameSource의 가상 카메라

세션 상태 정보 표시가 보이지 않으면, 옵션을 Log로 수정한 후 시스템 로그에서 세션 상태와 사용 중인 프레임 소스의 이름을 확인하세요.

ARSession 노드 아래의 다른 모든 프레임 소스를 삭제한 후 변화가 있는지 확인해 볼 수 있습니다.

단계 2: easyar가 수신하는 카메라 프레임 카운트 확인

필수적으로 정상 작동해야 하는 기능 또는 데이터:

ExternalFrameSource의 카메라 프레임 데이터가 Unity 코드 레이어에서의 경로 (데이터 정확성 및 네이티브 레이어까지의 데이터 경로는 제외)

이 데이터는 시간에 따라 증가해야 합니다. 그렇지 않으면 몇 초 후에 경고 메시지가 표시됩니다.

이 값이 증가하지 않는다고 확인되면, 가장 먼저 해결해야 합니다.

단계 3: 장치에서 EIF 녹화하기, 그리고 Unity 에디터에서 재생하기

정상적으로 동작하거나 제공되어야 하는 기능 또는 데이터:

ExternalFrameSource의 카메라 프레임 데이터가 네이티브 레이어로 입력되는 경로 (데이터 정확성은 불포함)

카메라 프레임 데이터 내의 raw camera image data

카메라 프레임 데이터 내의 timestamp (시간점 및 데이터 동기화는 불포함)

EIF를 클릭하여 녹화를 시작하고, 다시 클릭하여 정지합니다.

팁

재생 시 임의로 접근할 수 있는 EIF 파일을 얻으려면 반드시 녹화를 정상적으로 중지해야 합니다.

Unity 에디터에서 EIF 데이터를 실행할 때는 깨끗한 EasyAR 씬을 사용하거나, 잘못된 구성이 씬에 존재하지 않도록 하기 위해 EasyAR의 예제를 사용하는 것이 좋습니다.

Unity 에디터에서 카메라 프레임 데이터의 재생을 볼 수 있습니다. 이미지 데이터는 바이트 단위로 동일하지 않으며, 전체 흐름에서 손실이 있는 압축/해제 과정이 존재합니다.

EasyAR은 계산 시 왜곡 파라미터를 사용하지만 이미지를 표시할 때는 왜곡 보정을 적용하지 않습니다. 따라서 이러한 데이터를 입력하면 Unity에서 EIF 파일을 재생할 때 왜곡 보정이 적용되지 않은 데이터가 관찰되는데, 이는 예상된 동작입니다.

팁

입력된 데이터와 동일한 비율로 Unity game 창의 비율을 수정하세요. 그렇지 않으면 데이터가 잘려서 표시됩니다.

데이터 재생 속도가 너무 빠르거나 느리다면 timestamp 입력을 점검해야 합니다.

참고

EIF를 사용하면 다양한 작업을 수행할 수 있습니다. Unity 에디터 내에서 EIF를 이용해 이미지 추적 및 밀집 공간 매핑을 실행할 수 있습니다. 단, 장치에서 실행했을 때의 표시 효과와는 다를 수 있습니다.

Step four: EIF를 사용하여 이미지 추적 실행하기

필수로 정상 작동해야 하는 기능 또는 데이터:

카메라 프레임 데이터 내 raw camera image data

카메라 프레임 데이터 내 intrinsics (알고리즘이 오차에 어느 정도 내성이 있으므로 데이터 정확성은 완전히 보장되지 않음)

Unity 에디터에서 EIF를 사용하여 이미지 추적 샘플 ImageTracking_Targets를 실행하려면, 이미지가 추적 가능한 EIF를 녹화해야 합니다.

참고

이미지 추적은 추적 대상이 전체 이미지의 일정 비율을 차지해야 합니다. 이미지를 추적할 수 없다면, 헤드를 대상 이미지에 더 가까이 이동해 보세요.

추적이 지속적으로 실패하거나 가상 오브젝트가 대상에서 멀리 떨어진 위치에 표시된다면, intrinsics에 문제가 있을 가능성이 높습니다.

이미지 데이터에 왜곡이 있는 경우, 가상 오브젝트가 추적 대상 위에 완벽하게 겹쳐지지 않는 현상을 관찰할 수 있으며 이는 예상된 현상입니다. 추적 대상이 이미지 가장자리에 위치할 때 이 현상은 더 두드러집니다.

단계 5: 기기에서 이미지 추적 실행

반드시 정상 작동해야 하는 기능 또는 데이터:

기기 자체의 디스플레이 시스템

카메라 프레임 데이터의 raw camera image data

카메라 프레임 데이터의 intrinsics (오차에 대한 알고리즘 내성이 존재하므로 데이터 정확성은 완전히 보장되지 않음)

카메라 프레임 데이터의 extrinsics

카메라 프레임 데이터와 렌더링 프레임 데이터에서 device pose의 좌표 일관성

카메라 프레임 데이터와 렌더링 프레임 데이터에서 device pose의 시간 차

참고

이미지 추적은 추적 대상이 전체 이미지의 일정 비율을 차지해야 합니다. 이미지를 추적할 수 없다면, 머리를 이미지에 더 가까이 이동해 보세요.

이미지 추적은 이미지의 가로 길이가 실제 물체의 크기와 일치해야 합니다. 이 예시에서는 가로로 놓인 A4 용지의 긴 변을 가득 채우는 가로 길이의 이미지를 추적해야 합니다. 따라서 자를 사용하여 이미지의 가로 길이를 A4 크기로 조정하지 않는 한, 컴퓨터 화면에 표시된 이미지를 추적하지 마세요.

EIF를 사용할 때 이미지 추적이 완벽하게 작동하지만 기기에서는 그렇지 않은 경우, 다른 테스트를 진행하기 전에 이를 해결해야 합니다. 후속 단계에서 문제를 해결하는 것은 훨씬 더 어렵습니다.

가상 물체가 실제 물체에서 멀리 떨어진 곳에 공중에 떠 있는 것처럼 보이고, 사람이 움직이지 않아도 그런 상태라면, intrinsics 또는 extrinsics가 올바르지 않거나, 카메라 프레임 데이터와 렌더링 프레임 데이터의 device pose가 동일한 좌표계에 있지 않거나, 디스플레이 시스템에서 이 오차를 발생시켰을 가능성이 큽니다.

가상 물체가 머리를 움직일 때 지속적으로 움직이고 지연이 있는 것처럼 보인다면, device pose가 정상적이지 않을 가능성이 높습니다. 이는 주로 다음과 같은 상황에서 발생합니다(다른 문제 가능성도 배제할 수 없음).

device pose와 raw camera image data의 데이터 시간이 동기화되지 않음
카메라 프레임 데이터와 렌더링 프레임 데이터에서 동일한 pose가 사용됨

Step 6: EIF를 사용하고 기기에서 dense spatial map 실행하기

정상적으로 작동해야 하는 기능 또는 데이터:

기기 자체의 디스플레이 시스템

카메라 프레임 데이터 내 raw camera image data

카메라 프레임 데이터 내 intrinsics (데이터 정확성은 완전히 보장되지 않음. 알고리즘이 오차에 대한 내성을 갖고 있기 때문)

카메라 프레임 데이터 내 extrinsics

카메라 프레임 데이터 내 device pose

메시 생성 속도가 매우 느리고/또는 지면 재구성이 울퉁불퉁하다면, device pose에 문제가 있을 가능성이 높습니다. pose의 좌표계가 올바르지 않거나 pose의 시점이 맞지 않을 수도 있습니다.

팁

입력 데이터 프레임 속도가 낮으면 메시 생성 속도도 느려지지만, 품질이 현저히 나빠지지는 않습니다. 이는 예상된 동작입니다.

일반적으로 메시의 정확한 위치를 식별하는 것은 매우 쉽지 않으므로, dense spatial map을 사용할 때 디스플레이 시스템 오류를 관찰하기 어려울 수 있습니다.

실행 mega 예제

아래 내용을 읽고 unity에서 mega를 사용하는 방법을 알아보세요. 아직 mega 서비스를 활성화하지 않았다면, easyar 비즈니스에 문의하여 평가판 자격을 획득해야 합니다.

그런 다음 기기에서 Mega를 실행하고 모바일 실행 효과와 비교해 일치하는지 확인하세요(iphone을 기준으로 권장). 다음 사항에 주목하세요:

오브젝트 표시 위치가 정확한지
먼 거리(10m 이상)의 오브젝트 표시 위치와 크기가 정확한지
시선 중심 이외의 오브젝트 표시 위치와 크기가 정확한지
머리를 돌릴 때 오브젝트 표시 위치와 크기가 정확한지

실행 중 예외 상황 해결

정상적으로 작동해야 하는 기능 또는 데이터:

디바이스 자체의 디스플레이 시스템

카메라 프레임 데이터 및 렌더링 프레임 데이터 내 모든 데이터

이미지 트래킹 및 조밀한 공간 매핑 두 기능의 검증을 완료한 후, 이론적으로 EasyAR Mega는 지원되어야 합니다. 헤드셋에서 실행 시 휴대폰보다 성능이 현저히 떨어진다면 다음 사항에 주의해야 합니다,

카메라 프레임 데이터 및 렌더링 프레임 데이터 내 pose 데이터와 timestamp에 주의
모션 트래킹/VIO 시스템 출력에 주의. XR Origin 하단의 팬더가 좋은 참고가 될 수 있음

또한, 디바이스 자체의 디스플레이 시스템에 특히 주의해야 하며, 멀리 떨어진 곳, 시야 중심부 외곽 및 머리를 회전할 때의 객체 표시 효과에 더욱 유의해야 합니다. 이러한 장면은 디바이스 자체 테스트 시 자주 간과되지만, 문제는 여전히 대부분 디바이스 자체의 디스플레이 시스템에서 비롯됩니다. 해당 문제와 가능한 영향을 EasyAR에 설명하고, 개발자에게 합리적인 효과 기대치를 제공해야 합니다.

중요

사용자는 이러한 디스플레이 문제를 매우 중요하게 여기며, 많은 디바이스가 실제로 대규모 공간 장면에서 완벽한 디스플레이 효과를 제공하지 못합니다. EasyAR은 디바이스 자체의 디스플레이 문제를 해결할 수 없으며, 이는 디바이스 제조사의 지속적인 개선이 필요합니다. 동시에 사용자도 이러한 문제를 이해해야 합니다.

후속 단계

Publish extension package

Table of Contents