独自のアプリで Cloud Anchors を使用する方法を学びます。
前提条件
続行する前に、AR の基本コンセプトと ARCore セッションを構成する方法を理解してください。
Cloud Anchors を初めて使用する場合:
- アンカーと Cloud Anchor の仕組みを理解しておいてください。
- システム要件、設定、インストール手順については、Cloud Anchors のクイックスタートをご覧ください。
ARCore API を有効にする
アプリで Cloud Anchors を使用する前に、まずアプリで ARCore API を有効にする必要があります。
セッション構成で Cloud Anchor 機能を有効にする
アプリで Cloud Anchors 機能を有効にしたら、アプリの AR セッション構成で Cloud Anchors 機能を有効にして、ARCore API と通信できるようにします。
Java
Config config = new Config(session); config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED); session.configure(config);
Kotlin
val config = Config(session) config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED session.configure(config)
Cloud Anchor をホストする
ホスティングは hostCloudAnchorAsync() の呼び出しで開始されます。ARCore は、ビジュアル データ、デバイスのポーズ、アンカーのポーズを ARCore API にアップロードします。API は、この情報を処理して 3D 特徴マップを作成し、最終的にデバイスにアンカルの一意の Cloud Anchor ID を返します。
ARCore Cloud Anchor Management API を使用して、ホスト型アンカーの存続期間を延長することもできます。
アプリで Cloud Anchor のホスティングを完了する手順は次のとおりです。
hostCloudAnchorAsync()を呼び出します。- コールバックを待つか、完了するまで Future の状態を継続的に確認します。
- 結果の状態を確認して、オペレーションが成功したかどうかを判断します。失敗した場合は、エラーコードを解釈します。
- 結果の Cloud Anchor ID を他のクライアントと共有し、その ID を使用して
resolveCloudAnchorAsync()で Cloud Anchor を解決します。
特徴点のマッピング品質を確認する
Session.FeatureMapQuality は、特定のカメラ ポーズから前の数秒間に ARCore が検出した特徴点の品質を示します。質の高い特徴を使用してホストされた Cloud Anchor は、一般的に、より正確に解決されます。Session.estimateFeatureMapQualityForHosting() を使用して、特定のカメラのポーズから対象物地図の品質を推定します。
| 値 | 説明 |
|---|---|
INSUFFICIENT |
前の数秒間のポーズから特定された特徴点の品質が低い。この状態は、ARCore が Cloud Anchor の解決が難しくなる可能性が高いことを示しています。ホストする Cloud Anchor の希望する位置をさまざまな角度から確認できるように、デバイスを動かすようユーザーに伝えます。 |
SUFFICIENT |
前数秒間のポーズから検出された特徴点の品質は、ARCore が Cloud Anchor を正常に解決するのに十分である可能性が高いですが、解決されたポーズの精度は低下する可能性があります。デバイスを移動して、ホストする Cloud Anchor の希望する位置をさまざまな角度から確認できるようにするようお客様に伝えます。 |
GOOD |
前の数秒間のポーズから検出された特徴点の品質は、ARCore が Cloud Anchor を高い精度で解決するのに十分な可能性があります。 |
以前にホストされたアンカーを解決する
resolveCloudAnchorAsync() を呼び出して、ホスト型 Cloud Anchor を解決します。ARCore API は、シーンの視覚的な特徴をアンカーの 3D 特徴マップと定期的に比較して、アンカーを基準としたユーザーの位置と向きを特定します。一致が見つかった場合、API はホストされている Cloud Anchor のポーズを返します。
複数の Cloud Anchor の解決を順番に開始できます。一度に存在できる Cloud Anchor オペレーションは最大 40 個です。
オペレーションをキャンセルする、または Cloud Anchor を削除する
cancel() を呼び出して、保留中の Cloud Anchor オペレーションをキャンセルします。detach() を呼び出して、すでに解決済みの Cloud Anchor をアプリから削除します。
Cloud Anchor オペレーションの結果状態を確認する
Anchor.CloudAnchorState を使用して、ホスティング オペレーションまたは解決オペレーションの結果ステータス（エラーを含む）を確認します。
| 値 | 説明 |
|---|---|
ERROR_CLOUD_ID_NOT_FOUND |
ARCore API が指定された Cloud Anchor ID を見つけられなかったため、解決できませんでした。 |
ERROR_HOSTING_DATASET_PROCESSING_FAILED |
サーバーが指定されたアンカーのデータセットを正常に処理できなかったため、ホスティングに失敗しました。デバイスが環境からより多くのデータを収集した後で、もう一度お試しください。 |
ERROR_HOSTING_SERVICE_UNAVAILABLE |
ARCore API に到達できませんでした。この原因としては、デバイスが機内モードになっているか、インターネットに接続されていない可能性があります。サーバーに送信されたリクエストがタイムアウトし、応答が返されなかった可能性があります。ネットワーク接続の不良、DNS が利用できない、ファイアウォールの問題など、デバイスの ARCore API への接続機能に影響している可能性のある問題がある可能性があります。 |
ERROR_INTERNAL |
このアンカーのホスティング タスクまたは解決タスクが内部エラーで終了しました。アプリはこのエラーから復旧しようとしないでください。 |
ERROR_NOT_AUTHORIZED |
アプリが提供する認証が無効です。ARCore API の認可に関する問題のトラブルシューティングをご覧ください。 |
ERROR_RESOLVING_SDK_VERSION_TOO_NEW |
アンカーの解決に使用された SDK バージョンが、アンカーをホストするバージョンよりも新しく、互換性がないため、Cloud Anchor を解決できませんでした。 |
ERROR_RESOLVING_SDK_VERSION_TOO_OLD |
アンカーの解決に使用された SDK バージョンが、アンカーのホストに使用されたバージョンよりも古く、互換性がないため、Cloud Anchor を解決できませんでした。 |
ERROR_RESOURCE_EXHAUSTED |
アプリケーションが、特定の Google Cloud プロジェクトに割り当てられたリクエスト割り当てを使い果たしました。プロジェクトの ARCore API の追加の割り当ては、Google Developers Console からリクエストする必要があります。 |
SUCCESS |
このアンカーのホストまたは解決タスクが正常に完了しました。 |
ホスト リクエストと解決リクエストの API 割り当て
ARCore API には、リクエスト帯域幅に次の割り当てがあります。
| 割り当てのタイプ | 最大 | 期間 | 適用対象 |
|---|---|---|---|
| アンカーの数 | 無制限 | なし | プロジェクト |
| アンカーのホスト リクエスト | 30 | 分 | IP アドレスとプロジェクト |
| アンカーの解決リクエスト | 300 | 分 | IP アドレスとプロジェクト |
優れたユーザー エクスペリエンスを実現するためのベスト プラクティス
アプリで優れたユーザー エクスペリエンスを実現するために、ユーザーに次の手順を案内します。
- セッションの開始後、数秒待ってからアンカーをホストします（オブジェクトを配置するなど）。これにより、トラッキングが安定するまでしばらく時間がかかります。
- アンカーをホストする場所を選択する際は、視覚的な特徴が互いに区別しやすい場所を見つけてください。最良の結果を得るには、反射する表面や、視覚的な特徴のない表面（空白の白い壁など）は避けてください。
カメラを被写体の中心に合わせたまま、被写体の周囲を移動して、さまざまな角度から環境をマッピングします。移動する際は、物理的な距離をほぼ同じに保ってください。これにより、より多くの画像データをキャプチャし、解像度を高めることができます。
Cloud Anchor をホストして解決する際に、現実の環境で十分な照明があることを確認してください。
非推奨ポリシー
- ARCore SDK 1.12.0 以降でビルドされたアプリは、Cloud Anchor API の非推奨に関するポリシーの対象となります。
- ARCore SDK 1.11.0 以前でビルドされたアプリは、SDK で古い非推奨の ARCore API が使用されているため、Cloud Anchor をホストまたは解決できません。
次のステップ
- ARCore の Cloud Anchors と永続的な Cloud Anchors の Codelab を使用して、Cloud Anchors アプリを作成します。
- Cloud Anchors のクイックスタートで、2 つのサンプルアプリを使用して Cloud Anchors のホストと解決について説明します。
- Cloud Anchors Management API を使用して、ARCore アプリの外部で Cloud Anchors を管理します。
- アプリで ARCore を使用するその他の方法については、Android リファレンス ドキュメントをご覧ください。