Table of Contents

진단 및 수정: application에서 content가 표시되지 않는 문제

"현실 세계는 보이지만 virtual content가 나타나지 않습니다." 이는 AR development에서 가장 흔한 문제 중 하나입니다. 이 문제는 Mega localization 자체부터 rendering logic까지 여러 단계에서 발생할 수 있습니다.

이 문서는 이 문제를 체계적으로 troubleshooting하고 해결하도록 안내합니다.

Troubleshooting flow: 외부에서 내부로

"먼저 외부, 그 다음 내부" 원칙을 따르면 문제를 효율적으로 찾을 수 있습니다. 다음 단계를 순서대로 수행하십시오.

1단계: 외부 tool로 Mega localization status 검증(코드 수정 불필요)

Application code를 깊이 살펴보기 전에 먼저 Mega localization service 자체가 정상적으로 작동하는지 확인합니다. 이는 가장 중요한 단계이며, 문제가 Mega localization 자체인지 rendering 등 application development integration 문제인지 판단하는 데 도움이 됩니다.

  1. Mega Toolbox 사용(mobile)

    • Test phone에 Mega Toolbox App을 설치합니다(아직 설치하지 않은 경우).
    • App을 열고 On-site verification and diagnosis tool로 들어갑니다.
    • 계정에 login하고 application과 동일한 localization library를 선택합니다.
    • Application test 시 content가 표시되지 않는 같은 위치로 휴대폰을 가져갑니다.
    • 결과 확인:
      • Toolbox localization 성공(interface status가 Found 표시): Mega localization service는 정상입니다. 문제는 application 내부, 특히 rendering 및 content display logic에 있습니다. 2단계로 이동하십시오.
      • Toolbox localization 실패(interface status가 NotFound 또는 기타 표시): 문제는 localization service 자체에 있습니다. 더 자세한 분석은 다음 섹션을 참조하십시오.

  2. PC 측 simulation run 사용(EIF를 이미 수집한 경우)

    • 해당 scene에 대해 EIF data를 이미 recording했다면, PC의 Unity editor에서 session verification tool을 사용해 이 data를 replay할 수 있습니다.
    • 결과 확인:
      • Replay 시 localization 성공(interface status가 Found 표시): 문제는 application code 또는 device-specific environment에 있습니다.
      • Replay 시 localization 실패(interface status가 NotFound 또는 기타 표시): 문제는 localization service 자체에 있습니다. 더 자세한 분석은 다음 섹션을 참조하십시오.

2단계: application 내부 rendering 및 content logic 확인

1단계에서 Mega localization service 자체가 정상임을 확인했다면 문제는 application code에 있습니다. 다음 항목을 확인하십시오.

  1. Content가 올바른 node 아래에 있는지:

    • 3D object를 tool이 자동 생성한 MegaBlocks > Block_* node 아래에 올바르게 배치했습니까?
    • Content와 Block node의 hierarchy relation을 확인하여 runtime에 virtual content가 올바른 위치에 render되는지 확인합니다.

  2. MegaTracker의 Block Root가 올바르게 설정되었는지:

    • AR Session을 펼치고 Mega Tracker의 Block Root가 tool이 생성한 MegaBlocks node인지 확인합니다.

  3. MegaBlocks node가 변경되었는지:

    • Block_* node 이름을 수정하지 않았고, local transform property의 어떤 값도 수정하지 않았는지 확인합니다.

  4. Event listening이 올바른지:

    • MegaTracker의 localization callback handling logic을 수정한 적이 있습니까?
    • 코드가 localization status success event가 trigger된 후에야 virtual content를 instantiate하거나 표시합니까?

  5. Headset rendering 및 transparency:

    • Virtual object가 다른 object에 가려져 있습니까? render queue와 Shader를 확인합니다.
    • VST(video see-through) device를 사용하는 경우 rendering이 video stream 위에 올바르게 overlay되는지 확인합니다.
    • OST(optical see-through) device를 사용하는 경우 ambient light가 너무 강해서 content가 잘 보이지 않는지 확인합니다.

  6. Content 자체의 문제:

    • Instantiate한 Prefab 자체에 문제가 있습니까? 예를 들어 model file 누락, Shader error, scale 0 등입니다. 같은 object를 scene에 수동으로 배치해 정상적으로 표시되는지 확인해 보십시오.

일반적인 localization failure 원인 분석 및 개선 제안

1단계에서 Mega Toolbox도 localization할 수 없다면 localization 문제를 자세히 확인하고 해결해야 합니다. 일반적인 원인과 대응은 다음과 같습니다.

  • 원인 1: map과 environment가 일치하지 않음
    현장 environment가 acquisition 및 mapping 당시와 비교해 크게 변했거나, experience area가 acquisition 시 cover되지 않았거나, map 자체가 잘못되었습니다.
    개선 제안:

    • Localization library에 load된 map이 현재 physical space와 scene상 일치하는지 확인합니다.
    • Environment가 remodeling된 경우(예: renovation, display replacement) 다시 acquisition하고 map을 regenerate해야 합니다.
    • Acquisition 및 mapping 시 문제 발생 area가 cover되지 않았다면 incremental update 방식으로 map을 regenerate해야 합니다.

  • 원인 2: initialization environment가 좋지 않음
    Texture가 적은 area(예: solid-color wall, floor를 향함)에서 application을 시작합니다.
    개선 제안:

    • User가 texture가 풍부한 area에서 application을 시작하도록 안내하여 system이 initial localization을 빠르게 완료하도록 돕습니다.
    • Application UI에 "휴대폰을 들어 좌우를 둘러보세요"와 같은 명확한 prompt를 제공합니다.

  • 원인 3: network 또는 service 문제
    Network latency로 localization service request가 timeout되거나, localization service 자체에 fault가 발생했거나, concurrent usage limit를 초과한 경우입니다. 후자의 경우 즉시 feedback을 보내주십시오.

  • 원인 4: algorithm capability boundary에 도달
    Mega localization은 advanced computer vision, AI 등의 algorithm을 기반으로 하지만 만능은 아니며 일정한 algorithm capability boundary가 있습니다. 특정 scene 또는 point에서 localization이 계속 실패하는 경우 screen recording, EIF data recording 등의 방식으로 feedback을 제공하면 algorithm을 지속적으로 개선하고 iterate하는 데 도움이 됩니다.

또한 Mega localization은 과정이 필요하며 보통 약 1-2초가 걸립니다. Network congestion, high concurrency, phone heating frequency reduction 등 real scene의 복잡성을 고려하면 이 시간이 더 길어질 수 있습니다. 따라서 application에 명확한 loading/waiting 화면을 설계하여 user에게 "Localizing..."을 알려주면, 기다림 때문에 service down 또는 localization 실패로 오해하는 것을 피할 수 있습니다.

참고
  • 첫 localization은 보통 이후 localization보다 느립니다. 첫 localization 성공 후 system이 해당 content를 load해야 하기 때문입니다. 이는 정상입니다.
  • Device를 빠르게 움직이면 localization이 loss될 수 있습니다. User가 device를 안정적으로 움직이도록 안내하십시오.

Summary 및 best practices

  • 항상 외부 tool로 먼저 검증: 문제 범위를 "localization" 또는 "rendering"으로 가장 빠르게 좁힐 수 있습니다.
  • 합리적인 user expectation 설정: UI prompt를 통해 localization에 시간이 필요함을 알리고 적절한 environment로 안내합니다.
  • Content logic에 집중: content binding 등 설정이 올바른지 확인합니다.
  • Log 활용: event trigger, pose acquisition, response status 등 key point에서 log를 출력하면 code logic 문제를 빠르게 찾을 수 있습니다.

위의 체계적인 troubleshooting을 통해 대부분의 "content가 표시되지 않음" 문제를 해결할 수 있습니다. 문제가 계속되면 EIF data와 log를 준비하고 Issue report 를 통해 상세 report를 제출해 주십시오.