Android SDK（Kotlin/Java）でのユーザーの環境を理解する

独自のアプリで Scene Semantics API を使用する方法を学びます。

Scene Semantics API を使用すると、ML モデルベースのリアルタイムのセマンティック情報を提供することで、デベロッパーはユーザーの周囲のシーンを理解できます。屋外の画像を指定すると、API は空、建物、木、道路、歩道、車両、人など、一連の有用なセマンティック クラスにわたる各ピクセルのラベルを返します。ピクセルラベルに加えて、Scene Semantics API は、各ピクセルラベルの信頼値と、屋外シーンにおける特定のラベルの占有率を照会する簡単な方法も提供します。

左から順に、入力画像、ピクセルラベルのセマンティック画像、対応する信頼度画像の例を示しています。

前提条件

AR の基礎的なコンセプトを理解しておいてください。 と ARCore セッションを構成する方法を確認してください。

Scene Semantics を有効にする

新しい ARCore セッションで、ユーザーのデバイスが Scene Semantics API をサポートしているかどうかを確認します。処理能力に制約があるため、すべての ARCore 対応デバイスが Scene Semantics API をサポートしているわけではありません。

リソースを節約するため、ARCore の Scene Semantics はデフォルトで無効になっています。アプリで Scene Semantics API を使用するには、セマンティック モードを有効にします。

Config config = session.getConfig();

// Check whether the user's device supports the Scene Semantics API.
boolean isSceneSemanticsSupported =
    session.isSemanticModeSupported(Config.SemanticMode.ENABLED);
if (isSceneSemanticsSupported) {
  config.setSemanticMode(Config.SemanticMode.ENABLED);
}
session.configure(config);

val config = session.config

// Check whether the user's device supports the Scene Semantics API.
val isSceneSemanticsSupported = session.isSemanticModeSupported(Config.SemanticMode.ENABLED)
if (isSceneSemanticsSupported) {
  config.semanticMode = Config.SemanticMode.ENABLED
}
session.configure(config)

セマンティック画像を取得する

シーン セマンティクスが有効になると、セマンティック画像を取得できます。セマンティック画像は ImageFormat.Y8 画像で、各ピクセルは SemanticLabel で定義されたセマンティック ラベルに対応しています。

Frame.acquireSemanticImage() を使用してセマンティック画像を取得します。

// Retrieve the semantic image for the current frame, if available.
try (Image semanticImage = frame.acquireSemanticImage()) {
  // Use the semantic image here.
} catch (NotYetAvailableException e) {
  // No semantic image retrieved for this frame.
  // The output image may be missing for the first couple frames before the model has had a
  // chance to run yet.
}

// Retrieve the semantic image for the current frame, if available.
try {
  frame.acquireSemanticImage().use { semanticImage ->
    // Use the semantic image here.
  }
} catch (e: NotYetAvailableException) {
  // No semantic image retrieved for this frame.
}

デバイスに応じて、セッションの開始から約 1 ～ 3 フレーム後に出力セマンティック画像を利用できるようになる必要があります。

信頼性の画像を取得する

この API は、各ピクセルのラベルを提供するセマンティック画像に加えて、対応するピクセル信頼度の信頼度画像も提供します。信頼度の画像は ImageFormat.Y8 画像です。ここで、各ピクセルは [0, 255] の範囲の値に対応し、各ピクセルのセマンティック ラベルに関連付けられた確率に対応します。

Frame.acquireSemanticConfidenceImage() を使用してセマンティック信頼度の画像を取得します。

// Retrieve the semantic confidence image for the current frame, if available.
try (Image semanticImage = frame.acquireSemanticConfidenceImage()) {
  // Use the semantic confidence image here.
} catch (NotYetAvailableException e) {
  // No semantic confidence image retrieved for this frame.
  // The output image may be missing for the first couple frames before the model has had a
  // chance to run yet.
}

// Retrieve the semantic confidence image for the current frame, if available.
try {
  frame.acquireSemanticConfidenceImage().use { semanticConfidenceImage ->
    // Use the semantic confidence image here.
  }
} catch (e: NotYetAvailableException) {
  // No semantic confidence image retrieved for this frame.
}

出力信頼度の画像は、デバイスに応じて、セッションの開始から約 1 ～ 3 フレーム後に利用可能になります。

セマンティック ラベルのピクセル数の割合をクエリする

現在のフレーム内で Sky などの特定のクラスに属するピクセルの割合をクエリすることもできます。このクエリは、セマンティック画像を返して特定のラベルをピクセル単位で検索するよりも効率的です。返される小数は、範囲 [0.0, 1.0] 内の浮動小数点値です。

Frame.getSemanticLabelFraction() を使用して、指定したラベルの分数を取得します。

// Retrieve the fraction of pixels for the semantic label sky in the current frame.
try {
  float outFraction = frame.getSemanticLabelFraction(SemanticLabel.SKY);
  // Use the semantic label fraction here.
} catch (NotYetAvailableException e) {
  // No fraction of semantic labels was retrieved for this frame.
}

// Retrieve the fraction of pixels for the semantic label sky in the current frame.
try {
  val fraction = frame.getSemanticLabelFraction(SemanticLabel.SKY)
  // Use the semantic label fraction here.
} catch (e: NotYetAvailableException) {
  // No fraction of semantic labels was retrieved for this frame.
}