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 を使用できるようにします。

JavaKotlin
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() を使用してセマンティック画像を取得します。

JavaKotlin
// 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() を使用してセマンティック信頼度の画像を取得します。

JavaKotlin
// 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 フレーム後に利用可能になります。

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

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

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

JavaKotlin
// 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.
}