Table of Contents

診断と修正: アプリケーションでコンテンツが表示されない問題

「現実世界は見えるが、仮想コンテンツが表示されない。」これは AR 開発で最もよく見られる問題の 1 つです。この問題は、Mega localization 自体からレンダリングロジックまで、複数の段階に起因する可能性があります。

この記事では、この問題を体系的に調査し解決する方法を案内します。

調査フロー: 外部から内部へ

「まず外部、次に内部」の原則に従うことで、効率的に問題を特定できます。次の手順を順番に実行してください。

手順 1: 外部ツールで Mega localization 状態を検証する（コード変更不要）

アプリケーションコードに深く入る前に、まず Mega localization service 自体が正常に動作しているかを確認します。これは最も重要な手順であり、問題が Mega localization 自体にあるのか、レンダリングなどアプリケーション開発統合にあるのかを判断するのに役立ちます。

  1. Mega Toolbox を使用する（モバイル端末）

    • テスト用スマートフォンに Mega Toolbox App をインストールします（未インストールの場合）。
    • App を開き、On-site verification and diagnosis tool に入ります。
    • アカウントにログインし、アプリケーションと同じ localization library を選択します。
    • アプリケーションのテスト時にコンテンツが表示されない同じ位置にスマートフォンを持っていきます。
    • 結果を確認:
      • Toolbox の localization が成功する場合（画面状態が Found と表示）: Mega localization service は正常です。問題はアプリケーション内部、特にレンダリングとコンテンツ表示ロジックにあります。手順 2 に進んでください。
      • Toolbox の localization が失敗する場合（画面状態が NotFound またはその他）: 問題は localization service 自体にあります。次のセクションを参照して詳しく分析してください。

  2. PC 端でのシミュレーション実行を使用する（EIF を取得済みの場合）

    • このシーンの EIF data をすでに記録している場合、PC 上の Unity editor で session 検証ツールを使用してそのデータを再生できます。
    • 結果を確認:
      • 再生時に localization が成功する場合（画面状態が Found と表示）: 問題はアプリケーションコードまたはデバイス固有の環境にあります。
      • 再生時に localization が失敗する場合（画面状態が NotFound またはその他）: 問題は localization service 自体にあります。次のセクションを参照して詳しく分析してください。

手順 2: アプリケーション内部のレンダリングとコンテンツロジックを確認する

手順 1 で Mega localization service 自体が正常であることを確認できた場合、問題はアプリケーションコードにあります。次を確認してください。

  1. コンテンツが正しいノードの下に配置されているか:

    • 3D オブジェクトを、ツールが自動生成した MegaBlocks > Block_* ノードの下に正しく配置していますか。
    • コンテンツと Block ノードの階層関係を確認し、実行時に仮想コンテンツが正しい位置にレンダリングされることを確認します。

  2. MegaTracker の Block Root が正しく設定されているか:

    • AR Session を展開し、Mega Tracker の Block Root がツール生成の MegaBlocks ノードであるか確認します。

  3. MegaBlocks ノードに変更がないか:

    • Block_* ノード名を変更していないこと、また local transform プロパティ内のどの値も変更していないことを確認してください。

  4. イベントリスニングが正しいか:

    • MegaTracker の localization callback 処理ロジックを変更しましたか。
    • コードは localization success status event が発火した後にのみ、仮想コンテンツのインスタンス化または表示を実行していますか。

  5. ヘッドセットレンダリングと透明度:

    • 仮想オブジェクトが他のオブジェクトに遮られていませんか。render queue と Shader を確認してください。
    • VST (video see-through) デバイスを使用している場合、レンダリングが video stream の上に正しく重ねられているか確認してください。
    • OST (optical see-through) デバイスを使用している場合、環境光が強すぎてコンテンツが見えにくくなっていないか確認してください。

  6. コンテンツ自体の問題:

    • インスタンス化した Prefab 自体に問題はありませんか。たとえばモデルファイルの欠落、Shader エラー、scale が 0 などです。同じオブジェクトをシーンに手動配置し、正常に表示されるか確認してください。

よくある localization 失敗原因の分析と改善提案

手順 1 で Mega Toolbox でも localization できない場合は、localization 問題を慎重に確認し解決する必要があります。よくある原因と対策は次のとおりです。

  • 原因 1: マップと環境が一致しない
    現場環境が取得・マッピング時から大きく変化した、体験エリアが取得時にカバーされていなかった、またはマップ自体が間違っている。
    改善提案:

    • localization library に読み込まれているマップが、現在の物理空間とシーン上で一致していることを確認してください。
    • 環境が改装や陳列変更などで変化した場合は、再取得してマップを再生成する必要があります。
    • 取得・マッピング時に問題発生エリアがカバーされていなかった場合は、incremental update によってマップを再生成する必要があります。

  • 原因 2: 初期化環境が良くない
    単色の壁や床に向けるなど、テクスチャが少ない領域でアプリケーションを起動している。
    改善提案:

    • ユーザーにテクスチャが豊富な領域でアプリケーションを起動するよう案内し、システムが initial localization を素早く完了できるようにします。
    • アプリケーション UI に「スマートフォンを持ち上げて周囲を見回してください」など明確なヒントを表示します。

  • 原因 3: ネットワークまたはサービスの問題
    ネットワーク遅延によって localization service request が timeout した、または localization service 自体に障害がある、または同時使用上限を超えた場合などです。後者については速やかにフィードバックしてください。

  • 原因 4: アルゴリズム能力の限界に到達
    Mega localization は高度な computer vision、AI などのアルゴリズムに基づいていますが、万能ではなく一定の能力限界があります。特定のシーンや地点で localization が継続的に失敗する場合、画面録画や EIF data 記録などの方法でフィードバックいただくことで、アルゴリズムの継続的な改善と反復に役立ちます。

なお、Mega localization にはプロセスが必要で、通常 1〜2 秒程度かかります。ネットワーク混雑、高 concurrency、スマートフォン発熱による周波数低下など、現実シーンの複雑さを考慮すると、この時間はさらに長くなる場合があります。そのため、アプリケーション内に明確なロード/待機画面を設計し、「Localizing...」とユーザーに伝えることで、待機によってサービスが停止している、または localization できないと誤解されることを避けられます。

注記
  • 初回 localization は通常、後続の localization より遅くなります。初回 localization 成功後に、システムが対応するコンテンツを読み込む必要があるためです。これは正常な現象です。
  • デバイスを素早く動かすと localization が失われる可能性があります。ユーザーにデバイスを安定して動かすよう案内してください。

まとめとベストプラクティス

  • 常に外部ツールで先に検証する: 問題範囲を最速で「localization」または「rendering」に絞り込めます。
  • 合理的なユーザー期待を作る: UI ヒントにより、localization には時間がかかることをユーザーに知らせ、適切な環境へ案内します。
  • コンテンツロジックに注目する: content binding などの設定が正しいことを確認してください。
  • ログを活用する: event trigger、pose acquisition、response status などの重要ノードでログを出力すると、コードロジックの問題を素早く特定できます。

上記の体系的な調査により、「コンテンツが表示されない」問題の大多数を解決できるはずです。それでも問題が残る場合は、EIF data とログを用意し、Issue report から詳細レポートを提出してください。