Começar a usar as APIs Streetscape Geometry e Rooftop anchors 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 Geospatial Streetscape Geometry e Rooftop anchor ajudam suas experiências de RA a compreender edifícios nos arredores dos usuários.

Neste codelab, você vai criar um app de RA que visualiza a geometria da paisagem urbana na sua área e permite que você a decore. Em seguida, você vai usar âncoras no telhado para adicionar decorações em cima dos telhados ao seu redor.

Pré-requisitos

• Conhecimentos básicos sobre RA
• Conhecimentos básicos sobre a API ARCore Geospatial

O que você vai aprender

• Como configurar um projeto do Google Cloud que pode usar as APIs ARCore Geospatial.
• Como extrair a geometria da paisagem urbana da API Geospatial.
• Como exibir edifícios e terrenos extraídos da geometria da paisagem urbana.
• Como realizar cálculos básicos nos polígonos extraídos.
• Como realizar um teste de hit na geometria.
• Como usar âncoras no telhado para afixar conteúdos em cima dos edifícios.

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 usar as APIs Geospatial com o Kotlin e o Android Studio, você vai precisar de um projeto do Google Cloud e do nosso projeto inicial.

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) 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. Criar 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.

Configurar o Android Studio

Para começar a usar a API Geospatial, oferecemos um projeto inicial que aborda os princípios básicos de um projeto do ARCore integrado com a API Geospatial.

Para configurar o Android Studio, 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-streetscape-geometry-rooftop-anchors.git para importar o projeto.

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

Fazer uma verificação no projeto

• Para fazer uma verificação no 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. Também vão aparecer botões e controles que parecem não ter funcionalidade. Neste codelab, você vai programar essa funcionalidade no seu projeto.

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

3. Exibir dados de geometria da paisagem urbana

Depois de confirmar que a API Geospatial funciona no seu dispositivo, é possível extrair a geometria da paisagem urbana com a API Geospatial.

Ativar geometria da paisagem urbana

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

   // TODO: Enable Streetscape Geometry.
   

2. Depois dessa linha, ative o modo de geometria da paisagem urbana:

   streetscapeGeometryMode = Config.StreetscapeGeometryMode.ENABLED
   

   Quando a API Geospatial e o modo de geometria da paisagem urbana estão ativos, seu app pode receber informações da geometria da paisagem urbana em torno do usuário.

Extrair geometria da paisagem urbana

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

   // TODO: Obtain Streetscape Geometry.
   

2. Depois dessa linha, extraia a geometria da paisagem urbana filtrando todos os objetos Trackable com StreetscapeGeometry:

   val streetscapeGeometry = session.getAllTrackables(StreetscapeGeometry::class.java)
   

   Você usa essas geometrias em uma visualização simples oferecida no mesmo projeto. Ela exibe cada edifício ou polígono de terreno em cores diferentes.
3. Na próxima linha, adicione o código a seguir:

   streetscapeGeometryRenderer.render(render, streetscapeGeometry)
   

4. Execute seu app e vá até um edifício na sua área.
5. Depois que a localização geoespacial for concluída, toque em Configurações e ative a exibição da geometria da paisagem urbana.
6. Confira os edifícios em RA. Cada edifício segmentado tem uma cor própria, e os tipos enumerados Quality e Type da geometria mais central são mostrados.

Aviso: se a geometria da paisagem urbana não for mostrada ou se nenhuma decoração aparecer quando você tocar na tela, siga estas etapas para redefinir um checkpoint do codelab:

1. No Android Studio, clique em VCS > Git > Branches > Checkout > step-3. Depois disso, você vai voltar para a terceira etapa.
2. Acrescente sua chave de API ao arquivo AndroidManifest.xml, conforme detalhado nas instruções de configuração.

4. Realizar um teste de hit com dados de geometria da paisagem urbana

Agora que a geometria da paisagem urbana está sendo exibida, use um teste de hit para decorar o edifício. Um teste de hit encontra a interseção entre a geometria virtual e um raio. O teste de hit é usado para encontrar a geometria que um usuário toca.

Realizar um teste de hit

Nesta seção, você vai posicionar uma estrela na fachada do edifício quando o usuário tocar na geometria. Para fazer isso, use um teste de hit da perspectiva do usuário no mundo real e registre os objetos de RA encontrados quando ele está saindo do edifício. Depois disso, essas informações serão usadas para verificar se um usuário tocou no polígono de um edifício.

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

   // TODO: Create an anchor for a star, and add it to the starAnchors object.
   

2. Depois dessa linha, adicione o seguinte código:

   val centerHits = frame.hitTest(centerCoords[0], centerCoords[1])
   val hit = centerHits.firstOrNull {
     val trackable = it.trackable
     trackable is StreetscapeGeometry && trackable.type == StreetscapeGeometry.Type.BUILDING
   } ?: return
   

   Esse código usa as coordenadas de centro para encontrar uma geometria da paisagem urbana que seja um edifício. O resultado é usado para adicionar decorações.

Acrescentar uma decoração de estrela com um toque

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

   // TODO: Create an anchor for a star, and add it to the starAnchors object.
   

2. Depois dessa linha, adicione o seguinte código:

   val transformedPose = ObjectPlacementHelper.createStarPose(hit.hitPose)
   val anchor = hit.trackable.createAnchor(transformedPose)
   starAnchors.add(anchor)
   

   A classe ObjectPlacementHelper determina um local apropriado para posicionar a estrela usando a pose do hit como referência. O objeto starAnchors é usado para renderizar as estrelas na exibição em RA.

Testar

1. Execute seu app e vá até um edifício na sua área.
2. Depois que a localização geoespacial for concluída, foque sua câmera no edifício e toque na tela. Uma estrela vai aparecer no edifício no centro da tela.

Aviso: se a geometria da paisagem urbana não for mostrada ou se nenhuma decoração aparecer quando você tocar na tela, siga estas etapas:

1. No Android Studio, clique em VCS > Git > Branches > Checkout > step-4.
2. Acrescente sua chave de API ao arquivo AndroidManifest.xml, conforme detalhado nas instruções de configuração.

5. Usar dados da âncora no telhado

Por fim, você vai usar âncoras no telhado para adicionar decorações em cima do edifício. As âncoras no telhado ajudam você a afixar âncoras de RA em cima dos edifícios usando latitude e longitude. Elas podem ser usadas para posicionar balões nos edifícios ao redor do usuário.

Adicionar comportamentos ao modo de balão

O projeto tem dois modos de posicionamento de recursos: o modo de estrela e o de girassol, que você já usou.

Para programar o comportamento para o modo de balão, siga estas etapas:

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

   // TODO: Create an anchor for a balloon and add it to the balloonAnchors object.
   

2. Use a pose do hit para criar um bom local para o balão:

   val transformedPose = ObjectPlacementHelper.createBalloonPose(hit.hitPose)
   

3. Converta a variável transformedPose em uma pose geoespacial:

   val earth = session?.earth ?: return
   val geospatialPose = earth.getGeospatialPose(transformedPose)
   

4. Crie uma âncora no telhado com a latitude e a longitude transformadas:

   earth.resolveAnchorOnRooftopAsync(
     geospatialPose.latitude, geospatialPose.longitude,
     0.0,
     transformedPose.qx(), transformedPose.qy(), transformedPose.qz(), transformedPose.qw()
   ) { anchor, state ->
     if (!state.isError) {
       balloonAnchors.add(anchor)
     }
   }
   

Fazer o teste

1. Execute seu app e vá até um edifício na sua área.
2. Depois que a localização geoespacial for concluída, mude para o modo de balão e toque em um edifício. Um balão vai aparecer em cima do edifício.

Se você não conseguir replicar o comportamento esperado, siga estas etapas:

1. No Android Studio, clique em VCS > Git > Branches > Checkout > step-5.
2. Acrescente sua chave de API ao arquivo AndroidManifest.xml, conforme detalhado nas instruções de configuração.

6. Conclusão

Parabéns! Você criou um app de RA que visualiza a geometria da paisagem urbana na sua área e permite que você a decore com estrelas. Você também usou âncoras no telhado para acrescentar um balão em cima dos telhados perto de você.

Saiba mais

• Guia para desenvolvedores sobre geometria da paisagem urbana
• Guia para desenvolvedores sobre âncoras de telhado
• Aspectos gerais da API Geospatial