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

1. Visão geral

O ARCore é o framework do Google para criar experiências de realidade aumentada em smartphones. A nova API ARCore Geospatial oferece um novo aspecto à realidade aumentada, permitindo que você coloque pontos de referência de realidade aumentada específicos de um 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ê 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 criar uma experiência simples de orientação por 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 mostrá-los usando o Google Maps.
• Como colocar uma âncora anexada a um local do mundo real.

O que é necessário

• Um dispositivo Android com suporte ao ARCore conectado com um cabo USB à sua máquina de desenvolvimento e configurado com depuração USB.
• O Android Studio instalado e configurado para criar 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 aborda os princípios básicos de um projeto do ARCore integrado com o SDK do Google Maps. Isso oferece um início rápido com 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....
   • Se a janela Welcome to Android Studio aparecer, 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 magnetômetro e do sensor da câmera do dispositivo para melhorar os valores de orientação. Para usar esse serviço, configure 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 do projeto adequado (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 seguida, Biblioteca.
   • Pesquise a API ARCore.
   • Clique em Ativar.
   • Volte para a Biblioteca.
   • Pesquise o SDK do Maps para Android.
   • Clique em Ativar.
3. Criar credenciais de 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 criada, porque ela será necessária na próxima etapa. Volte para a página Credenciais se precisar recuperá-la.

Com essas etapas, você criou um projeto do Google Cloud com autorização de chave de API e está pronto para usar a API Geospatial.

Integrar a chave de API com o 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 app > src > AndroidManifest.xml.
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 na nuvem 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ê vai ver uma imagem da câmera ao vivo e um mapa funcional na parte de baixo 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 extrair dados geoespaciais, ative a API Geospatial. Mude o 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 estiver 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. É quando 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 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 uma estimativa da precisão da elevação.
• Rumo, uma aproximação da direção para onde o dispositivo está apontando, e uma estimativa da precisão do rumo.

Mostrar informações de posicionamento no mapa

Use o GeospatialPose armazenado em 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. Esse marcador gira conforme você olha ao redor. Ele também precisa apontar na direção correta: quando você estiver de frente para o norte, a seta também vai apontar para o norte.

4. Colocar uma âncora usando coordenadas do Earth

A API Geospatial pode colocar âncoras em qualquer par de coordenadas e rotação no mundo real. Assim, os usuários podem ver conteúdo fixado quando visitam locais específicos.

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 vem com uma função onMapClick, que é chamada com uma latitude e uma longitude quando o fragmento de mapa é clicado. Encontre a função onMapClick em HelloGeoRenderer.kt.

Verifique se o objeto do Earth pode ser usado

Antes de criar âncoras na Terra, verifique se o TrackingState do objeto Terra é TRACKING, ou seja, se a posição da Terra é conhecida. Verifique também se o EarthState é ENABLED, o que significa que não houve problemas 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á rastreando, desvincule o earthAnchor anterior, se houver. Nas próximas etapas, você vai substituir o earthAnchor por uma nova âncora:

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 rotação específica. 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 quaternions no sistema de coordenadas East-Up-South (EUS). Você usa valores diferentes para girar a âncora, mas, neste exemplo, use um quaternion unitário para a rotação padrão. Uma rotação de quaternário unitário tem a âncora orientada de forma que X+ aponta para o leste, Y+ aponta para cima, longe 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 o marcador foi colocado:

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, um marcador verde vai aparecer no mapa indicando sua posição atual.

Ao tocar no mapa, a API Geospatial é usada para colocar uma âncora, que é fixada em um local do mundo real. Tente colocar a âncora perto da sua localização atual para que ela apareça na visualização de 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 simples de RA vinculada ao mundo real.

O que aprendemos

• Como configurar um projeto na nuvem do Google com a API Geospatial ativada.
• Como extrair informações geoespaciais em um projeto do ARCore e mostrá-las em um mapa.
• Como posicionar uma âncora 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 adicionais:

• Documentação da API ARCore Geospatial
• Sistema Geodésico Mundial (WGS)
• SDK do Maps para Android