Table of Contents

Mega ポジショニング失敗 トラブルシューティングガイド

Mega は、先進的なビジュアル ポジショニングアルゴリズムを基盤としており、クラウド上の Mega Block 検索とビジュアル特徴マッチングによる位置解算により、高精度な位置推定を実現します。したがって、実際の運用中には、設定ミス、環境変化、ネットワークの不安定など様々な要因により、ポジショニングが失敗する可能性があります。

本文書は、ポジショニングの状態を迅速に判断し、「通常の待機状態」と「異常なエラー」を区別し、設定、環境、サービスの3つの主要なカテゴリに基づいて迅速な診断を行うための支援を目的としています。

Positioning process

対象エリア内でマッピングデータを収集し、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 Token 期限切れ

上記エラーが発生した場合の解決方法:

  • リクエストタイムアウト: ネットワーク状況を確認・修正し、必要に応じてリクエストタイムアウト時間 MegaRequestTimeParameters.Timeout を引き上げます。ただし、ネットワーク状況が悪いとトラッキング効果に影響するため、可能な限りネットワーク問題を解決してください。
  • リクエスト間隔が短すぎる: リクエスト間隔を長くします。
  • 接続または転送失敗: ネットワーク状況を確認・修正します。
  • QPS 制限超過: EasyAR のビジネス担当に連絡し、QPS の拡張を行ってください。
  • サービス起動中: システムが起動中です。しばらく待ってから再試行してください。
  • SpotVersionId が不足: SpotVersionId を設定してください。
  • API Token 期限切れ: EasyAR 管理画面で新しい API Token を再生成してください。

UnknownError には主に 2 つの状況があります

  • 接続または転送失敗
  • サービスからの返答異常

UnknownError については、MegaLocalizationResponse.ErrorMessage から詳細情報を取得できます。

Common error classification troubleshooting

位置情報に基づいて返されるステータスや現象から、一般的な問題は以下の3つに分類できます：設定問題、環境要因、サービス自体の問題。

Configuration issues

この種の問題は通常、開発導入フェーズで発生し、サービスが全く起動しないという形で現れます。

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を使用、またはその逆のケースです
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 アプリケーションの開発またはテスト中に、画面が真っ暗になる、アプリがクラッシュする、カメラ画面が表示されないなどの異常な問題が発生した場合、以下の手順に従って体系的に問題を調査し、情報を収集してください。

  1. 自分で解決を試みる

  • もし Unity を使用して開発テストを行っている場合は、AR Session (EasyAR) -> Inspector で Diagnostics Controller (Script) をチェックして診断情報を有効にしていることを確認してください。

    診断情報

  • 画面やログに表示される内容を確認し、UI に明確なテキストメッセージがあるかどうかをチェックしてください。

  • ほとんどの場合、エラーメッセージは自己説明的です。画面情報やログにエラーの原因が記載されている場合は、具体的な原因に基づいて解決できます。例： cameraDevice.openWithPreferredType fail（カメラが使用可能かどうかを確認する必要があります）。

  • 「サポートされていません」（デバイスが ARCore やその他の機能をサポートしていない場合など）と表示された場合は、正常な制限であり、それ以上の調査は必要ありません。

  1. 自分で解決できない場合

    まず、既存の情報に基づいて自分で解決を試みてください。自分で解決できない場合は、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 を返します。

原因：視覚的位置推定 (VPS) はテクスチャ特徴に依存しています。弱いテクスチャ領域では特徴点を抽出できません。

解決方法：これは正常な現象です。起動するには、カメラをテクスチャが豊富な領域に向けて移動させる必要があります。

現場にいてテクスチャが豊富だが、持続的に not found

ユーザーが現場にいて、テクスチャが豊富なエリアを向いているにもかかわらず、長時間にわたって正常な位置特定が成功しない。

考えられる原因：

  • シーン変化：現場の環境（例：内装工事、ポスターの張り替え、激しい照明変化）が、マッピング時のシーンと大きく異なっている。
  • 収集範囲外：ユーザーが立っている位置が、当初のマッピング収集範囲を超えている。

解決方法：

  • 当初収集したルートエリアに移動して試す。
  • シーンが恒久的に大きく変化している場合は、再収集を行い block を更新する必要がある。

サービス自体に起因する

ブロックの追加直後、WakingUp 継続中

位置情報ライブラリの設定直後、または位置情報ライブラリの起動直後は、サービスステータスが WakingUp または長時間 NotFound と表示されることがあります。これは、Mega サービスがコールドスタートメカニズムを備えているためで、初回の読み込みにはコールドストレージからの復帰が必要です。ネットワーク接続を維持し、10～30 秒待ってから再試行してください。

サービスが例外を返しました

HTTPSステータス ステータスコード 原因
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およびローカリゼーションライブラリ情報のみが含まれ、その他の機密情報は含まれません。

Mega 定位サービス情報のエクスポート

Eifファイルの記録

携帯電話でのテスト中に問題が発生した場合、Toolboxを使用して携帯電話のEifファイルを記録する

ヘッドセットでのテスト中に問題が発生した場合、Toolboxを使用してヘッドセットのEifファイルを記録する

ご自身のアプリケーションで問題が発生した場合、アプリケーションを使用してEifファイルを記録する

WeChatミニプログラムを使用する場合、ミニプログラムでEifファイルを記録することが可能です

スマートフォン、メガネなどのデバイスを使用した問題現象の録画

AR分野では、テキストによる説明だけでは正確な情報を伝えることが難しく、人によって解釈が大きく異なる可能性があります。一方、実行時の画面録画は有用な情報であり、EasyARスタッフとの共通理解を構築するのに役立ちます。スマートフォンやメガネなどのデバイスに搭載されている機能、またはサードパーティ製ソフトウェアを利用して録画できます。ただし、録画プロセス中は通常、実行パフォーマンスに影響を与え、トラッキング精度やパフォーマンスが低下する可能性がある点に注意が必要です。

注記

録画を開始する前に、実行時にサンプルを参照し、必要なデバッグ情報を画面に表示することを推奨します。録画を提供する際は、録画期間に対応するEIFデータも併せて提供してください。

Unity development problem feedback

Unity開発中に異常な問題が発生した場合、以下の4つのチェック項目をすべて完了しているか確認してください。

  1. 最新バージョンのEasyAR Sense Unity Pluginを試していること。新バージョンには通常バグ修正や新機能が含まれるため、まず最新版にアップグレードして試すことを推奨します
  2. EasyAR開発ドキュメントおよびMegaガイドを読んでいること。ドキュメントには状況説明が記載されている場合があります
  3. システムおよびUnityログを確認していること。質問時に完全なログを提供することを推奨します
  4. 空のUnityプロジェクトで、サンプル内で問題を再現しようと試みていること

上記4つのチェックを完了しても問題が解決しない場合、EasyAR Sense Unity Pluginで以下の手順に従い完全な情報を提供してください。EasyAR技術スタッフが分析し問題解決を支援します。

  1. Unity -> EasyAR -> Senseで質問を選択
    質問

  2. 質問では以下の情報を提供する必要があります

    • 問題が発生した実行環境を選択（単一環境のみ選択可）
    • デバイス情報をコピー：EasyAR SessionでDiagnosticsController.DumpSessionをLogに設定し、1フレームの出力をコピーして下欄に記入
      dump session
    • 問題発生時に使用した全てのEasyAR機能を選択（複数選択可）
    • 上記4つのチェックを完了済みであることを確認。サンプルで問題を再現する方法を質問時に記載することを推奨
    • 右上のコピー機能をクリック
      Unity開発情報のエクスポート
      質問ウィンドウを開いたばかりの時、下の情報が完全に表示されない場合があります。使用環境と機能を選択後に表示されます。
      環境と機能の選択

  3. 下記のEasyAR Q&Aへ移動をクリックし、コピーした情報をEasyAR公式にフィードバックするか、直接EasyARスタッフに連絡
    問題フィードバック