Entender o ambiente do usuário no SDK do Android (Kotlin/Java)

Aprenda a usar a API Scene Semantics nos seus próprios apps.

A API Scene Semantics permite que os desenvolvedores entendam o cenário em que o usuário está, fornecendo informações semânticas em tempo real com base em modelos de ML. Dada uma imagem de uma cena externa, a API retorna um rótulo para cada pixel em um conjunto de classes semânticas úteis, como céu, edifício, árvore, estrada, calçada, veículo, pessoa e muito mais. Além dos rótulos de pixel, a API Scene Semantics também oferece valores de confiança para cada rótulo de pixel e uma maneira fácil de usar de consultar a prevalência de um determinado rótulo em uma cena externa.

Da esquerda para a direita, exemplos de uma imagem de entrada, a imagem semântica dos rótulos de pixel e a imagem de confiança correspondente:

Pré-requisitos

Entenda os conceitos fundamentais de RA. e como configurar uma sessão do ARCore antes de continuar.

Ativar semântica de cena

Em uma nova sessão do ARCore, verifique se o dispositivo de um usuário é compatível com a API Scene Semantics. Nem todos os dispositivos compatíveis com ARCore têm suporte à API Scene Semantics devido a restrições de capacidade de processamento.

Para economizar recursos, a Scene Semantics fica desativada por padrão no ARCore. Ative o modo semântico para que o app use a API Scene Semantics.

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)

Receber a imagem semântica

Depois que a Semântica de cena é ativada, a imagem semântica pode ser recuperada. A imagem semântica é uma imagem ImageFormat.Y8, em que cada pixel corresponde a um rótulo semântico definido por SemanticLabel.

Use Frame.acquireSemanticImage() para adquirir a imagem semântica:

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

As imagens semânticas de saída precisam estar disponíveis após cerca de 1 a 3 frames do início da sessão, dependendo do dispositivo.

Obter a imagem de confiança

Além da imagem semântica, que fornece um rótulo para cada pixel, a API também fornece uma imagem de confiança de valores de confiança de pixel correspondentes. A imagem de confiança é uma imagem ImageFormat.Y8, em que cada pixel corresponde a um valor no intervalo [0, 255], correspondente à probabilidade associada ao identificador semântico de cada pixel.

Use Frame.acquireSemanticConfidenceImage() para adquirir a imagem de confiança em semântica:

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

As imagens de confiança de saída precisam estar disponíveis após cerca de 1 a 3 frames do início da sessão, dependendo do dispositivo.

Consultar a fração de pixels para encontrar um rótulo semântico

Também é possível consultar a fração de pixels no frame atual que pertencem a uma classe específica, como o céu. Essa consulta é mais eficiente do que retornar a imagem semântica e realizar uma pesquisa pixel por pixel de um rótulo específico. A fração retornada é um valor flutuante no intervalo [0.0, 1.0].

Use Frame.getSemanticLabelFraction() para adquirir a fração de um determinado rótulo:

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