ARCore の Scene Semantics API と Geospatial Depth API を使ってみる

1. 始める前に

ARCore は、スマートフォンで拡張現実（AR）エクスペリエンスを構築するための Google のフレームワークです。Scene Semantics API と Geospatial Depth API は、AR エクスペリエンスでユーザーの周囲の環境を把握できるようにします。

Scene Semantics API は、機械学習（ML）モデルを使用してカメラの画像を分析し、ラベル付けされたピクセルの画像を提供します。11 種類の屋外ラベルを区別できます。

Geospatial Depth API は、動きや ToF（Time of Flight）などのアクティブなハードウェアのセンサーから得られる深度の情報と、Streetscape Geometry API のデータを組み合わせます。最大 65 メートル離れた場所の深度を観測し、エラーを補正します。

この Codelab では、Scene Semantics API と Geospatial Depth API の結果を可視化する AR アプリを作成します。

前提条件

AR に関する基本的な知識

学習内容

Scene Semantics API を有効にする方法。
セマンティック画像を取得し、可視化する方法。
セマンティック信頼度の画像を取得し、可視化する方法。
特定のラベルに対応したピクセルの割合を判断する方法。
ARCore Geospatial API を使用できる Google Cloud プロジェクトをセットアップする方法。
Geospatial Depth API を有効にする方法。
深度の画像を可視化する方法。

必要なもの

ARCore 対応の Android デバイス（開発マシンと USB ケーブルで接続され、USB デバッグが構成されていること）。
Android 開発用デバイスに Google Play 開発者サービス（AR） 1.37 以上がインストールされていること。
Android Studio がインストールされ、Android アプリをビルドできるように構成されていること。

2. 環境をセットアップする

Geospatial API を使い始めるにあたって、基本的な ARCore プロジェクトといくつかのヘルパー関数を含むスタータープロジェクトを用意しています。

スタータープロジェクトをセットアップするには、次の手順を実施します。

Android Studio を開き、次のいずれかを行います。
- すでにプロジェクトを開いている場合は、[File] > [New] > [Project from version control] をクリックします。
- [Welcome to Android Studio] ウィンドウが表示されたら、[Get from VCS] をクリックします。
[Git] を選択し、「https://github.com/google-ar/codelab-scene-semantics-geospatial-depth.git」と入力してプロジェクトをインポートします。

3. Scene Semantics API データの可視化

Scene Semantics API を有効にする

処理能力を節約するため、Scene Semantics API はデフォルトで無効になっています。

Scene Semantics API を有効にするには次の手順を実施します。

CodelabActivity.kt ファイルを開き、次の行を見つけます。
```
// TODO: Enable the Scene Semantics API.
```
その行の後で、デバイスで Scene Semantics API がサポートされていれば、セッションの構成で Scene Semantics API を有効にします。
```
  if (session.isSemanticModeSupported(Config.SemanticMode.ENABLED)) {
    semanticMode = Config.SemanticMode.ENABLED
  }
```

セマンティック画像の取得と可視化

セマンティック画像とは、SemanticLabel 列挙型をカメラフィード内の各ピクセルに割り当てた、ARCore ML モデルの結果です。

セマンティック画像の例

セマンティック画像を取得して画面上に表示するには、次の手順を実施します。

CodelabRenderer.kt ファイルを開き、次の行を見つけます。
```
// TODO: Obtain the semantic image for this frame.
```
その行の後で、セマンティック画像を取得します。
```
  frame.acquireSemanticImage().use { image ->
    semanticRenderer.updateCameraSemanticsTexture(image)
    activity.view.semanticLabelAtCenter = getLabelAt(image, image.width/2, image.height/2)
  }
```
セマンティック画像を画面に表示するには、SemanticRenderer クラス内でその画像を使用します。semanticLabelAtCenter 変数を更新して、アプリのビューの画面中央にセマンティックラベルを表示します。
アプリを起動してカメラを屋外のさまざまなオブジェクトに向けます。別の種類のオブジェクトに向けると、セマンティックラベルの表示が変化します。
[Settings] をタップしてセマンティック信頼度の画像オーバーレイを有効にします。

セマンティック信頼度の画像の取得と可視化

セマンティック信頼度の画像は、対応するピクセルのセマンティックラベルに対する ARCore の信頼度を示します。

セマンティック画像を取得して画面上に表示するには、次の手順を実施します。

CodelabRenderer.kt ファイルを開き、次の行を見つけます。
```
// TODO: Obtain the confidence image for this frame.
```
その行の後で、セマンティック画像を取得します。
```
frame.acquireSemanticConfidenceImage().use { image ->
  semanticRenderer.updateConfidenceSemanticsTexture(image)
  activity.view.confidenceAtCenter = getConfidenceAt(image, image.width/2, image.height/2)
}
```
セマンティック信頼度の画像を画面に表示するには、SemanticRenderer クラス内でその画像を使用します。confidenceAtCenter 変数を更新して、アプリのビューの画面中央にセマンティックラベルを表示します。
アプリを起動してカメラを屋外のさまざまなオブジェクトに向けます。別の種類のオブジェクトに向けると、セマンティック信頼度の表示が変化します。
[Settings] をタップしてセマンティック信頼度の画像オーバーレイを有効にします。

ラベルの占有率の判断

ラベルの占有率とは、セマンティック画像の中で特定のラベルに等しい部分の割合です。たとえば、画像中の 26% にSemanticLabel.SKY の値がある場合、SemanticLabel.SKY の占有率の値は 0.26f です。

ラベルの占有率を取得して画面上に表示するには、次の手順を実施します。

CodelabRenderer.kt ファイルを開き、次の行を見つけます。
```
// TODO: Obtain the prevalence of the selected label for this frame.
```

その行の後で、選択したラベルの占有率を取得します。

frame.acquireSemanticConfidenceImage().use { image ->
  semanticRenderer.updateConfidenceSemanticsTexture(image)
  activity.view.confidenceAtCenter = getConfidenceAt(image, image.width/2, image.height/2)
}

アプリを起動してカメラを屋外のさまざまなオブジェクトに向けます。別の種類のオブジェクトに向けると、セマンティック信頼度の表示が変化します。
[Settings] をタップしてセマンティック信頼度の画像オーバーレイを有効にします。

4. Geospatial Depth API データの可視化

Geospatial Depth API は、Geospatial API と Streetscape Geometry API が有効になっている場合に、深度の読み取りを向上させます。Kotlin と Android Studio で Geospatial Depth API を使用するには、Google Cloud プロジェクトが必要です。

Google Cloud プロジェクトをセットアップする

ARCore Geospatial API は Google Cloud に接続し、Google ストリートビューがカバーするエリアで Google の Visual Positioning System（VPS）からのローカライズ情報を提供します。

自分のプロジェクトでこのサーバーを使用する手順は次のとおりです。

Google Cloud でプロジェクトを作成します。
[プロジェクト名] フィールドに、「ARCore Geospatial API project」などの適切な名前を入力し、任意の場所を選択します。
[作成] をクリックします。
Google Cloud コンソールのプロジェクト選択ページで [プロジェクトを作成] をクリックします。
以下のリンクをクリックしてこのプロジェクトの ARCore API を表示し、[有効にする] を選択します。
プロジェクトの API キーを作成します。
1. [API とサービス] で [認証情報] を選択します。
2. [認証情報を作成] をクリックし、[API キー] を選択します。
3. 以降の手順で必要になるため、キーを書き留めておきます。

API キー認証がある Google Cloud プロジェクトを作成できました。これで、サンプルプロジェクトで Geospatial API を使用する準備が整いました。

API キーを Android Studio プロジェクトに統合する

Google Cloud の API キーをプロジェクトに関連付ける手順は次のとおりです。

Android Studio で [app] > [src] をクリックし、AndroidManifest.xml をダブルクリックします。

以下の meta-data エントリを見つけます。

<meta-data
    android:name="com.google.android.ar.API_KEY"
    android:value="API_KEY" />

API_KEY のプレースホルダを Google Cloud プロジェクトで作成した API キーに置き換えます。com.google.android.ar.API_KEY に格納されている値は、このアプリが Geospatial API を使用することを許可するものです。

プロジェクトを検証する

プロジェクトを検証するために、開発用デバイスでアプリを実行します。画面上部にカメラビューと地理空間デバッグ情報が表示されます。

アプリに表示される地理空間情報

必要な構成を有効にする

Geospatial Depth API を使用するには、アプリのセッション構成で 3 つの設定を有効にする必要があります。

それらを有効にする手順は次のとおりです。

CodelabRenderer.kt ファイルを開き、次の行を見つけます。

// TODO: Enable the Geospatial API, the Streetscape Geometry API, and the Depth API.

この次の行に、以下のコードを追加します。

val isDepthSupported = session.isDepthModeSupported(Config.DepthMode.AUTOMATIC)
val isGeospatialSupported = session.isGeospatialModeSupported(Config.GeospatialMode.ENABLED)
if (isDepthSupported && isGeospatialSupported) {
  // These three settings are needed to use Geospatial Depth.
  geospatialMode = Config.GeospatialMode.ENABLED
  streetscapeGeometryMode = Config.StreetscapeGeometryMode.ENABLED
  depthMode = Config.DepthMode.AUTOMATIC
}

深度情報を可視化する

CodelabRenderer.kt ファイルを開き、次の行を見つけます。
```
// TODO: Obtain depth information and display it.
```