独自のアプリで 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);
Cloud Anchor をホストする
ホスティングは ArSession_hostCloudAnchorAsync() への呼び出しから始まります。ARCore は、ビジュアル データ、デバイスのポーズ、アンカーのポーズを ARCore API にアップロードします。API はこの情報を処理して 3D 特徴マップを構築し、最終的にデバイスにアンカーの一意の Cloud Anchor ID を返します。
ARCore Cloud Anchor Management API を使用して、ホストされているアンカーの存続期間を延長することもできます。
アプリで Cloud Anchor のホスティングを完了する手順は次のとおりです。
ArSession_hostCloudAnchorAsync()を呼び出します。- コールバックを待つか、終了するまで Future の状態を継続的に確認します。
- 結果の状態を確認する オペレーションが成功したかどうかを判定したり、失敗した場合はエラーコードを解釈したりできます。
- 結果の Cloud Anchor ID を他のクライアントと共有し、それを使用して Cloud Anchor を解決します
ArSession_resolveCloudAnchorAsync()。
対象物ポイントのマッピングの品質を確認する
ArFeatureMapQuality は、特定のカメラのポーズから直近の数秒間に ARCore が認識した特徴点の品質を示します。通常、高品質の特徴を使用してホストされた Cloud Anchors はより正確に解決されます。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 Anchors の解決を順番に開始できます。一度に最大 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 プロジェクトに割り当てられたリクエストの割り当てを使い果たしました。プロジェクトの ARCore API の追加割り当ては、Google Developers Console からリクエストしてください。 |
AR_CLOUD_ANCHOR_STATE_SUCCESS |
このアンカーのホスティング タスクまたは解決タスクが正常に完了しました。 |
ホスト リクエストと解決リクエストの API 割り当て
ARCore API のリクエスト帯域幅の割り当ては、次のとおりです。
| 割り当てのタイプ | 最大 | 期間 | 適用対象 |
|---|---|---|---|
| アンカーの数 | 無制限 | なし | プロジェクト |
| アンカー host リクエスト | 30 | 分 | IP アドレスとプロジェクト |
| resolve リクエストをアンカーする | 300 | 分 | IP アドレスとプロジェクト |
優れたユーザー エクスペリエンスのためのおすすめの方法
アプリのユーザー エクスペリエンスを高めるために、ユーザーに次の手順を案内します。
- セッションの開始後数秒待ってからアンカーのホストを試みる （オブジェクトを配置するなど）。これにより、トラッキングが安定するまでしばらく時間がかかります。
- アンカーをホストする場所を選択する際は、互いに簡単に区別できる視覚的特徴のあるエリアを選ぶようにします。最良の結果を得るには、反射面や、空白の白い壁など、視覚的特徴のない表面は避けてください。
カメラを被写体の中心に向けるようにし、デバイスを動かす 対象物とほぼ同じ物理的距離を維持しながら、さまざまな角度から環境を地図に表示できます。これにより、より多くの視覚的なデータを取得して、より確実な解決を行うことができます。
Cloud Anchors をホストおよび解決する際に、実際の環境が十分に明るいことを確認します。
非推奨ポリシー
- ARCore SDK 1.12.0 以降でビルドされたアプリには、Cloud Anchor API の非推奨ポリシーが適用されます。
- ARCore SDK 1.11.0 以前でビルドされたアプリでは、サポートが終了した古い ARCore API が使用されているため、Cloud Anchors をホストまたは解決できません。
次のステップ
- アプリで ARCore を使用するその他の方法については、Android NDK リファレンス ドキュメントをご覧ください。