独自のアプリで Cloud Anchors を使用する方法を学習する。
前提条件
続行する前に、AR の基本的なコンセプトと ARCore セッションを構成する方法を理解しておいてください。
Cloud Anchors を初めて使用する場合は、アンカーと Cloud Anchors の仕組みを理解しておく必要があります。
ARCore API を有効にする
アプリで Cloud Anchors を使用する前に、まずアプリケーションで ARCore API を有効にする必要があります。
セッション構成で Cloud Anchor 機能を有効にする
アプリで Cloud Anchors 機能が有効になったら、アプリの AR セッション構成で Cloud Anchors 機能を有効にして、ARCore API と通信できるようにします。
// Create a new ARCore session.
ArSession* session = NULL;
CHECK(ArSession_create(env, context, &session) == AR_SUCCESS);
// Create a session config.
ArConfig* config = NULL;
ArConfig_create(session, &config);
ArSession_getConfig(session, config);
// Enable Cloud Anchor mode.
ArConfig_setCloudAnchorMode(session, config,
AR_CLOUD_ANCHOR_MODE_ENABLED);
// Configure the session.
ArSession_configure(session, config);
ArConfig_destroy(config);
クラウド アンカーをホストする
ホスティングは ArSession_hostCloudAnchorAsync() を呼び出すことから始まります。ARCore は、ビジュアル データ、デバイスのポーズ、アンカーのポーズを ARCore API にアップロードします。API はこの情報を処理して 3D 対象物マップを作成し、最終的にアンカーの一意の Cloud Anchor ID をデバイスに返します。
ARCore Cloud Anchor Management API を使用して、ホストされたアンカーの有効期間を延長することもできます。
アプリで Cloud Anchor のホスティングを完了する手順は次のとおりです。
ArSession_hostCloudAnchorAsync()を呼び出します。- コールバックを待つか、完了するまで Future の状態を継続的に確認します。
- 結果の状態を確認して、オペレーションが成功したかどうかを判断し、失敗した場合はエラーコードを解釈します。
- 結果の Cloud Anchor ID を他のクライアントと共有し、それを使用して
ArSession_resolveCloudAnchorAsync()で Cloud Anchor を解決します。
対象物のマッピングの質を確認する
ArFeatureMapQuality は、特定のカメラのポーズから直近の数秒間に ARCore が確認した特徴点の品質を示します。一般的に、高品質の機能を使用してホストされた Cloud Anchor はより正確に解決されます。ArSession_estimateFeatureMapQualityForHosting() を使用して、特定のカメラのポーズに対する特徴マップの品質の推定を取得します。
| 値 | 説明 |
|---|---|
INSUFFICIENT |
前の数秒のポーズから特定された特徴点の品質が低い。この状態は、ARCore による Cloud Anchor の解決がより困難であることを示します。ホストする Cloud Anchor をさまざまな角度から確認できるようにデバイスを移動するよう、お客様におすすめします。 |
SUFFICIENT |
前の数秒のポーズから特定された特徴ポイントの品質は、ARCore が Cloud Anchor を正常に解決するのに十分であると考えられますが、解決されるポーズの精度は低下する可能性があります。ホストする Cloud Anchor をさまざまな角度から確認できるようにデバイスを移動するよう、お客様におすすめします。 |
GOOD |
前の数秒のポーズから特定された特徴点の品質は、ARCore が Cloud Anchor を高い精度で正常に解決するうえで十分であると考えられます。 |
以前にホストしたアンカーを解決する
ArSession_resolveCloudAnchorAsync() を呼び出して、ホストされている Cloud Anchor を解決します。ARCore API は、シーンの視覚的特徴を定期的にアンカーの 3D 特徴マップと比較し、アンカーを基準としたユーザーの位置と向きを特定します。一致を見つけると、API はホストされている Cloud Anchor のポーズを返します。
複数の Cloud Anchor の解決を順番に開始できます。同時に最大 40 個の Cloud Anchor オペレーションを同時に存在できます。
オペレーションのキャンセルまたは Cloud Anchor の削除
ArFuture_cancel() を呼び出して、保留中の Cloud Anchor オペレーションをキャンセルします。ArAnchor_detach() を呼び出してトラッキングを停止し、解決済みの Cloud Anchor を削除します。アンカーへの参照は、ArAnchor_release() を呼び出して個別に解放する必要があります。
Cloud Anchor オペレーションの結果状態を確認する
ArCloudAnchorState を使用して、ホスティングまたは解決オペレーションの結果ステータス（エラーを含む）を確認します。
| 値 | 説明 |
|---|---|
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND |
ARCore API が指定された Cloud Anchor ID を見つけられなかったため、解決できませんでした。 |
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED |
サーバーが指定されたアンカーのデータセットを正常に処理できなかったため、ホスティングに失敗しました。デバイスが環境からより多くのデータを収集してから、もう一度お試しください。 |
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE |
ARCore API にアクセスできませんでした。これにはいくつかの原因が考えられます。デバイスが機内モードになっているか、インターネットに接続されていない可能性があります。サーバーに送信されたリクエストがタイムアウトし、応答がない。ネットワーク接続に問題がある、DNS を利用できない、ファイアウォールに問題があるなど、デバイスの ARCore API への接続に影響する可能性があります。 |
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL |
このアンカーのホスティング タスクまたは解決タスクが内部エラーが発生しました。アプリはこのエラーからの復元を試行してはなりません。 |
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED |
ARCore API の承認に関する問題のトラブルシューティングをご覧ください。 |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW |
アンカーの解決に使用された SDK バージョンが、アンカーをホストするために使用されるバージョンより新しく、互換性がないため、Cloud Anchor を解決できませんでした。 |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD |
アンカーの解決に使用された SDK バージョンが、アンカーをホストするために使用されるバージョンより古く、互換性がないため、Cloud Anchor を解決できませんでした。 |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED |
アプリケーションが、指定された Google Cloud プロジェクトに割り当てられたリクエストの割り当てを使い果たした。Google Developers Console から、プロジェクトの ARCore API の追加割り当てをリクエストする必要があります。 |
AR_CLOUD_ANCHOR_STATE_SUCCESS |
このアンカーのホスティング タスクまたは解決タスクが正常に完了しました。 |
ホストの API 割り当てとリクエストの解決
ARCore API には、リクエスト帯域幅に次の割り当てがあります。
| 割り当てのタイプ | 最大 | Duration | 適用先 |
|---|---|---|---|
| アンカーの数 | unlimited | なし | プロジェクト |
| ホスト リクエストのアンカー | 30 | 分 | IP アドレスとプロジェクト |
| アンカーでリクエストをresolve | 300 | 分 | IP アドレスとプロジェクト |
優れたユーザー エクスペリエンスを実現するためのベスト プラクティス
アプリのユーザー エクスペリエンスを向上させるために、以下の手順を行うようユーザーに指示する。
- セッションが開始してから数秒待ってから、（オブジェクトを配置するなどして）アンカーをホストします。これにより、トラッキングが安定する時間が得られます。
- アンカーをホストする場所を選択する際は、互いに簡単に区別できる視覚的特徴を持つエリアを見つけるようにしてください。最良の結果を得るには、反射する面や、空白の白い壁など、視覚的特徴のない面は避けてください。
対象の中心でカメラをトレーニングし、対象の中心の周りでデバイスを動かして、さまざまな角度から環境をマッピングします。その際、物理的距離とほぼ同じ距離を維持します。これにより、より多くの視覚的データをキャプチャでき、より確実な解決が可能になります。
Cloud Anchor をホストして解決する際は、実際の環境に十分な照明があることを確認します。
非推奨ポリシー
- ARCore SDK 1.12.0 以降で作成されたアプリには、Cloud Anchor API のサポート終了ポリシーが適用されます。
- ARCore SDK 1.11.0 以前でビルドされたアプリでは、非推奨になった古い ARCore API が SDK で使用されているため、Cloud Anchors をホストまたは解決できません。
次のステップ
- アプリで ARCore を使用するその他の方法については、Android NDK リファレンス ドキュメントをご覧ください。