瞭解 Android SDK (Kotlin/Java) 的使用者環境's 環境

瞭解如何在自家應用程式中使用 Scene Semantics API。

Scene Semantics API 提供以機器學習模型為基礎的即時語意資訊，可讓開發人員瞭解使用者周遭環境。針對戶外場景的圖片，API 會為一系列實用的語意類別 (例如天空、建築物、樹木、道路、人行道、車輛、人形等) 傳回每個像素的標籤。除了像素標籤之外，場景語意 API 還會為每個像素標籤提供信心值，並提供簡單易用的查詢方式，可查詢特定標籤在戶外場景中的盛行率。

從左至右，分別為輸入圖片的示例、像素標籤的語意圖片，以及對應的信心圖片：

必要條件

請務必先瞭解基本 AR 概念，以及如何設定 ARCore 工作階段，再繼續操作。

啟用場景語意

在新的 ARCore 工作階段中，檢查使用者的裝置是否支援 Scene Semantics API。基於處理電力限制，並非所有與 ARCore 相容的裝置都支援 Scene Semantics API。

為節省資源，ARCore 預設會停用場景語意。啟用語意模式，讓應用程式使用 Scene Semantics API。

Java

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);

Kotlin

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() 取得語意圖片：

Java

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

Kotlin

// 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() 取得語意信心圖像：

Java

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

Kotlin

// 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() 取得特定標籤的分數：

Java

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

Kotlin

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