Android をターゲットとする Unity(AR Foundation)の地理空間デベロッパー ガイド

ご自身のアプリで Geospatial API を使用する方法をご確認ください。

Prerequisites

先に進む前に、基本的な AR のコンセプトARCore セッションの設定方法をご確認ください。

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

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

ARCore 地理空間 API を使用するには、プロジェクトが AR FoundationAR Foundation の ARCore 拡張をサポートしている必要があります。

Google Cloud プロジェクトを設定する

ビジュアル ポジショニング システム(VPS)を使用するには、ARCore API が有効になっている Google Cloud プロジェクトにアプリを関連付ける必要があります。

Google Cloud プロジェクトで ARCore API を有効にする必要があります。プロジェクトを作成する必要がある場合は、次の手順を行います。

  1. Google Cloud Platform でプロジェクトを作成するをご覧ください。

  2. [Project name] に適切な名前を入力し、場所を選択します。

  3. [作成] をクリックします。

  4. サイドバーで [API とサービス]、[ライブラリ] の順に選択します。

  5. ARCore API を検索して選択し、[有効にする] をクリックします。

認可を設定する

VPS に地理空間 API 呼び出しを行うには、アプリで承認が必要です。キーレス承認が推奨されていますが、API キー承認もサポートされています。

ARCore SDK 1.24.0 以降で構築された新しい Unity プロジェクトのデフォルトの認証戦略は、DoNotUse です。これは、不要なライブラリを使用してアプリがビルドされるのを防ぐためです。

キーレス認可

以前に使用していた API キーが不要になった場合は、Google Cloud Platform Console で削除してアプリから削除してください。

パッケージ名と署名鍵の異なる組み合わせ(debug、release など)については個別に登録する必要があります。

プロジェクトでキーレス認証を使用するには、次の手順に従います。

  1. Unity で、Edit > Project Settings > XR > ARCore Extensions に移動します。

  2. [Android Authentiation Strategy] プルダウンで、[Keyless] を選択します。

  3. Optional Features で、プロジェクトで使用している API のチェックボックスをオンにします。

  4. SHA-1 フィンガープリント署名鍵を生成します。

    1. Edit メニューから、Project Settings > Player > Publishing Settings を選択します。

    2. Keystore Manager をクリックして、新しいキーを作成します。

    3. SHA-1 フィンガープリント署名鍵をコピーします(後述のステップで貼り付けます)。

  5. OAuth クライアント ID を作成します。

    1. Google Cloud プロジェクトで、OAuth クライアント ID を作成します。

    2. SHA-1 fingerprint フィールドに、目的のバリアントの SHA-1 フィンガープリントを貼り付けます(前のステップでコピーしたもの)。

    3. CREATE をクリックして、OAuth クライアント ID を作成します。

API キーの承認

API キーを取得してプロジェクトに追加する手順は次のとおりです。

  1. Google Cloud Platform Console ヘルプセンターの説明に従って、Google Cloud Platform から鍵を取得します。

  2. Unity で、Edit > Project Settings > XR > ARCore Extensions に移動します。

  3. [Android Authentiation Strategy] プルダウンで、[API Key] を選択します。

  4. Android API Key フィールドに、Google Cloud Platform から取得した API キーを貼り付けます。

  5. Optional Features で、プロジェクトで使用している API のチェックボックスをオンにします。

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

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

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

ARCore をサポートするすべてのデバイスが Geospatial API もサポートしているわけではありません。ユーザーのデバイスの互換性を確認するには、AREarthManager.IsGeospatialModeSupported() を呼び出します。FeatureSupported.Unsupported が返された場合は、セッションを構成しようとしないでください。

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

ARCore 拡張機能は、ARCoreExtensions.Update() で地理空間モードが有効になっている場合、適切な位置情報の利用許可を自動的にリクエストします。ユーザーが正確な位置情報の利用許可を付与しない場合、セッションは再開されず、「権限が付与されていません」エラーが発生します。これは終了エラーで、権限リクエストを再度トリガーするには再起動する必要があります。

正確な現在地を確認する

CameraGeospatialPose は、特定の場所、標高、コンパス方位を地球を基準にして表します。AREarthManager オブジェクトで管理されています。

トラッキングの状態を確認する

地理空間値は、TrackingState.EarthTrackingStateTrackingState.Tracking の場合にのみ有効です。それ以外の場合、TrackingStateLimited または None になります。以下に示すように、地理空間 API 呼び出しは常に TrackingState コントロール ブロックでラップします。

var earthTrackingState = EarthManager.EarthTrackingState;
if (earthTrackingState == TrackingState.Tracking)
{
     // Values obtained by the Geospatial API are valid as long as
     // earthTrackingState is TrackingState.Tracking.
     // Use Geospatial APIs in this block.
}

その他のエラー状態や一般的な条件については、AREarthManager.EarthState をご覧ください。TrackingStateLimited または None の場合、AREarthManager.EarthState がこのエラーの原因を示していることがあります。

カメラの地理空間ポーズを取得する

TrackingStateTracking である間、地球の相対位置におけるカメラのポーズをリクエストします。

var earthTrackingState = EarthManager.EarthTrackingState;
if (earthTrackingState == TrackingState.Tracking)
{
  // camera_geospatial_pose contains geodetic location, rotation, and
  // confidences values.
  var cameraGeospatialPose = EarthManager.CameraGeospatialPose;
}

これにより、次の情報を含む GeospatialPose を取得できます。

  • 位置。緯度と経度で表されます。位置情報の精度の推定値も提供されます。
  • 標高と標高の推定値。
  • 方角、デバイスが向いている方向の近似値、方位精度の推定値。

姿勢の精度を調整する

VPS の姿勢の精度は、その位置の VPS データを利用できる状況や、位置が時間的に変動することにより変化することがあります。アプリでは、地理空間 API によって決定されるポーズの正確さを調整する必要が生じる場合があります。

Geospatial API では、VPS から返された緯度/経度、標高、方位値の精度を推定できます。

たとえば、左側の図に示すように、GeospatialPose.Heading から返された方位値が 60 度で、GeospatialPose.HeadingAccuracy の値が 10 度の場合、VPS 方位が、観測された方位の 10 度以内にある確率は 68% です。

方角の精度

GeospatialPose.HeadingAccuracy の値が 15 の場合、右の図に示すように、真の見出しが 60 度の 15 度以内にある可能性は 68% です。GeospatialPose.HeadingAccuracy から返される値が高いほど、GeospatialPose.Heading の見出し値の精度は「低」になります。

同様に、GeospatialPose.HorizontalAccuracy は、真の緯度 / 経度値が指定された距離内にある確率が 68% の範囲をメートルし、GeospatialPose.VerticalAccuracy は真の標高値が指定された距離内にある確率が 68% の範囲をメートル単位で報告します。

プロジェクトで Geospatial API を有効にする

  1. プロジェクトの Assets フォルダに ARCoreExtensionsConfig スクリプト可能オブジェクトが含まれていることを確認します。

    作成するには、Assets ペインで、Create > ARCore Extensions > ARCore Extensions Config を右クリックして選択します。

  2. ARCoreExtensionsConfig スクリプト可能オブジェクトを選択し、Inspector ウィンドウで Geospatial Mode のプルダウン メニューから Enabled を選択します。

  3. ARCoreExtensionsConfig 構成を使用するように ARCore Extensions ゲーム オブジェクトを構成します。

    1. Hierarchy ペインで、最初に ARCore 拡張機能を設定したときに作成した ARCore Extensions ゲーム オブジェクトを見つけます。

    2. ARCore Extensions Config フィールドを、Assets フォルダ内の ARCoreExtensionsConfig スクリプト可能オブジェクトに接続します。

地理空間アンカーを配置する

地理空間アンカーを配置するには、位置(緯度、経度、標高)と向き(四元数)を指定する必要があります。力を合わせ、アンカーのポーズを作ります。

緯度、経度、高度は WGS84 座標系で指定します。標高は、基準 WGS84 の楕円体の上方をメートルで表し、地面のレベルがゼロにならないようにします。作成されたアンカーごとに、アプリがこれらの座標を提供します。

場所の緯度と経度を調べる

緯度と経度は、次の 3 つの方法で計算できます。

  • Googleマップの使用
  • Google Earth を使用します(注: Google マップではなく Google Earth を使用してこれらの座標を取得すると、最大数メートルの誤差が生じます)。
  • 実際の場所に移動

Googleマップの使用

Google マップで場所の緯度と経度を取得するには:

  1. パソコンで Google マップにアクセスします。

  2. [レイヤ] > [その他] に移動します。

  3. [地図の種類] を [航空写真] に変更し、画面の左下にある [地球表示] チェックボックスをオフにします。

    これにより、2D ビューが強制的に使用され、3D ビューが斜めになっていてもエラーがなくなります。

  4. 地図上で右クリックし、経度と緯度を選択してクリップボードにコピーします。

Google Earth を使用

Google Earth では、管理画面で場所をクリックして、目印の詳細データを読み取ることで、緯度と経度を算出できます。

Google Earth で場所の緯度と経度を取得するには:

  1. パソコンで Google Earth にアクセスします。
  2. ハンバーガー メニュー に移動して、[地図のスタイル] を選択します。

  3. [建物の 3D 表示] スイッチをオフにします。

  4. 建物の 3D 表示スイッチをオフにしたら、固定アイコン をクリックして、選択した場所に目印を追加します。

  5. 目印を追加するプロジェクトを指定し、[保存] をクリックします。

  6. 目印の [タイトル] フィールドに目印の名前を入力します。

  7. プロジェクト ペインで戻る矢印 をクリックし、 [その他の操作] メニューを選択します。

  8. メニューから [KML ファイルとしてエクスポート] を選択します。

KLM ファイルは、次のように <coordinates> タグ内の目印の緯度、経度、標高をカンマで区切ります。

<coordinates>-122.0755182435043,37.41347299422944,7.420342565583832</coordinates>

<LookAt> タグの緯度と経度は使用せず、場所ではなくカメラの位置を指定してください。

実際の場所に移動

標高は、実際に足を運んで現地の観測を行って計算します。

場所の標高を確認する

アンカーを配置する場所の標高は、以下の複数の方法で特定できます。

  • アンカーの位置が物理的にユーザーの近くにある場合、ユーザーのデバイスの高度に似た標高を使用できます。
  • 緯度と経度を取得したら、Elevation API を使用して、EGM96 仕様に基づいて標高を取得します。GeospatialPose の標高と比較するには、Maps API EGM96 高度を WGS84 に変換する必要があります。コマンドラインと HTML インターフェースの両方を備えた GeoidEval をご覧ください。Maps API では、すぐに使用できる WGS84 仕様に沿って緯度と経度が報告されます。
  • 場所の緯度、経度、標高は Google Earth から取得できます。これにより、最大数メートルの誤差が生じます。KML ファイルの <LookAt> タグではなく、<coordinates> タグの緯度、経度、標高を使用します。
  • 既存のアンカーの付近かつ、急な傾斜がない場合、Maps API などの別のソースを使用せずにカメラの GeospatialPose から標高を使用できる場合があります。

回転四元数を取得する

+Z 軸が GeospatialPose で取得した方角と同じ方向を指す Pose.rotation 四元を作成するには、次の数式を使用します。

Quaternion quaternion =
                Quaternion.AngleAxis(180f - (float)pose.Heading, Vector3.up);

緯度、経度、標高、回転の四元数を取得したら、ARAnchorManagerExtensionsARAnchorManager.AddAnchor を使用して ARGeospatialAnchor を作成し、指定した地理座標にコンテンツをアンカーします。

if (earthTrackingState == TrackingState.Tracking)
{
  var anchor =
      AnchorManager.AddAnchor(
          latitude,
          longitude,
          altitude,
          quaternion);
  var anchoredAsset = Instantiate(GeospatialAssetPrefab, anchor.transform);
}

地表から指定した位置と向きにアンカーを置くと、WGS84 の仕様により緯度と経度が定義され、標高値(WGS84 楕円体より上)がメートル単位で定義されます。指定された回転四元数は、East-South-South(EUS)座標フレームに対するものです。ID の回転はアンカー方向として、X+ は東を指し、Y+ は地球の中心から離れて、Z+ は南を指します。

API 使用量の割り当て

ARCore SDK は、ARCore サービスに対する API リクエストを、ARCore SDK を使用するプロジェクトごとに次の上限に制限します。

  • 1 分あたり 1,000 セッションを開始
  • 1 分あたり 100,000 件のリクエスト

API リクエストがこれらの上限を超えた場合

EarthState.ErrorResourcesExhausted エラーで処理されなかった場合。