Mega ローカライズ失敗トラブルシューティングガイド

Mega は先進的なビジュアルローカライズアルゴリズムに基づき、クラウド上の Mega Block 検索、視覚特徴のマッチング計算によって高精度なローカライズを実現します。そのため実際の使用中には、設定ミス、環境変化、ネットワークの揺らぎなど、さまざまな原因でローカライズに失敗する可能性があります。

このドキュメントは、ローカライズ状態をすばやく判断し、「正常な待機」と「異常なエラー」を区別し、設定、環境、サービスの 3 つの要因に基づいて迅速に診断できるようにすることを目的としています。

ローカライズフロー

対象区域内で建図データを収集し、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 でよくある状況は 2 つあります

• 接続または転送失敗
• サービスからの異常戻り値

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

よくあるエラー分類と調査

ローカライズから返される状態と現象に基づき、よくある問題は設定問題、環境要因、サービス自体の 3 種類に分類できます。

設定問題

この種の問題は通常、開発接続段階で発生し、サービスがまったく起動できない形で表れます。

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 つずつ確認してください。

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 に設定し、1 フレームの出力をコピーして結果を下部に入力します
   • 問題発生時に使用していたすべての EasyAR 機能を選択します。複数選択に対応しています
   • 上記 4 項目の確認を完了していることを確認します。質問時には Sample で問題を再現する方法を説明することを推奨します
   • 右上のコピー機能をクリックします 質問 ウィンドウを開いた直後は、下部の情報がすべて表示されません。使用する環境と機能を選択すると表示されます。

3. 下部の EasyAR 問答へ移動 をクリックし、コピーした情報を EasyAR 公式へフィードバックするか、直接 EasyAR スタッフへフィードバックします