Entender o ambiente do usuário no Android NDK (C)

Aprenda a usar a API Scene Semantics nos seus apps.

A API Scene Semantics permite que os desenvolvedores entendam o cenário ao redor do usuário, fornecendo informações semânticas em tempo real baseadas 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 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:

Exemplo de imagem de entrada, imagem semântica e imagem de confiança em semântica.

Pré-requisitos

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

Ativar a API Scene Semantics

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, o Scene Semantics é desativado por padrão no ARCore. Ative o modo semântico para que o app use a API Scene Semantics.

// Check whether the user's device supports the Scene Semantics API.
int32_t is_scene_semantics_supported = 0;
ArSession_isSemanticModeSupported(ar_session, AR_SEMANTIC_MODE_ENABLED, &is_scene_semantics_supported);

// Configure the session for AR_SEMANTIC_MODEL_ENABLED.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);
if (is_scene_semantics_supported) {
  ArConfig_setSemanticMode(ar_session, ar_config, AR_SEMANTIC_MODE_ENABLED);
}
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);
ArConfig_destroy(ar_config);

Receber a imagem semântica

Depois que a Scene Semantics for ativada, a imagem semântica poderá ser recuperada. A imagem semântica é uma imagem AR_IMAGE_FORMAT_Y8, em que cada pixel corresponde a um rótulo semântico definido por ArSemanticLabel.

Use ArFrame_acquireSemanticImage() para receber a imagem semântica:

// Retrieve the semantic image for the current frame, if available.
ArImage* semantic_image = NULL;
if (ArFrame_acquireSemanticImage(ar_session, ar_frame, &semantic_image) != AR_SUCCESS) {
  // 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.
  return;
}
// If a semantic image is available, use it here.

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.

Receber 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 dos valores de confiança de pixel correspondentes. A imagem de confiança é uma imagem AR_IMAGE_FORMAT_Y8, em que cada pixel corresponde a um valor no intervalo [0, 255], correspondente à probabilidade associada ao identificador semântico de cada pixel.

Use ArFrame_acquireSemanticConfidenceImage() para adquirir a imagem de confiança em semântica:

// Retrieve the semantic confidence image for the current frame, if available.
ArImage* semantic_confidence_image = NULL;
if (ArFrame_acquireSemanticConfidenceImage(ar_session, ar_frame, &semantic_confidence_image) != AR_SUCCESS) {
  // 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.
  return;
}
// If a semantic confidence image is available, use it here.

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

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

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

// Retrieve the fraction of pixels for the semantic label sky in the current frame.
float out_fraction = 0.0f;
if (ArFrame_getSemanticLabelFraction(ar_session, ar_frame, AR_SEMANTIC_LABEL_SKY, &out_fraction) != AR_SUCCESS) {
  // No fraction of semantic labels was retrieved for this frame.
}