Começar a usar as APIs Scene Semantics e Geospatial Depth no ARCore

1. Antes de começar

O ARCore é o framework do Google voltado à criação de experiências de realidade aumentada (RA) em smartphones. As APIs Scene Semantics e Geospatial Depth ajudam suas experiências de RA a entender melhor o ambiente ao redor dos seus usuários.

A API Scene Semantics usa um modelo de aprendizado de máquina (ML) para analisar imagens de câmera e proporcionar uma imagem de pixels identificados. Ela consegue distinguir entre 11 identificadores externos diferentes.

A API Geospatial Depth combina informações de profundidade do movimento e de quaisquer sensores de hardware ativos, como tempo de voo, com os dados da API Streetscape Geometry. Ela reduz os erros em observações de profundidade em até 65 metros.

Neste codelab, você vai criar um app de RA que exibe os resultados das APIs Scene Semantics e Geospatial Depth.

Pré-requisitos

• Conhecimentos básicos sobre RA

O que você vai aprender

• Como ativar a API Scene Semantics.
• Como receber e exibir uma imagem semântica.
• Como receber e exibir uma imagem de confiança em semântica.
• Como determinar a porcentagem de pixels que corresponde a um certo identificador.
• Como configurar um projeto do Google Cloud que pode usar as APIs ARCore Geospatial.
• Como ativar a API Geospatial Depth.
• Como exibir imagens com profundidade.

O que você vai precisar

• Um dispositivo Android com suporte ao ARCore conectado com um cabo USB à sua máquina de desenvolvimento e configurado com depuração USB.
• Google Play Services para RA 1.37 ou versão mais recente instalado no dispositivo Android de desenvolvimento.
• Android Studio instalado e configurado para a criação de apps Android.

2. Configurar o ambiente

Para começar a usar a API Geospatial, oferecemos um projeto inicial que aborda os princípios básicos de um projeto de ARCore e algumas funções auxiliares.

Para configurar o projeto inicial, siga estas etapas:

1. Abra o Android Studio e realize uma dentre as seguintes ações:
   • Se você já tiver um projeto aberto, clique em File > New > Project from version control.
   • Na janela Welcome to Android Studio, clique em Get from VCS.
2. Selecione Git e digite https://github.com/google-ar/codelab-scene-semantics-geospatial-depth.git para importar o projeto.

3. Exibir dados da API Scene Semantics

Ativar a API Scene Semantics

A API Scene Semantics é desativada por padrão para economizar a capacidade de processamento.

Para ativar a API Scene Semantics, siga estas etapas:

1. No arquivo CodelabActivity.kt, encontre a seguinte linha:

   // TODO: Enable the Scene Semantics API.
   

2. Depois dessa linha, se isso for aceito pelo seu dispositivo, ative a API Scene Semantics na configuração da sessão:

     if (session.isSemanticModeSupported(Config.SemanticMode.ENABLED)) {
       semanticMode = Config.SemanticMode.ENABLED
     }
   

Receber e exibir uma imagem semântica

A imagem semântica é um resultado do modelo de ML do ARCore que atribui um tipo enumerado SemanticLabel a cada pixel no feed da câmera.

Para receber uma imagem semântica e exibi-la na tela, siga estas etapas:

1. No arquivo CodelabRenderer.kt, encontre a seguinte linha:

   // TODO: Obtain the semantic image for this frame.
   

2. Depois dessa linha, receba uma imagem semântica:

     frame.acquireSemanticImage().use { image ->
       semanticRenderer.updateCameraSemanticsTexture(image)
       activity.view.semanticLabelAtCenter = getLabelAt(image, image.width/2, image.height/2)
     }
   

   A imagem semântica é usada na classe SemanticRenderer para exibição na tela. Você atualiza a variável semanticLabelAtCenter para mostrar o identificador semântico no centro da tela na exibição do app.
3. Execute o app e aponte a câmera para objetos diferentes no espaço aberto. O identificador semântico muda quando você visualiza tipos diferentes de objetos.
4. Toque em Settings para ativar a sobreposição de imagem de confiança em semântica.

Receber e exibir uma imagem de confiança em semântica

A imagem de confiança em semântica indica quanto o ARCore confia no identificador semântico no pixel correspondente.

Para receber uma imagem semântica e exibi-la na tela, siga estas etapas:

1. No arquivo CodelabRenderer.kt, encontre a seguinte linha:

   // TODO: Obtain the confidence image for this frame.
   

2. Depois da linha, receba uma imagem semântica:

   frame.acquireSemanticConfidenceImage().use { image ->
     semanticRenderer.updateConfidenceSemanticsTexture(image)
     activity.view.confidenceAtCenter = getConfidenceAt(image, image.width/2, image.height/2)
   }
   

   A imagem de confiança em semântica é usada na classe SemanticRenderer para exibição na tela. Você atualiza a variável confidenceAtCenter para mostrar o identificador semântico no centro da tela na exibição do app.
3. Execute o app e aponte a câmera para objetos diferentes no espaço aberto. A confiança em semântica muda quando você visualiza tipos diferentes de objetos.
4. Toque em Settings para ativar a sobreposição de imagem de confiança em semântica.

Determinar a prevalência de um identificador

A prevalência é a porcentagem de uma imagem semântica que é idêntica a um determinado identificador. Por exemplo, se 26% da imagem tiver o valor SemanticLabel.SKY, então a prevalência de SemanticLabel.SKY será 0.26f.

Para receber a prevalência dos identificadores e mostrá-los na tela, siga estas etapas:

1. No arquivo CodelabRenderer.kt, encontre a seguinte linha:

   // TODO: Obtain the prevalence of the selected label for this frame.
   

2. Depois da linha, receba a prevalência para o identificador selecionado:

   frame.acquireSemanticConfidenceImage().use { image ->
     semanticRenderer.updateConfidenceSemanticsTexture(image)
     activity.view.confidenceAtCenter = getConfidenceAt(image, image.width/2, image.height/2)
   }
   

3. Execute o app e aponte a câmera para objetos diferentes no espaço aberto. A confiança em semântica muda quando você visualiza tipos diferentes de objetos.
4. Toque em Settings para ativar a sobreposição de imagem de confiança em semântica.

4. Exibir dados da API Geospatial Depth

A API Geospatial Depth melhora as leituras de profundidade quando as APIs Geospatial e Streetscape Geometry estão ativadas. Para usar a API Geospatial Depth com o Kotlin e o Android Studio, você precisa de um projeto do Google Cloud.

Configurar um projeto do Google Cloud

A API ARCore Geospatial se conecta com o Google Cloud para oferecer informações de localização do sistema de posicionamento visual (VPS, na sigla em inglês) do Google em áreas abrangidas pelo Google Street View.

Para usar esse servidor no seu projeto, siga estas etapas:

1. Crie um projeto no Google Cloud.
   
   
2. No campo Nome do projeto, digite um nome adequado, como ARCore Geospatial API project, e depois escolha um local.
3. Clique em Criar.
4. No console do Google Cloud ou na página de seleção de projetos, clique em Criar projeto.
5. Clique no link a seguir para exibir a API ARCore para este projeto e depois clique em Ativar:
   Ativar a API ARCore
6. Crie uma chave de API para o seu projeto:
   1. Em APIs e serviço, clique em Credenciais.
   2. Clique em Criar credenciais e selecione Chave de API.
   3. Anote essa chave, porque você vai precisar dela mais tarde.

Você criou um projeto do Google Cloud com autorização de chave de API e está com tudo pronto para usar a API Geospatial no projeto de amostra.

Integrar a chave de API com o projeto do Android Studio

Para associar a chave de API do Google Cloud ao seu projeto, siga estas etapas:

1. No Android Studio, clique em app > src e dê um clique duplo em AndroidManifest.xml.
2. Encontre as seguintes entradas de meta-data:

   <meta-data
       android:name="com.google.android.ar.API_KEY"
       android:value="API_KEY" />
   

3. Substitua o marcador de posição API_KEY pela chave de API que você criou no projeto do Google Cloud. O valor armazenado em com.google.android.ar.API_KEY autoriza o app a usar a API Geospatial.

Verificar seu projeto

• Para verificar seu projeto, execute o app no seu dispositivo de desenvolvimento. Uma visualização de câmera e as informações de depuração geoespaciais vão aparecer na parte de cima da tela.

Atenção: se a API Geospatial não inicializar, certifique-se de que a chave de API foi inserida no arquivo AndroidManifest.xml exatamente como aparece no Google Cloud.

Ativar as configurações necessárias

A API Geospatial Depth precisa que três configurações sejam ativadas na sua sessão do app.

Para fazer isso, siga estas etapas:

1. No arquivo CodelabRenderer.kt, encontre a seguinte linha:

   // TODO: Enable the Geospatial API, the Streetscape Geometry API, and the Depth API.
   

2. Na próxima linha, adicione o código a seguir:

   val isDepthSupported = session.isDepthModeSupported(Config.DepthMode.AUTOMATIC)
   val isGeospatialSupported = session.isGeospatialModeSupported(Config.GeospatialMode.ENABLED)
   if (isDepthSupported && isGeospatialSupported) {
     // These three settings are needed to use Geospatial Depth.
     geospatialMode = Config.GeospatialMode.ENABLED
     streetscapeGeometryMode = Config.StreetscapeGeometryMode.ENABLED
     depthMode = Config.DepthMode.AUTOMATIC
   }
   

Exibir informações de profundidade

1. No arquivo CodelabRenderer.kt, encontre a seguinte linha:

   // TODO: Obtain depth information and display it.
   

2. Na próxima linha, adicione o código a seguir:

   try {
     frame.acquireDepthImage16Bits().use { image ->
       backgroundRenderer.updateCameraDepthTexture(depthImage)
     }
   } catch (e: NotYetAvailableException) {
     // No depth information is available.
   }
   

3. Execute seu app e vá até um edifício na sua área.
4. Depois que a localização geoespacial for concluída, toque em Settings e ative a exibição da profundidade geoespacial.
5. Exiba o edifício em RA e a compare às informações de profundidade sem profundidade geoespacial.

5. Conclusão

Parabéns! Você criou um app de RA que visualiza a profundidade geoespacial e as semânticas da cena.

Saiba mais

• Guia para desenvolvedores sobre a API Scene Semantics
• Guia para desenvolvedores sobre a API Geospatial Depth