独自のアプリで 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 には、リクエスト帯域幅に次の割り当てがあります。
| 割り当てのタイプ | 最大 | 期間 | 適用対象 |
|---|---|---|---|
| アンカーの数 | 無制限 | なし | プロジェクト |
| アンカー host リクエスト | 30 | 分 | IP アドレスとプロジェクト |
| アンカーの解決リクエスト | 300 | 分 | IP アドレスとプロジェクト |
優れたユーザー エクスペリエンスのためのおすすめの方法
アプリのユーザー エクスペリエンスを高めるために、ユーザーに次の手順を案内します。
- セッションの開始後数秒待ってからアンカーのホストを試みる （オブジェクトを配置するなど）。これにより、トラッキングが安定するまでしばらく時間がかかります。
- アンカーをホストする場所を選択する際は、互いに簡単に区別できる視覚的特徴のあるエリアを選ぶようにします。最良の結果を得るには、反射面、何もない白い壁など視覚的特徴のない表面は避けてください。
カメラを被写体の中心に向けるようにし、デバイスを動かす 対象物とほぼ同じ物理的距離を維持しながら、さまざまな角度から環境を地図に表示できます。これにより、より多くの視覚的なデータを取得して、より確実な解決を行うことができます。
Cloud Anchors をホストおよび解決する際に、実際の環境が十分に明るいことを確認します。
非推奨ポリシー
- ARCore SDK 1.12.0 以降でビルドされたアプリには、Cloud Anchor API の非推奨ポリシーが適用されます。
- ARCore SDK 1.11.0 以前でビルドされたアプリでは、サポートが終了した古い ARCore API が使用されているため、Cloud Anchors をホストまたは解決できません。
次のステップ
- ARCore Cloud Anchors と永続的な Cloud Anchors Codelab に沿って Cloud Anchors アプリを作成します。
- Cloud Anchors クイックスタートの 2 つのサンプルアプリを使用して、Cloud Anchors のホスティングと解決を学びます。
- Cloud Anchors Management API を使用して、ARCore アプリの外部で Cloud Anchors を管理します。
- アプリで ARCore を使用するその他の方法については、Android リファレンス ドキュメントをご覧ください。