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

1. Visão geral

O ARCore é o framework do Google para a criação de experiências de realidade aumentada em smartphones. A nova API ARCore Geospatial confere um novo aspecto à realidade aumentada, permitindo que você posicione waypoints de realidade aumentada específicos do local em torno 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ê descobrirá quais informações a API Geospatial pode oferecer para sua experiência geral de RA e como esses dados podem ser usados para proporcionar uma experiência simples de orientação em RA.

O que você vai aprender

• Como configurar um projeto do ARCore que usa a API Geospatial.
• Como solicitar dados geográficos da API Geospatial e exibi-los usando o Google Maps.
• Como posicionar uma âncora anexada a um local real.

O que é necessário

• Um dispositivo Android com suporte ao ARCore, conectado por um cabo USB à sua máquina de desenvolvimento e 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 o 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 ao SDK do Google Maps. Aqui você começa a usar a API Geospatial rapidamente.

1. Inicie o Android Studio e importe um projeto do VCS.
   • Se você já tiver um projeto aberto, use File > Novo > projeto de controle de versões...
   • 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 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.
     
   • Insira um Nome de projeto apropriado (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 em Biblioteca.
   • Pesquise pela API ARCore.
   • Clique em Ativar.
   • Volte para a Biblioteca.
   • Pesquise o SDK do Maps para Android.
   • Clique em Ativar.
3. Crie as 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 conforme necessário para a próxima etapa. Volte para a página Credenciais se precisar recuperá-las.

Depois de seguir essas etapas, você criou um projeto do Google Cloud com autorização de chave de API e está com tudo pronto para 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 criado no Android Studio e modifique as chaves de API:

1. Abra o app > src > AndroidManifest.xml (link em inglês)
2. Encontre as seguintes entradas de meta-data:

   <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ê terá acesso a uma visualização de câmera, junto com um mapa que funciona na parte inferior da tela.

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

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

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

Para receber os dados geoespaciais, você precisa ativar a API Geospatial. Altere 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
    }
  )
}

Com o modo geoespacial ENABLED, o aplicativo pode 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 caso, ela 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 fornece um GeospatialPose que contém estas informações:

• Localização, expressa em latitude e longitude. Uma estimativa da precisão da localização também é fornecida.
• Elevação e estimativa de precisão da elevação.
• Direção, uma aproximação da direção para onde o dispositivo está voltado 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 obtidos da API Geospatial.

Faça um teste

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 conforme você visualiza os arredores. Ela também deve apontar na direção correta: quando você estiver fisicamente virado para o Norte, a seta também apontará para o Norte.

4. Posicionar uma âncora usando as coordenadas da Terra

A API Geospatial coloca âncoras em qualquer par de coordenadas e rotação no mundo real. Assim, os usuários podem conferir conteúdo ancorado quando locais específicos são visitados.

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

Definir uma ação quando alguém tocar no mapa

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

Verificar se o objeto Earth pode ser usado

Antes de criar âncoras, verifique se o TrackingState do objeto Earth é TRACKING, o que significa que a posição da Terra é conhecida. Além disso, verifique 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 um. Substitua earthAnchor por uma nova âncora nas próximas etapas:

earthAnchor?.detach()

Em seguida, use o cameraGeospatialPose para determinar a altitude da nova âncora. Use o par de coordenadas do toque no mapa como o 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 fixada nas coordenadas e altitude especificadas.

As variáveis [qx, qy, qz, qw] determinam a rotação da âncora expressa em quatérnios no sistema de coordenadas Leste-para-Sul (EUS). Você usa 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 tal forma 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 indique onde ele foi posicionado:

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

Faça um teste

No Android Studio, clique em Play. Segure o dispositivo e mova-o para ajudar o ARCore a estabelecer o rastreamento. Depois de um tempo, você verá um marcador verde que indica sua posição atual no mapa.

Ao tocar no mapa, a API Geospatial é usada para posicionar uma âncora, que é fixada em um local real. Coloque 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 vinculada ao mundo real.

O que aprendemos

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

Outros recursos

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

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