Informationen zur Nutzerumgebung im Android SDK (Kotlin/Java)

Weitere Informationen zur Verwendung der Scene Semantics API in Ihren eigenen Apps

Die Scene Semantics API ermöglicht es Entwicklern, die Umgebung des Nutzers zu verstehen, indem sie ML-Modell-basierte semantische Informationen in Echtzeit bereitstellen. Wenn Sie ein Bild einer Außenszene angeben, gibt die API für jedes Pixel ein Label für eine Reihe nützlicher semantischer Klassen zurück, z. B. Himmel, Gebäude, Baum, Straße, Bürgersteig, Fahrzeug oder Person. Neben Pixellabels bietet die Scene Semantics API auch Konfidenzwerte für jedes Pixellabel und eine nutzerfreundliche Möglichkeit, die Häufigkeit eines bestimmten Labels in einer Außenszene abzufragen.

Von links nach rechts: Beispiele für ein Eingabebild, das semantische Bild der Pixellabels und das entsprechende Konfidenzbild:

Vorbereitung

Machen Sie sich mit den grundlegenden AR-Konzepten und der Konfiguration einer ARCore-Sitzung vertraut, bevor Sie fortfahren.

Szenensemantik aktivieren

Prüfen Sie in einer neuen ARCore-Sitzung, ob das Gerät eines Nutzers die Scene Semantics API unterstützt. Nicht alle ARCore-kompatiblen Geräte unterstützen die Scene Semantics API aufgrund von Einschränkungen bei der Rechenleistung.

Aus Ressourcengründen ist die Szenensemantik in ARCore standardmäßig deaktiviert. Aktivieren Sie den semantischen Modus, damit Ihre App die Scene Semantics API verwendet.

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)

Semantisches Bild abrufen

Sobald die Szenensemantik aktiviert ist, kann das semantische Bild abgerufen werden. Das semantische Bild ist ein ImageFormat.Y8-Bild, bei dem jedes Pixel einem semantischen Label entspricht, das von SemanticLabel definiert wird.

Verwenden Sie Frame.acquireSemanticImage(), um das semantische Bild zu erfassen:

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

Die Ausgabe semantisch relevanter Bilder sollte je nach Gerät nach etwa 1–3 Frames nach Beginn der Sitzung verfügbar sein.

Bild mit Zuverlässigkeitsbewertung abrufen

Neben dem semantischen Bild, das ein Label für jedes Pixel enthält, stellt die API auch ein Konfidenzbild mit den entsprechenden Pixelkonfidenzwerten bereit. Das Konfidenzbild ist ein ImageFormat.Y8-Bild, bei dem jedem Pixel ein Wert im Bereich [0, 255] zugeordnet ist, der der Wahrscheinlichkeit entspricht, die mit dem semantischen Label für jedes Pixel verknüpft ist.

Verwenden Sie Frame.acquireSemanticConfidenceImage(), um das Bild mit der semantischen Konfidenz zu erhalten:

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

Bilder mit dem Konfidenzgrad sollten je nach Gerät nach etwa 1–3 Frames nach Beginn der Sitzung verfügbar sein.

Den Anteil der Pixel für ein semantisches Label abfragen

Sie können auch den Anteil der Pixel im aktuellen Frame abfragen, die zu einer bestimmten Klasse gehören, z. B. zum Himmel. Diese Abfrage ist effizienter als die Rückgabe des semantischen Bilds und die pixelweise Suche nach einem bestimmten Label. Der zurückgegebene Bruch ist ein Float-Wert im Bereich [0.0, 1.0].

Verwenden Sie Frame.getSemanticLabelFraction(), um den Bruchteil für ein bestimmtes Label abzurufen:

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