Criar um app de realidade aumentada (RA) usando a nova API ARCore Geospatial

1. Informações gerais

O ARCore é o framework do Google voltado à criação de experiências de realidade aumentada em smartphones. A nova API ARCore Geospatial concede um novo aspecto à realidade aumentada, permitindo que você posicione waypoints de realidade aumentada específicos do local ao redor de pontos de referência do mundo real.

O que você vai criar

Neste codelab, você vai começar a usar a API ARCore Geospatial. Você vai descobrir quais informações a API Geospatial pode oferecer para sua experiência geral de RA e como esses dados podem ser usados para potencializar uma experiência simples de orientação em RA.

Conteúdo

• Como configurar um projeto do ARCore que usa a API Geospatial.
• Como solicitar dados geográficos da API Geospatial e mostrar essas informações usando o Google Maps.
• Como colocar uma âncora anexada a um local do mundo real.

Pré-requisitos

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

2. Configurar seu ambiente de desenvolvimento

Configurar o Android Studio

Para começar a usar a API Geospatial, oferecemos um projeto inicial que inclui os conceitos básicos de um projeto do ARCore integrado com o SDK do Google Maps. Com isso, você tem um início rápido usando a API Geospatial.

1. Inicie o Android Studio e importe um projeto do VCS.
   • Se você já tiver um projeto aberto, use File > New > Project from Version Control....
   • Na janela Welcome to Android Studio, use Get from VCS.
2. Selecione Git e use o URL https://github.com/google-ar/codelab-geospatial.git para importar o projeto.

Configurar um projeto do Google Cloud

A API Geospatial usa imagens do Street View combinadas com as informações do sensor da câmera e do magnetômetro do dispositivo para melhorar os valores de orientação. Para usar este serviço, você precisa configurar um projeto do Google Cloud.

1. Crie um projeto no console do Google Cloud:
   • Acesse Criar um projeto no Google Cloud Platform.
     
   • Digite o Nome do projeto (por exemplo, "Projeto da API ARCore Geospatial") e escolha um local.
   • Clique em Criar.
2. Ative as APIs necessárias:
   • Na barra lateral, selecione APIs e serviços e Biblioteca.
   • Procure a API ARCore.
   • Selecione Ativar.
   • Volte à Biblioteca.
   • Pesquise o SDK do Maps para Android.
   • Selecione Ativar.
3. Criar credenciais da chave de API:
   • Em APIs e serviços, selecione Credenciais.
   • Na barra superior, clique em Criar credenciais e selecione Chave de API.
   • Anote a chave que foi criada porque você vai precisar dela para a próxima etapa. Volte para a página Credenciais se você precisar recuperá-las.

Após concluir essas etapas, você criou um projeto do Google Cloud com autorização de chave de API e já pode usar a API Geospatial.

Integrar a chave de API ao projeto do Android Studio

Para associar a chave de API do Google Cloud ao seu projeto, abra o projeto que você criou no Android Studio e modifique as chaves de API:

1. Abra app > src > AndroidManifest.xml.
2. Encontre as seguintes meta-data entradas:

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

3. Substitua PLACEHOLDER_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, e o valor armazenado em com.google.android.geo.API_KEY autoriza o app a usar o SDK do Google Maps.

Verificar seu projeto

Verifique se o projeto está pronto. No Android Studio, execute o app. Você verá uma visualização da câmera e um mapa em funcionamento na parte de baixo da tela.

3. Determinar a posição do usuário

Nesta etapa, você vai adicionar um código ao projeto de amostra para começar a usar a API Geospatial.

Configurar a sessão do ARCore para usar a API Geospatial

Para acessar dados geoespaciais, é necessário ativar a API Geospatial. Mude a GeospatialMode na configuração da sessão para ENABLED modificando a função configureSession em HelloGeoActivity.kt:

fun configureSession(session: Session) {
  session.configure(
    session.config.apply {
      // Enable Geospatial Mode.
      geospatialMode = Config.GeospatialMode.ENABLED
    }
  )
}

Enquanto o modo geoespacial for ENABLED, o aplicativo poderá receber informações geoespaciais.

Solicitar dados da API Geospatial

Em HelloGeoRenderer.kt, encontre a seguinte linha:

// TODO: Obtain Geospatial information and display it on the map.

Abaixo dele, verifique se o objeto Earth está disponível para uso. Nesse momento, ele tem trackingState TrackingState.ENABLED.

val earth = session.earth
if (earth?.trackingState == TrackingState.TRACKING) {
  // TODO: the Earth object may be used here.
}

Abaixo de TODO, solicite informações geoespaciais do ARCore. Adicione esta linha:

val cameraGeospatialPose = earth.cameraGeospatialPose

Isso gera um GeospatialPose com estas informações:

• Local, expresso em latitude e longitude. Uma estimativa da precisão do local também é fornecida.
• Elevação e uma estimativa da precisão da elevação.
• título, uma aproximação da direção para o dispositivo e uma estimativa da precisão da direção.

Exibir informações de posicionamento no mapa

Você pode usar o GeospatialPose armazenado no cameraGeospatialPose para mover um marcador no mapa que mostra onde o usuário está. Continue de onde parou e adicione o seguinte:

activity.view.mapView?.updateMapPosition(
  latitude = cameraGeospatialPose.latitude,
  longitude = cameraGeospatialPose.longitude,
  heading = cameraGeospatialPose.heading
)

Isso atualiza continuamente a posição do mapa usando os valores recebidos da API Geospatial.

Testar

No Android Studio, clique em Play. Segure o dispositivo e mova-o para ajudar o ARCore a estabelecer o rastreamento. Depois de um tempo, um marcador verde vai aparecer no mapa. Este marcador gira à medida que você visualiza os arredores. Ela também deve apontar na direção correta: quando você está fisicamente voltado para o Norte, a seta também aponta para o Norte.

4. Colocar uma âncora usando as coordenadas do Google Earth

A API Geospatial pode colocar âncoras em qualquer par de coordenadas e rotação no mundo real. Isso permite que seus usuários vejam conteúdo ancorado quando locais específicos forem visitados.

Nesta etapa, você vai adicionar uma maneira de colocar uma âncora tocando no mapa.

Definir uma ação quando o mapa for tocado

O projeto tem uma função onMapClick, que é chamada com latitude e longitude quando o fragmento de mapa é clicado. Encontre a função onMapClick em HelloGeoRenderer.kt.

Verificar se o objeto Earth pode ser usado

Antes de criar âncoras no Earth, verifique se o TrackingState do objeto Earth é TRACKING, o que significa que a posição da Terra é conhecida. Verifique também se o EarthState é ENABLED, o que significa que nenhum problema foi encontrado com a API Geospatial. Adicione estas linhas em onMapClick:

val earth = session?.earth ?: return
if (earth.trackingState != TrackingState.TRACKING) {
  return
}

Determinar o posicionamento da nova âncora

Depois de confirmar que o objeto da Terra está sendo rastreado, remova o earthAnchor anterior, se houver. Substitua earthAnchor por uma nova âncora nas próximas etapas:

earthAnchor?.detach()

Em seguida, use cameraGeospatialPose para determinar a altitude da nova âncora. Use o par de coordenadas tocando no mapa como posicionamento da âncora.

// Place the earth anchor at the same altitude as that of the camera to make it easier to view.
val altitude = earth.cameraGeospatialPose.altitude - 1
// The rotation quaternion of the anchor in the East-Up-South (EUS) coordinate system.
val qx = 0f
val qy = 0f
val qz = 0f
val qw = 1f
earthAnchor =
  earth.createAnchor(latLng.latitude, latLng.longitude, altitude, qx, qy, qz, qw)

createAnchor cria um Anchor fixo em coordenadas geodésicas com uma determinada rotação. Essa âncora tenta permanecer estável e fixa nas coordenadas e na altitude especificadas.

As variáveis [qx, qy, qz, qw] determinam a rotação da âncora expressa em quatérnios, no sistema de coordenadas Leste-Up-Sul (EUS, na sigla em inglês). Use valores diferentes para girar a âncora, mas, neste exemplo, use um quatérnio de unidade para a rotação padrão. Uma rotação de quatérnio unitário tem a âncora orientada de modo que X+ aponta para o leste, Y+ aponta para cima do centro da Terra e Z+ aponta para o sul.

Mostrar o marcador posicionado no mapa

Por fim, mova um novo marcador que indica onde ele foi colocado:

activity.view.mapView?.earthMarker?.apply {
  position = latLng
  isVisible = true
}

Testar

No Android Studio, clique em Play. Segure o dispositivo e mova-o para ajudar o ARCore a estabelecer o rastreamento. Depois de um tempo, um marcador verde vai aparecer no mapa indicando sua posição atual.

Ao tocar no mapa, a API Geospatial coloca uma âncora, que é fixada em um local real. Posicione a âncora perto do seu local atual para que ela apareça na visualização em RA. Ele precisa permanecer estável enquanto você navega pelo ambiente.

5. Conclusão

Neste codelab, você aprendeu a usar a API Geospatial para criar uma experiência de RA simples e vinculada ao mundo real.

O que aprendemos

• Como configurar um projeto do Google Cloud com a API Geospatial ativada.
• Como extrair informações geoespaciais em um projeto ARCore e exibi-las em um mapa.
• Como inserir uma âncora posicionada no mundo real usando o posicionamento geográfico.

Outros recursos

Para mais detalhes sobre os conceitos geográficos e SDKs usados neste codelab, consulte estes recursos adicionais:

• Documentação da API ARCore Geospatial
• Sistema Geodésico Mundial (WGS, na sigla em inglês)
• SDK do Google Maps para Android