Crie com o Geospatial Creator e a API Places da Plataforma Google Maps

1. Antes de começar

O Geospatial Creator no Unity, com tecnologia do ARCore e blocos fotorrealistas em 3D da Plataforma Google Maps, permite criar e visualizar rapidamente experiências de realidade aumentada (RA) para uma latitude e longitude específicas, tudo no editor do Unity. Isso pode reduzir muito o tempo necessário para criar uma única cena de RA geolocalizada para seu app. Mas e se você quiser criar várias experiências semelhantes em locais diferentes? Usando a API C# no Geospatial Creator, você também pode fazer isso.

Neste codelab, você vai escrever um código em C# que usa o Geospatial Creator e a API Places da Plataforma Google Maps para criar várias experiências geoespaciais usando um modelo inicial. As experiências resultantes podem ser exploradas e ajustadas no Unity Editor antes de serem compiladas em um app.

O livro está na altura correta

Pré-requisitos

O que você vai aprender

  • Como usar APIs no Geospatial Creator para criar e visualizar uma experiência geolocalizada em vários locais.
  • Como usar a API Places da Plataforma Google Maps para encontrar os locais.
  • Como executar a experiência de RA no seu dispositivo.

O que é necessário

2. Configurar o ambiente

Para usar o Geospatial Creator, você precisa configurar a autorização para acessar blocos fotorrealistas em 3D, serviços do ARCore no Google Cloud e a API Places da Plataforma Google Maps.

Configure um projeto do Google Cloud

Este codelab exige um projeto do Google Cloud com o faturamento ativado para acessar as APIs de servidor do Google. A configuração de faturamento é necessária para este codelab, mas você só vai receber uma cobrança se um projeto exceder a cota de serviços sem custo financeiro.

Para configurar um projeto no Google Cloud, siga estas etapas:

  1. Crie um projeto no console do Google Cloud.Criar um projeto do Google Cloud
  2. Na caixa de texto Nome do projeto, digite um nome adequado, como ARCore Geospatial 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. Consulte Ativar o faturamento e confira os preços dos 3D Tiles fotorrealistas e da API Places (nova).

Ativar a API Map Tiles

A API Map Tiles oferece os blocos 3D fotorrealistas, que ficam visíveis no editor do Unity.

Ativar a API ARCore

A API ARCore no Google Cloud permite acessar a API ARCore Geospatial no dispositivo de destino.

  • Para habilitar a API ARCore, clique no botão a seguir e depois em Ativar:

Ativar a API Places

A API Places da Plataforma Google Maps permite receber dados de localização de mais de 200 milhões de lugares, que você vai usar no codelab para encontrar lugares relacionados. Essa API fornece resultados de pesquisa e coordenadas geográficas de lugares.

Criar uma chave de API para o projeto

Para usar a autenticação por chave de API e autenticar seu app com os serviços remotos do Google Cloud, siga estas etapas:

  1. No console do Google Cloud, em APIs e serviços, selecione Credenciais.
  2. Na parte de cima da página, clique em Criar credenciais e selecione Chave de API.
  3. Anote essa chave, porque você vai precisar dela para as próximas etapas.

Configurar o software

Para começar a usar o software Geospatial Creator, siga estas etapas:

  1. Clone este repositório.
  2. Faça o download do Unity Hub e use-o para instalar a versão 2022.3 do Unity. Confira se você está instalando as ferramentas de build opcionais para Android ou iOS.
  3. No Unity Hub, pressione Adicionar > Adicionar projeto do disco.
  4. No painel Hierarchy, selecione AR Geospatial Creator Origin.
  5. Na caixa de texto Chave de API de bloco do Google Maps, insira a chave de API e pressione Enter (ou return no macOS).Insira sua chave de API na origem do Geospatial Creator
  6. Em Edit > Project Settings > XR Plug-in Management > ARCore Extensions, use a autenticação de chave de API para Android ou iOS e insira a chave de API.
  7. Em File > Build Settings, mude a plataforma de destino para Android ou iOS.

3. Criar sua primeira âncora

Neste codelab, você vai criar uma âncora de RA que pode ser usada em vários locais. Você usa bibliotecas públicas em São Francisco, Califórnia, como exemplo, mas pode usar locais perto de você.

Sobre o componente de origem do Geospatial Creator

Cada cena do Unity criada com o Geospatial Creator exige exatamente uma origem do Geospatial Creator. Esse objeto de jogo é o ponto de referência para converter valores de latitude, longitude e altitude do mundo real em coordenadas de jogo do Unity.

O projeto de exemplo contém uma origem do Geospatial Creator, que usa o Cesium para renderizar blocos 3D fotorrealistas na visualização Scene do Editor e permite visualizar exatamente onde no mundo seu conteúdo de RA vai aparecer.

Mover a origem

Mova a origem do Geospatial Creator para a latitude e longitude da filial principal da biblioteca de São Francisco.

Para usar a integração integrada do Geospatial Creator com a API Places e realocar automaticamente a origem para o local correto, siga estas etapas:

  1. No painel Hierarchy, selecione o objeto de jogo Geospatial Creator Origin.
  2. No painel Inspetor, clique em Pesquisar local.
  3. Na caixa de diálogo de pesquisa, digite San Francisco Public Library. O primeiro resultado deve ser na Rua Larkin, 100.
  4. Clique em Aplicar aos objetos para aplicar o resultado da pesquisa à origem. A latitude e a longitude da origem serão atualizadas para as novas coordenadas.

O edifício está visível

Adicionar uma âncora do Geospatial Creator à cena

Agora que uma origem existe, adicione uma âncora do Geospatial Creator usando GameObject > XR > AR Geospatial Creator Anchor. Por padrão, a âncora fica no mesmo local que a origem.

Use essa âncora para posicionar nosso conteúdo de RA em 3D. Um modelo 3D de um livro está incluído no projeto de exemplo.

Para colocar o livro na cena, siga estas etapas:

  1. No painel Project, arraste o modelo Book para o painel de visualização Editor.
  2. No painel Hierarchy, verifique se o Book é um filho da âncora criada anteriormente. Qualquer objeto de jogo filho da âncora do Geospatial Creator será posicionado em relação a ela.
  3. No painel Hierarchy, selecione o Book. Defina os valores de posição como 0, 0, 0.

O livro é adicionado à cena

Ao analisar esse modelo na visualização do editor, fica claro que algo está errado: a altitude padrão da âncora está abaixo da superfície do telhado da biblioteca, quando deveria estar muito acima dela.

Embora seja possível mover o objeto no editor para encontrar a altitude aproximada do WGS84, é preferível configurar as âncoras geoespaciais como uma âncora de telhado nessa situação para que a altitude seja corrigida automaticamente em relação ao telhado da estrutura em que elas estão.

  • Para fazer isso, abra o painel do inspetor da âncora e defina a propriedade Altitude Type como Rooftop.

O painel do inspetor

Depois disso, observe que a altitude da âncora não muda na visualização do editor. Isso ocorre porque a altitude da âncora é determinada no tempo de execução quando ela é resolvida para âncoras de telhado e terreno. Para visualizar a âncora no telhado na visualização Scene, use o botão Ajustar ao bloco. Isso define a altitude da âncora para corresponder ao bloco na visualização Scene, sem afetar a altitude da âncora resolvida durante a execução.

  • Para que o modelo flutue acima do telhado da biblioteca em vez de ficar apoiado nele, mude o parâmetro Altitude relative to rooftop para 15 metros acima do telhado.

O modelo agora está flutuando sobre a biblioteca.

O livro está na altura correta

Seu projeto agora tem uma cena completa de RA geoespacial, incluindo todos os componentes necessários do sistema de RA, uma origem do Geospatial Creator e uma âncora com um modelo anexado.

Em seguida, crie âncoras duplicadas em outros locais da biblioteca.

4. Encontrar novos locais de ancoragem com a API Places

Com a API Places da Plataforma Google Maps, você pode receber dados de localização de mais de 200 milhões de lugares. Neste codelab, você vai usar essa API para encontrar outras filiais de bibliotecas públicas em São Francisco e usar esses resultados para gerar uma âncora do Geospatial Creator para os próximos dez resultados da pesquisa.

  • Para começar, clique em Recursos > Scripts > Editor e abra o arquivo AnchorDuplicator.cs. Esse arquivo fornece um código clichê que ajuda você a começar a usar a API Places e analisar os resultados dela.

Autenticar com a API Places

  1. Localize a seguinte linha na classe AnchorDuplicator:
    private const string API_KEY = "<YOUR_API_KEY_HERE>";
  2. Substitua <YOUR_API_KEY_HERE> pela chave obtida nas etapas de configuração.

Consultar a API Places para um termo de pesquisa

Com a configuração de autorização da API Places concluída, você pode escrever um código que inicia uma solicitação POST.

  • Para fazer isso, encontre o método CreatePlacesRequest e use a seguinte definição:
    string postBody = "{ \"textQuery\": \"" + searchTerm + "\", " + 
                    "   \"locationBias\": { \"circle\": { " +
                    "      \"center\": { \"latitude\": " + lat + ", \"longitude\": " + lon + " }, " +
                    "      \"radius\": 10000 }" +
                    "   }" +
                    "}";

string url = "https://places.googleapis.com/v1/places:searchText";

UnityWebRequest request = UnityWebRequest.Post(url, postBody, "application/json");
request.SetRequestHeader("X-Goog-Api-Key", apiKey);
request.SetRequestHeader("X-Goog-FieldMask", "places.displayName,places.location");

return request;
    Agora, quando o método CreatePlacesRequest é chamado, uma solicitação é feita para pesquisar searchTerm em um círculo centralizado em lat e lon.

Testar seu trabalho

Antes de continuar, verifique se as chamadas para a API Places foram feitas.

  1. Execute as funções no Unity Editor:
    1. No Codelab de RA do Google, clique em Executar solicitação de lugares.
    2. Abra o console do Unity. Os resultados vão aparecer.Os lugares aparecem no console

5. Adicionar âncoras a lugares de maneira programática

Agora que você verificou que a API Places encontra resultados, crie novas âncoras do Geospatial Creator em cada local especificado pelos resultados.

Criar um item de menu

  1. Na classe AnchorDuplicator, encontre o método CreateNewAnchorsFromPlaces e use a seguinte definição de método:
    if (_places == null)
{
    Debug.LogError("Cannot create anchors: Places has not been initialized.");
    return;
}

// You start with only one anchor in the scene, which you want to copy:
var prototypeAnchorObject = GameObject
    .FindObjectOfType<ARGeospatialCreatorAnchor>()
    .gameObject;

foreach (var place in _places)
{
    var newAnchorObject = GameObject.Instantiate(prototypeAnchorObject);
    var anchor = newAnchorObject.GetComponent<ARGeospatialCreatorAnchor>();
    anchor.Latitude = place.location.latitude;
    anchor.Longitude = place.location.longitude;

    newAnchorObject.name = place.displayName.text;
}
    Esse item de menu verifica uma solicitação iniciada anteriormente e usa o primeiro ARGeospatialCreatorAnchor na sua cena como um protótipo para criar âncoras, uma por lugar no resultado da API Places.
  2. Use o novo item de menu Criar novas âncoras da resposta de lugares no Codelab do Google AR para criar as âncoras.
  3. Várias âncoras vão aparecer no painel Hierarquia.

Verificar as posições das âncoras

Para verificar se todos os recursos estão ancorados nos locais corretos antes de executar o app, siga estas etapas:

  1. Clique em uma âncora adicionada no painel Hierarquia.
  2. Pressione F.
  3. Inspecione a âncora na visualização Scene.
  4. Se uma âncora não estiver no local correto, clique em Ajustar ao bloco ou mude manualmente os valores Latitude, Longitude ou Editor Override Altitude.

6. Conferir o recurso em RA

Para ver o recurso em RA no seu dispositivo Android ou iOS com suporte a ARCore, siga estas etapas:

  1. Clique em File > Build Settings e selecione as plataformas de criação Android ou iOS.
  2. Clique em Alternar plataforma.
  3. Verifique se o dispositivo de desenvolvimento está conectado e configurado para desenvolvimento.
  4. Clique em Build and run.
  5. Confirme se o app funciona no seu dispositivo.
  6. Acesse os locais em que você fixou o conteúdo. Se você não mudou os exemplos, os locais são bibliotecas públicas em São Francisco.

Conferir a experiência de RA

7. Conclusão

Parabéns! Você escreveu um app Unity que usa o Geospatial Creator e a API Places da Plataforma Google Maps para criar várias experiências geoespaciais usando um modelo inicial. Esperamos que você use esse conhecimento para aumentar o alcance do seu conteúdo do Geospatial Creator.

Saiba mais