Mega 위치 실패 문제 해결 가이드

Mega는 고급 비주얼 위치 알고리즘을 기반으로 클라우드 Mega Block 검색과 시각 특징 매칭 계산을 통해 고정밀 위치 추정을 구현합니다. 따라서 실제 사용 과정에서는 설정 오류, 환경 변화, 네트워크 변동 등 다양한 원인으로 위치 실패가 발생할 수 있습니다.

이 문서는 위치 상태를 빠르게 판단하고 "정상 대기"와 "비정상 오류"를 구분하며, 설정, 환경, 서비스 세 가지 요소에 따라 빠르게 진단할 수 있도록 돕기 위한 것입니다.

위치 프로세스

대상 구역에서 지도 구축 데이터 수집을 수행하고 Mega Block 구축을 완료한 뒤, 재구축된 Mega Block을 위치 라이브러리에 추가하고 위치 라이브러리 사용 가능 여부를 확인해야 합니다.

이미 구축된 Mega Block이 커버하는 구역 안에서, 환경 조명이 좋고 특징이 풍부하며 네트워크가 정상이라면 보통 몇 초 안에 위치 추정에 성공할 수 있습니다. 위치 추정에 성공하면 현재 장치가 Mega Block 안에서 가지는 위치와 자세가 반환됩니다.

위치 상태 판단

• Mega Toolbox를 사용하여 위치 결과를 검증하는 경우 위치 상태를 직접 확인할 수 있습니다.

  

• Unity 개발자라면 위치할 수 없을 때 화면에서 위치 반환의 구체적인 정보인 MegaTrackerLocalizationStatus를 확인할 수 있습니다. 화면에 이 정보가 없다면 진단 정보를 켜야 합니다.

  

MegaTrackerLocalizationStatus의 가능한 값

Constant	Value	Description
UnknownError	0	알 수 없는 오류
Found	1	Block 위치 추정 성공
NotFound	2	Block 위치 추정 실패
RequestTimeout	3	요청 타임아웃(1분 초과)
RequestIntervalTooLow	4	요청 간격이 너무 짧음
QpsLimitExceeded	5	QPS 제한 초과
WakingUp	6	서비스가 깨어나는 중
MissingSpotVersionId	7	SpotVersionId 누락, 설정하지 않았을 수 있음
ApiTokenExpired	8	API Token 만료

위 이상 상태의 해결 방법:

• 요청 타임아웃: 네트워크 상태를 확인하고 수정합니다. 필요한 경우 요청 타임아웃 시간 MegaRequestTimeParameters.Timeout을 늘릴 수 있지만, 네트워크 상태가 좋지 않으면 추적 효과에도 영향을 주므로 네트워크 문제를 최대한 해결해야 합니다.
• 요청 간격이 너무 짧음: 요청 간격을 낮춥니다.
• 연결 또는 전송 실패: 네트워크 상태를 확인하고 수정합니다.
• QPS 제한 초과: EasyAR 비즈니스 담당자에게 연락하여 QPS 용량을 확장합니다.
• 서비스가 깨어나는 중: 시스템이 깨어나는 중이므로 잠시 기다린 뒤 다시 시도합니다.
• SpotVersionId 누락: SpotVersionId를 설정하십시오.
• API Token 만료: EasyAR 관리 백그라운드에서 API Token을 다시 생성하십시오.

UnknownError의 일반적인 경우는 두 가지입니다.

• 연결 또는 전송 실패
• 서비스 반환 예외

UnknownError의 경우 MegaLocalizationResponse.ErrorMessage를 통해 자세한 정보를 얻을 수 있습니다.

일반적인 오류 분류 및 문제 해결

위치 반환 상태 및 현상에 따라 일반적인 문제는 설정 문제, 환경 요인, 서비스 자체의 세 가지 유형으로 나눌 수 있습니다.

설정 문제

이 유형의 문제는 보통 개발 연동 단계에서 발생하며, 서비스가 전혀 시작되지 않는 형태로 나타납니다.

License 관련

개발 또는 테스트 과정에서 로그나 화면에 License, Invalid Key 등의 문제가 표시된다면 AppID/BundleID 불일치, License 만료, 플랜 불일치 등이 원인일 수 있습니다. 아래 표와 대조하여 License 설정을 확인하십시오.

오류	해결 방법
Invalid Key: No matched Bundle ID	Bundle ID와 license key가 일치하지 않습니다. 둘 중 하나를 수정하여 일치시키십시오.
Invalid Key: No matched Package Name	Bundle ID와 license key가 일치하지 않습니다. 둘 중 하나를 수정하여 일치시키십시오.
Invalid Key: License does not apply to current variant	엔터프라이즈 패키지 SDK를 사용하면서 엔터프라이즈판 license key가 아니거나, 비엔터프라이즈 패키지 SDK를 사용하면서 엔터프라이즈 패키지 license key를 사용했습니다.
Invalid Key: License for an old version does not apply	license 버전이 너무 오래되었습니다. 새 license를 다시 만들어야 합니다.
Invalid Key: Invalid format	license 형식이 잘못되었습니다. 예를 들어 전체를 복사하지 않았을 수 있습니다.
Invalid Key: Server verification failed	license가 삭제되었거나 장치 사용 권한이 없습니다. 헤드셋 사용인 경우 비즈니스 담당자에게 연락하여 권한을 추가하십시오.
License does not apply to eyewear	license를 헤드셋에서 사용할 수 없습니다. xr license로 교체하십시오.
License is expired	license가 만료되었습니다.

또한 체험판 License에는 일부 제한이 있다는 점에 유의해야 합니다. 유료 버전의 EasyAR Sense와 유료 EasyAR Mega 서비스를 사용하면 이 문제를 해결할 수 있습니다. 이미 유료 버전의 EasyAR Sense를 사용 중이라면 sample에서 관련 문구를 무시하거나 직접 삭제할 수 있습니다.

카메라 화면 이상

EasyAR Mega 애플리케이션을 개발하거나 테스트하는 과정에서 검은 화면, 충돌, 카메라 화면 없음 등의 이상 문제가 발생하면 다음 단계에 따라 체계적으로 조사하고 정보를 수집하십시오.

1. 직접 해결 시도

• Unity로 개발 테스트 중이라면 AR Session (EasyAR) -> Inspector에서 Diagnostics Controller (Script)를 선택하여 진단 정보를 켰는지 확인하십시오.

  

• 화면이나 로그에 표시된 내용을 확인하고 UI에 명확한 문자 안내가 있는지 검사합니다.

• 대부분의 경우 오류 정보에는 자체 설명이 있습니다. 화면 정보나 로그가 오류 원인을 이미 설명했다면 구체적인 원인에 따라 해결할 수 있습니다. 예: cameraDevice.openWithPreferredType fail(카메라 사용 가능 여부 확인 필요).

• "지원하지 않음"이라는 안내가 표시되는 경우(예: 장치가 ARCore 또는 기타 기능을 지원하지 않음)는 정상적인 제한이며 추가 조사가 필요하지 않습니다.

2. 직접 해결할 수 없음

   먼저 기존 정보를 바탕으로 직접 해결을 시도하십시오. 직접 해결할 수 없다면 EasyAR 담당자가 문제를 빠르게 찾을 수 있도록 상세하고 재현 가능한 기술 정보를 반드시 제공하십시오. "검은 화면"과 같은 현상만 설명하지 마십시오. 권장 피드백 내용은 다음과 같습니다.

• 전체 로그: Unity 또는 Sense
• 화면 캡처 또는 화면 녹화: 검은 화면 시의 전체 화면. 진단 정보가 있다면 보이도록 캡처해야 합니다.
• 자세한 장치 정보: 장치 모델(예: iPhone 15, HUAWEi P40), 시스템 버전(예: iOS 17.1, Android 14), EasyAR Sense 버전, EasyAR Sense Unity Plugin 버전, Unity 버전 등.

현장에서 실행하지 않아 계속 NotFound

개발자가 사무실에서 시뮬레이터나 화면 녹화를 사용해 테스트하지만 계속 위치 추정에 실패합니다. 가능한 원인은 MegaLocationInputMode 모드가 Onsite로 설정되어 있지만 실제 현장에서 실행 중이 아니기 때문입니다. Mega 위치 입력 모드에 따라 개발 과정에서 올바른 모드를 선택해야 합니다.

Constant	Value	Description
Onsite	0	현장에서 사용하는 경우의 입력 모드. 위치 데이터는 보통 장치에서 가져와 Mega에 입력되며 일반적으로 FrameFilter 내부에서 처리됩니다.
Simulator	1	원격으로 사용하는 경우의 입력 모드. 위치 데이터를 현장 데이터처럼 시뮬레이션하여 해당 인터페이스를 통해 Mega에 입력해야 합니다(선택 사항).
FramePlayer	2	FramePlayer를 사용할 때의 입력 모드입니다. 이 모드는 읽기 전용입니다.

환경 요인으로 인한 문제

이 유형의 문제는 서비스는 정상이지만 위치 결과가 계속 NotFound로 반환되는 형태로 나타납니다.

흰 벽이나 바닥을 향하면 계속 NotFound

카메라 화면에 넓은 흰 벽, 유리 또는 단색 바닥이 보이면 상태가 계속 NotFound를 반환합니다.

원인: 비주얼 위치 추정은 텍스처 특징에 의존합니다. 약한 텍스처 구역에서는 특징점을 추출할 수 없습니다.

해결 방법: 이는 정상적인 현상입니다. 카메라를 텍스처가 풍부한 구역으로 이동하여 시작해야 합니다.

현장이고 텍스처가 풍부하지만 계속 NotFound

사용자가 현장에 있고 텍스처가 있는 구역을 향하고 있지만 오랫동안 위치 추정에 성공하지 못합니다.

가능한 원인:

• 장면 변화: 현장 환경(예: 인테리어 변경, 포스터 교체, 조명 변화가 큼)이 지도 구축 당시 장면과 너무 크게 다릅니다.
• 수집 미커버: 사용자가 서 있는 위치가 당시 수집해 지도 구축한 커버 범위를 벗어났습니다.

해결 방법:

• 당시 수집 경로 구역으로 이동하여 시도합니다.
• 장면에 영구적이고 큰 변화가 발생했다면 다시 수집하고 Block을 업데이트해야 합니다.

서비스 자체로 인한 문제

Block을 방금 추가했으며 계속 WakingUp

위치 라이브러리를 방금 설정했거나 위치 라이브러리를 방금 시작했을 때 서비스 상태가 WakingUp으로 표시되거나 오랫동안 NotFound로 유지될 수 있습니다. Mega 서비스에는 콜드 스타트 메커니즘이 있어 최초 로드 시 콜드 스토리지에서 깨어나야 하기 때문입니다. 네트워크를 원활하게 유지하고 10~30초 기다린 뒤 다시 시도하면 됩니다.

서비스 반환 예외

Https status	Status code	원인
200	21	QPS 제한 초과
200	1040 x	매개변수, 라이브러리 또는 지도 데이터가 올바르지 않음. 구체적인 메시지 설명 참조
200	4000 x	알고리즘 수준 오류. 구체적인 설명 참조
401	-	인증 실패. 구체적인 메시지 설명 참조
404	-	URL의 경로 입력이 올바르지 않음
50x	-	서버 프로그램 오류

서비스 예외의 해결 방법:

• QPS 제한 발생: EasyAR 비즈니스 담당자에게 연락하여 QPS 용량을 확장합니다.
• 인증 실패 발생: 구체적인 메시지 설명에 따라 해결합니다. 일반적인 문제로는 장치 시간과 표준 시간의 편차가 너무 큼, API Key에 CLS 권한이 없음 등이 있습니다.
• 기타 상황: EasyAR 담당자에게 피드백하여 해결하십시오.

문제 피드백

위의 문제 해결 절차를 거친 후에도 문제가 해결되지 않으면 다음 단계에 따라 정보를 수집하고 EasyAR 기술 지원 팀에 피드백하십시오.

Mega 위치 서비스 정보 내보내기

• Unity 개발, 플러그인 버전 >= 4003
• Unity 개발, 플러그인 버전 4.7 - 4002
• 미니 프로그램 개발
• 기타 Mega Studio 사용 시나리오

사용 중인 block 노드의 에디터 도구에서 아래 그림의 Diagnosis Info 버튼을 클릭하여 Mega Block 진단 정보를 내보냅니다. Mega Block 진단 정보에는 Mega Block 및 위치 라이브러리 정보만 포함되며 기타 민감한 정보는 포함되지 않습니다.

내보낸 파일 형식은 Mega_Report_Block_<blockID>_YY-MM-DD_HH-MM-SS.json이어야 합니다.

EIF 파일 녹화

휴대폰 테스트 중 문제가 발생했다면 Toolbox로 휴대폰 EIF 파일 녹화를 사용하십시오.

헤드셋 테스트 중 문제가 발생했다면 Toolbox로 헤드셋 EIF 파일 녹화를 사용하십시오.

자체 애플리케이션에서 문제가 발생했다면 애플리케이션으로 EIF 파일 녹화를 사용할 수 있습니다.

WeChat 미니 프로그램을 사용할 때는 미니 프로그램으로 EIF 파일 녹화를 사용할 수 있습니다.

휴대폰, 글래스 등 장치로 문제 현상 녹화

AR 분야에서는 문자 설명만으로 정확한 정보를 전달하기 어려운 경우가 많고, 사람마다 이해가 크게 다를 수 있습니다. 동시에 런타임 화면 녹화는 매우 유용한 정보이며, 사용자와 EasyAR 담당자가 공통된 이해를 형성할 수 있게 합니다. 휴대폰, 글래스 등 장치의 내장 기능이나 타사 소프트웨어를 사용하여 녹화할 수 있습니다. 주의할 점은 화면 녹화 과정이 일반적으로 실행 효과에 영향을 주며, 추적 효과와 성능 모두 영향을 받을 수 있다는 것입니다.

참고

녹화 전에 런타임에서 해당 Sample을 참고하여 필요한 Debug 정보를 화면에 표시하는 것을 권장합니다. 화면 녹화를 제공할 때는 녹화 기간에 해당하는 EIF 데이터도 함께 제공해야 합니다.

Unity 개발 문제 피드백

Unity 개발 과정에서 일부 이상 문제가 발생한 경우, 아래 4개 항목을 완료했는지 하나씩 확인해야 합니다.

1. 최신 버전의 EasyAR Sense Unity Plugin을 시도했습니다. 새 버전에는 보통 bug 수정 및 새 기능이 포함되어 있으므로 먼저 최신 버전으로 업그레이드해 시도하는 것을 권장합니다.
2. EasyAR 개발 문서 및 Mega 가이드를 읽었습니다. 문서에는 보통 일부 상황 설명이 포함되어 있습니다.
3. 시스템 및 Unity 로그를 읽었습니다. 질문할 때 전체 로그를 제공하는 것을 권장합니다.
4. 빈 Unity 프로젝트에서 Sample 안에서 문제 재현을 시도했습니다.

위 4개 항목을 모두 완료했는데도 문제가 해결되지 않는다면 EasyAR Sense Unity Plugin에서 아래 절차에 따라 전체 정보를 제공하여 EasyAR 기술 담당자가 문제를 분석하고 해결할 수 있도록 하십시오.

1. Unity -> EasyAR -> Sense에서 질문을 선택합니다.

   

2. 질문에서 다음 정보를 제공해야 합니다.

   • 문제가 발생한 실행 환경을 선택합니다. 단일 환경만 선택할 수 있습니다.
   • 장치 정보를 복사합니다. EasyAR Session에서 DiagnosticsController.DumpSession을 Log로 설정하고 한 프레임의 출력을 복사해 아래 결과란에 입력합니다.
   • 문제가 발생했을 때 사용한 모든 EasyAR 기능을 선택합니다. 다중 선택을 지원합니다.
   • 위 4개 항목을 완료했는지 확인합니다. 질문 시 Sample에서 문제를 재현하는 방법을 설명하는 것을 권장합니다.
   • 오른쪽 위의 복사 기능을 클릭합니다. 질문 창을 처음 열면 아래 정보가 모두 표시되지 않으며, 사용하는 환경과 기능을 선택한 후에야 표시됩니다.

3. 아래의 EasyAR Q&A로 이동을 클릭하여 복사한 정보를 EasyAR 공식에 피드백하거나, EasyAR 담당자에게 직접 피드백합니다.