Mega 위치 확인 실패 문제 해결 가이드
Mega는 고급 vision-based 위치 확인 알고리즘을 기반으로, 클라우드 Mega Block 검색 및 시각 특징 매칭 연산을 통해 고정밀 위치 확인을 실현합니다. 따라서 실제 사용 과정에서 구성 오류, 환경 변화 또는 네트워크 변동 등 다양한 이유로 위치 확인 실패가 발생할 수 있습니다.
본 문서는 위치 확인 상태를 신속히 판단하고, "정상 대기"와 "비정상 오류"를 구분하며, 구성, 환경, 서비스 세 가지 주요 요인을 기준으로 신속한 진단을 돕기 위한 목적을 가지고 있습니다.
로케이션 프로세스
대상 영역에서 매핑 데이터 수집 및 Mega Block 구축이 필요합니다. 재구축된 Mega Block을 로케이션 라이브러리에 추가하고 로케이션 라이브러리 사용 가능 여부를 확인하세요.
Mega Block이 구축된 커버리지 영역 내에서 조명 환경이 양호하고 특징이 풍부하며 네트워크가 정상일 경우, 일반적으로 몇 초 이내에 로케이션이 성공합니다. 로케이션 성공 시 현재 디바이스의 Mega Block 내 위치 및 자세가 반환됩니다.
로컬라이제이션 상태 확인
Mega Toolbox를 사용하여 로컬라이제이션 결과를 검증하는 경우, 직접 로컬라이제이션 상태를 확인할 수 있습니다.
Unity 개발자로서 로컬라이제이션에 실패하는 경우, 화면에서
MegaTrackerLocalizationStatus로 반환된 구체적인 정보를 확인할 수 있습니다. 화면에 해당 정보가 표시되지 않는다면 진단 정보를 활성화해야 합니다.
MegaTrackerLocalizationStatus 가능한 값
| Constant | Value | 설명 |
|---|---|---|
| UnknownError | 0 | 알 수 없는 오류 |
| Found | 1 | Block 로컬라이즈됨 |
| NotFound | 2 | Block 로컬라이즈되지 않음 |
| RequestTimeout | 3 | 요청 시간 초과(1분 초과) |
| RequestIntervalTooLow | 4 | 요청 간격이 너무 짧음 |
| QpsLimitExceeded | 5 | QPS 제한 초과 |
| WakingUp | 6 | 서비스가 깨어나는 중 |
| MissingSpotVersionId | 7 | SpotVersionId 누락, 설정되지 않았을 수 있음 |
| ApiTokenExpired | 8 | API 토큰 만료 |
위 예외 발생 시 해결 방법:
- 요청 시간 초과: 네트워크 상태 확인 및 수정, 필요 시 요청 타임아웃 시간(MegaRequestTimeParameters.Timeout)을 높일 수 있으나 네트워크 상태 불량은 트래킹 성능에 영향을 미칠 수 있으므로 네트워크 문제를 해결해야 함
- 요청 간격이 너무 짧음: 요청 간격을 낮춤
- 연결 또는 전송 실패: 네트워크 상태 확인 및 수정
- QPS 제한 초과: EasyAR 영업 담당자에게 문의하여 QPS 확장 요청
- 서비스가 깨어나는 중: 시스템이 깨어나는 중이므로 잠시 대기 후 재시도
- SpotVersionId 누락: SpotVersionId를 구성하십시오
- API 토큰 만료: EasyAR 관리 콘솔에서 API 토큰을 재생성하십시오
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를 사용 중이라면 해당 내용을 무시하거나 샘플에서 직접 삭제하셔도 됩니다.
카메라 화면 이상
개발 또는 테스트 중 EasyAR Mega 애플리케이션에서 검은 화면, 강제 종료, 카메라 화면 없음 등의 이상 현상이 발생할 경우, 아래 단계에 따라 체계적으로 문제를 파악하고 정보를 수집하십시오.
- 자체 해결 시도
Unity로 개발/테스트하는 경우, AR Session (EasyAR) -> Inspector에서 Diagnostics Controller (Script)를 체크하여 진단 정보가 활성화되었는지 확인하십시오.
화면 또는 로그에 표시된 내용을 확인하고, UI에 명확한 텍스트 알림이 있는지 검사하십시오.
대부분의 경우 오류 메시지는 자체 설명적입니다. 화면 정보나 로그에 오류 원인이 명시되어 있다면 해당 원인을 해결하십시오. 예:
cameraDevice.openWithPreferredType fail(카메라 사용 가능 여부 확인 필요)."지원되지 않음"(예: ARCore 미지원 장치 또는 기타 기능)이라는 메시지는 정상적인 제한 사항이므로 추가 조치가 필요 없습니다.
해결할 수 없음
우선 기존 정보를 바탕으로 자체 해결을 시도하십시오. 문제가 지속될 경우, EasyAR 지원팀의 신속한 문제 파악을 위해 현상(예: "검은 화면")만 기술하지 말고 아래와 같은 세부적이고 재현 가능한 기술 정보를 반드시 제공하십시오:
- 전체 로그: Unity 또는 Sense 로그
- 화면 캡처 또는 녹화: 이상 발생 시 전체 화면. 진단 정보가 표시된다면 해당 정보가 포함되도록 캡처하십시오.
- 상세 장치 정보: 기기 모델(예: iPhone 15, HUAWEi P40), OS 버전(예: iOS 17.1, Android 14), EasyAR Sense 버전, EasyAR Sense Unity Plugin 버전, Unity 버전 등.
Not found on-site, 지속적으로 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 서비스에는 콜드 스타트(cold-start) 메커니즘이 있어, 초기 로딩 시 콜드 스토리지(cold storage)에서 깨워야 합니다. 네트워크 연결을 유지한 상태로 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의 Mega Studio에서 계정에 로그인한 후 위치 추적 오류가 발생하는 포지셔닝 라이브러리를 선택하세요. 아래 이미지의 Mega 포지셔닝 서비스 내보내기 버튼을 찾습니다. 내보낸 파일 형식은 MegaStudio_ServiceInfo_username_YY-MM-DD_HH-MM-SS.json이어야 합니다. Mega 포지셔닝 서비스에는 Mega Block 및 포지셔닝 라이브러리 정보만 포함되며, 다른 민감한 정보는 포함하지 않습니다.
Eif 파일 녹화
휴대폰 테스트 시 문제가 발생하면 Toolbox로 휴대폰 Eif 파일 녹화를 사용하세요.
안경 테스트 시 문제가 발생하면 Toolbox로 안경 Eif 파일 녹화를 사용하세요.
자체 애플리케이션에서 문제가 발생한 경우 애플리케이션을 사용하여 Eif 파일 녹화가 가능합니다.
위챗 미니프로그램 사용 시 미니프로그램으로 Eif 파일 녹화를 사용할 수 있습니다.
휴대폰, 안경 등 기기를 사용하여 문제 현상 녹화하기
AR 분야에서는 문제 현상을 문자로 정확히 전달하기 어렵습니다. 각자의 이해도가 크게 다를 수 있습니다. 동시에, 런타임 화면 녹화는 매우 유용한 정보로, 귀하와 EasyAR 직원 간의 공통된 이해를 도모할 수 있습니다. 휴대폰, 안경 등 기기의 기본 기능이나 타사 소프트웨어를 활용하여 녹화할 수 있습니다. 다만, 화면 녹화 과정은 일반적으로 실행 성능에 영향을 미치며, 추적 효과와 성능이 저하될 수 있음을 유의해야 합니다.
[!참고] 화면 녹화 전, 런타임에서 해당 샘플을 참고하여 필요한 Debug 정보를 화면에 표시하는 것이 좋습니다. 녹화본을 제공할 때는 녹화 기간에 해당하는 EIF 데이터도 함께 제공해야 합니다.
Unity 개발 문제 피드백
Unity 개발 과정에서 비정상적인 문제가 발생한 경우, 아래 4가지 항목을 순차적으로 점검해 보세요.
- 최신 버전의 EasyAR Sense Unity Plugin을 시도해 보았는지 확인: 새 버전에는 일반적으로 버그 수정 및 신기능이 포함되어 있으므로, 최신 버전으로 업그레이드하여 시도해 보는 것을 권장합니다.
- EasyAR 개발 문서 및 Mega 가이드를 읽어 보았는지 확인: 문서에는 일반적으로 특정 상황에 대한 설명이 포함되어 있습니다.
- 시스템 및 Unity 로그를 확인해 보았는지 확인: 질문 시 전체 로그를 제공하는 것을 권장합니다.
- 빈 Unity 프로젝트에서 Sample을 통해 문제를 재현해 보았는지 확인
위 4가지 점검을 완료했음에도 문제가 해결되지 않는 경우, EasyAR 기술진이 분석 및 해결할 수 있도록 아래 절차에 따라 EasyAR Sense Unity Plugin에서 완전한 정보를 제공하세요.
Unity -> EasyAR -> Sense에서
질문하기선택
질문하기에서 다음 정보를 제공해야 합니다- 문제가 발생한 실행 환경 선택 (단일 환경만 선택 가능)
- 장치 정보 복사:
EasyAR Session에서DiagnosticsController.DumpSession을Log로 설정한 후, 한 프레임의 출력 결과를 복사하여 아래에 입력
- 사용한 모든 EasyAR 기능 선택 (다중 선택 가능)
- 위 4가지 점검을 완료했는지 확인: Sample에서 문제 재현 방법을 질문 시 설명하는 것을 권장
- 오른쪽 상단의 복사 기능 클릭
질문하기창을 처음 열면 하단 정보가 불완전하게 표시됩니다. 사용 환경 및 기능을 선택한 후에 전체 정보가 나타납니다.
하단의
EasyAR Q&A로 이동클릭 후 복사한 정보를 EasyAR 공식에 피드백하거나, 직접 EasyAR 담당자에게 전달
