Android NDK アプリで Geospatial API を有効にする（C）

アプリの設定を構成して、Geospatial API を使用できるようにします。

前提条件

続行する前に、AR の基本的なコンセプトと ARCore セッションを構成する方法を理解しておいてください。

ここで説明する機能のデモを行うサンプルアプリを実行するには、Java 用の Android 用の ARCore Geospatial クイックスタートをご覧ください。クイックスタートのサンプルアプリは Java で記述されています。このドキュメントのコードサンプルは、C で記述された同じ機能のものです。

Geospatial API の詳細については、Geospatial API の概要をご覧ください。

ARCore を使った開発を初めて行う場合は、スタートガイドで、ソフトウェアとハードウェアの要件、前提条件、その他使用しているプラットフォームに固有の情報をご確認ください。

Java のクイックスタートで説明されているように、開発環境が ARCore SDK の要件を満たしていることを確認します。

ARCore API を有効にする

アプリで Visual Positioning System（VPS）を使用する前に、新規または既存の Google Cloud プロジェクトで ARCore API を有効にする必要があります。このサービスは、地理空間アンカーのホスティング、保存、解決を行います。

キーなしの承認が推奨されますが、API キー認証もサポートされています。

必要なライブラリをアプリに追加する

ARCore API の呼び出しをアプリに許可したら、アプリで地理空間機能を有効にするためのライブラリを追加する必要があります。

アプリの build.gradle ファイルで、Google Play 開発者サービスをセットアップして、Play 開発者サービスの位置情報ライブラリを含めます。

dependencies {
  // Apps must declare play-services-location version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-location:16 (or later)'
}

セッション構成で地理空間機能を有効にする

セッションを作成する前に、セッション構成の GeospatialMode を ENABLED に変更します。

// Create a session config.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);

// Enable the Geospatial API.
ArConfig_setGeospatialMode(ar_session, ar_config, AR_GEOSPATIAL_MODE_ENABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);

// Release config resources.
ArConfig_destroy(ar_config);

地理空間モードが ENABLED に設定されている場合、アプリは Visual Positioning System（VPS）から地理情報を取得できます。

デバイスデータの使用を許可するようユーザーに求める

ARCore Geospatial API を使用するアプリは、デバイスからのデータの使用を確認して許可するためのプロンプトをユーザーに表示する必要があります。詳しくは、ユーザーのプライバシー要件をご覧ください。

デバイスの互換性を確認する

Java のquickstartで説明されているように、ARCore をサポートするすべてのデバイスが Geospatial API もサポートしているわけではありません。

ユーザーのデバイスの互換性を確認するには、ArSession_isGeospatialModeSupported() を呼び出します。false が返された場合は、セッションの構成を試行しないでください（下記参照）。設定すると、ArStatus が AR_ERROR_UNSUPPORTED_CONFIGURATION を報告します。

実行時に位置情報の利用許可をユーザーに求める

アプリは実行時に位置情報の利用許可をリクエストする必要があります。

ARCore Geospatial API を使用するには、アプリで次の追加権限を登録する必要があります。

  • ACCESS_FINE_LOCATION: ユーザーの現在地を正確に判断します。

  • ACCESS_COARSE_LOCATION: ユーザーの現在地を不正確に判断し、ユーザーのプライバシー要件を遵守する場合。ただし、おおまかな位置情報で動作するように Geospatial API を構成することはできず、ユーザーがこの権限を設定すると API リクエストは失敗します。詳しくは以下をご確認ください。

  • ACCESS_INTERNET: ARCore Geospatial API サービスに連絡します。

<manifest ... >
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.INTERNET" />
</manifest>

Android バージョン 12 以上を搭載したデバイスでは、アプリがおおよその位置情報のみにアクセスすることをユーザーはリクエストできます。このリクエストに対応するには、上記のように、ACCESS_FINE_LOCATION とともに ACCESS_COARSE_LOCATION 権限を構成する必要があります。両方の位置情報の利用許可を構成する必要があります。

ただし、ユーザーがおおまかな位置情報を指定すると、Geospatial API は必要な正確な位置情報を取得できなくなります。アプリがおおよその位置情報しか提供しない場合、地理空間サービス自体は構成できません。お客様のアプリは、おおよその位置情報では Geospatial API を使用できません。

デバイスの現在地で利用可能な地理空間を確認する

Geospatial API は、VPS と GPS を組み合わせて地理空間ポーズを決定するため、デバイスが自身の位置を特定できる限り、この API を使用できます。屋内空間や密集した都市環境など、GPS 精度が低いエリアでは、API は VPS の受信可能範囲を利用して、高精度のポーズを生成します。一般的な条件下では、VPS の位置精度は約 5 メートル、回転精度は 5 度であると期待できます。ArSession_checkVpsAvailabilityAsync() を使用して、指定された場所が VPS に対応しているかどうかを確認します。

Geospatial API は、VPS がカバーされていない地域でも使用可能です。頭上の障害物がほとんどないか、まったくない屋外環境では、GPS で十分な精度のポーズを生成できます。

次のステップ