Com o ARCore Geospatial Creator para Unity, é possível visualizar conteúdo geoespacial no editor do Unity mostrando dados do Google Maps em um novo formato de blocos 3D. Isso ajuda a visualizar onde o conteúdo será colocado no mundo real enquanto você cria o app.
O Geospatial Creator está disponível como parte das extensões do ARCore para AR Foundation. Neste guia de início rápido, você vai aprender a usar o Geospatial Creator no Unity para adicionar conteúdo de RA geoespacial ao app de exemplo geoespacial do ARCore.
Se você tiver um app que gostaria de usar em vez da amostra geoespacial, siga o guia para desenvolvedores geoespaciais do Unity. Depois que o app estiver configurado para uso da API Geospatial, pule para a etapa Adicionar dependências necessárias abaixo e continue de lá.
Pré-requisitos
Siga "Primeiros passos com as extensões do ARCore para AR Foundation" para configurar seu ambiente Unity e criar experiências de RA.
Embora as extensões do ARCore sejam compatíveis com versões anteriores do Unity, o Geospatial Creator exige o Unity 2021.3 ou mais recente.
Autorização da API
É necessário configurar o acesso à API para usar a API ARCore Geospatial e a API Google Map Tiles.
API Google Map Tiles
A API Map Tiles oferece uma representação 3D fotorrealista de locais compatíveis. Vamos usar esses blocos no Unity Editor para visualizar a área ao redor da sua cena de RA.
Consulte a página da API Map Tiles para ativar a API e saber mais sobre Map Tiles.
API ARCore Geospatial
A API ARCore Geospatial é usada pelo app durante a execução para criar e interagir com âncoras geoespaciais.
Para ativar as APIs Geospatial, configure a API ARCore no seu aplicativo. Use os métodos de autorização sem chave (recomendado) ou com chave de API.
Estender o app de exemplo geoespacial
Neste guia, vamos mostrar como usar o Geospatial Creator para adicionar conteúdo geoespacial ao app de exemplo geoespacial do ARCore.
Configurar a amostra geoespacial
Primeiro, conheça o app de exemplo do ARCore Geospatial. Em um novo projeto do Unity, abra o Unity Package Manager e selecione o pacote ARCore Extensions. No painel de detalhes do Package Manager, expanda Samples e importe o exemplo geoespacial para seu projeto do Unity.
Antes de executar o app, ative a funcionalidade do ARCore e da API Geospatial no seu projeto. Use Editar > Configurações do projeto... > XR Plug-in Management. Marque as caixas adequadas para ativar o provedor de plug-in do ARCore para Android e/ou o provedor de plug-in do ARKit para iOS.
Em seguida, em Editar > Configurações do projeto... > XR Plug-in Management, abra o painel ARCore Extensions. Verifique se a opção "Geospatial" está marcada (ainda não é necessário ativar o Geospatial Creator) e insira suas credenciais de API. Consulte a documentação "Ativar a API Geospatial Unity" para Android e iOS para mais detalhes.
Há algumas outras configurações do Player específicas da plataforma que são necessárias para qualquer app Unity que use o ARCore. Consulte a seção Configurar definições do player dos nossos documentos para ver as mudanças necessárias.
Neste ponto, não há objetos de jogo na cena além do que é necessário para executar a amostra geoespacial. Este é um bom momento para criar e executar o app. Se configurado corretamente, no tempo de execução, o app vai mostrar a visualização da câmera do dispositivo. À medida que você se move, a precisão geoespacial mostrada na parte de cima da tela começa a melhorar. Ao tocar na tela, você cria âncoras geoespaciais que permanecem no local original enquanto você se move.
Em seguida, vamos mostrar como usar o Geospatial Creator para criar e visualizar conteúdo sofisticado de RA no Unity Editor. Esse conteúdo vai aparecer no seu app em locais específicos de latitude / longitude no mundo.
Adicionar as dependências necessárias
O Geospatial Creator usa um pacote do Unity de terceiros chamado Cesium para renderizar blocos do Google Maps na janela de cena do Unity Editor. Antes de ativar os recursos do Geospatial Creator, vamos adicionar o pacote do Cesium ao seu projeto.
Recomendamos instalar a versão mais recente do pacote Cesium para Unity na página do GitHub do Cesium:
- Faça o download da versão mais recente do
.tgzpré-compilado do Cesium para Unity na página de versões do GitHub deles (link em inglês). A versão recomendada atual do pacote Cesium para Unity é a 1.1.0. - Abra o Unity Package Manager clicando no menu "Window" do Unity e selecionando "Package Manager".
- Clique no ícone "+" e escolha "Adicionar pacote do tarball".
- Selecione o arquivo .tgz do Cesium para Unity baixado na etapa 1.
- Talvez seja necessário instalar outras dependências, como o Text Mesh Pro.
Ativar o Geospatial Creator
Agora você pode ativar o Geospatial Creator:
- Na caixa de diálogo "Configurações de build", verifique se a plataforma selecionada é "Android" ou "iOS". No momento, os recursos do Geospatial Creator não estão disponíveis para outras plataformas.
- Navegue até Configurações do projeto > Gerenciamento de plug-ins de XR > Extensões do ARCore.
- Se você não definiu as chaves de API do ARCore para Android e/ou iOS em uma etapa anterior, faça isso agora.
- Ative as opções "Geospatial" e "Geospatial Creator". Depois de clicar para ativar a opção "Criador geoespacial", um assistente não modal vai aparecer para confirmar se o projeto é compatível com o Criador geoespacial.
- Clique em "Concluir" no assistente.
Depois de concluir o assistente, o Unity vai acionar uma compilação dos seus scripts. Aguarde a conclusão da recompilação antes de continuar. Se a plataforma selecionada não for "Android" ou "iOS", mude para uma delas agora.
Adicionar uma origem do Geospatial Creator com blocos de mapa
Sua cena precisa ter exatamente um objeto "Origem do criador geoespacial". Esse objeto é usado como ponto de referência para converter valores de latitude, longitude e altitude do mundo real em coordenadas de jogos do Unity.
Para adicionar uma origem do Geospatial Creator à sua cena, selecione Objeto de jogo > XR > Origem do Geospatial Creator. O objeto recém-criado exige uma georreferência, que vincula uma latitude, longitude e altitude específicas à posição da origem em coordenadas do jogo. No painel Inspector da origem do Geospatial Creator, adicione uma georreferência clicando no botão Add Cesium Georeference Component.
Além de ser o ponto de referência para seus objetos de RA, a georreferência do Cesium adiciona um objeto de conjunto de blocos 3D do Cesium à cena. Esse objeto vai renderizar blocos do Google Maps na visualização de cena do editor, permitindo que você visualize exatamente onde no mundo seu conteúdo de RA vai aparecer. Há um campo no inspetor da origem do Geospatial Creator para adicionar a chave de API de blocos de mapa que você configurou antes. Depois de definir essa chave, os blocos do mapa vão ser carregados na visualização de cena.
Agora mude os campos de latitude, longitude e altura para que fiquem perto de onde você quer que o conteúdo de RA apareça no app.
A visualização de cena no editor agora vai mostrar os blocos de mapa na latitude e longitude especificadas da sua origem. No tempo de execução, presumimos que seu app vai usar a câmera de RA. Por isso, o Geospatial Creator já configurou o objeto "Tileset" do mapa 3D do Cesium com a tag "EditorOnly". Por isso, os blocos não serão baixados nem renderizados no tempo de execução do jogo. Isso pode ser mudado no inspetor do objeto Cesium3DTileset. Para saber mais sobre a georreferência do Cesium e os GameObjects de conjuntos de blocos 3D, consulte a documentação do Cesium para Unity.
Adicionar e posicionar uma âncora do Geospatial Creator
Agora você pode colocar conteúdo de RA na sua cena. Clique em GameObject > XR > Geospatial Creator Anchor para adicionar uma âncora à hierarquia da cena. No inspetor de âncora, é possível especificar uma latitude, longitude e altura exatas. A transformação do objeto será atualizada imediatamente para a posição correta na cena, e você poderá ver exatamente onde no mundo o objeto vai aparecer.
Ao ajustar a latitude e a longitude da âncora, escolha um lugar próximo para poder validar se ela está no local correto durante a execução. Ao definir a altitude de uma âncora do Geospatial Creator, você tem três opções:
- Terreno coloca a âncora no nível do solo na latitude e longitude especificadas. O nível do solo é determinado no tempo de execução pelo Sistema de posicionamento visual (VPS, na sigla em inglês). Se você não conhece as APIs geoespaciais do ARCore, "Terreno" é uma boa opção, porque a âncora será resolvida diretamente no chão com um alto grau de precisão vertical. O campo "Deslocamento de altitude" permite posicionar a âncora acima ou abaixo do nível do solo por um valor fixo, em metros. Por exemplo, especificar um deslocamento de "1.0" faz com que a âncora "flutue" um metro acima do terreno.
- Telhado posiciona a âncora em relação à parte de cima de qualquer estrutura na latitude e longitude especificadas. Assim como a âncora de terreno, o campo "Deslocamento de altitude" permite mover a âncora para cima ou para baixo em relação à posição do telhado, em metros.
- O WGS84 coloca a âncora em uma altitude absoluta específica, em metros, com base no sistema de coordenadas WGS84. Colocar o objeto dessa forma pode exigir algumas tentativas e erros, já que uma altura de "0" no WSG84 não indica necessariamente o nível médio do mar e pode não corresponder à altitude de um GPS. Além disso, embora a latitude e a longitude dos blocos 3D renderizados sejam altamente precisas, tentar colocar o objeto no nível do solo usando os blocos 3D como referência pode resultar em um erro de altura de até vários metros.
Para saber mais sobre os diferentes tipos de âncoras geoespaciais do ARCore, consulte o Guia para desenvolvedores de recursos geoespaciais.
As âncoras de terreno e de telhado têm um campo Altitude WGS84. Esse valor é usado apenas no modo de edição para definir a altura do objeto na visualização da cena. As alturas do terreno e do telhado são determinadas apenas no tempo de execução. Assim, o campo Altitude WGS84 permite visualizar a âncora em uma altura específica durante o desenvolvimento do app. O campo Altitude WGS84 é ignorado no tempo de execução para âncoras de terreno e telhado.
Adicionar geometria à âncora
Se você criar e executar o app agora, não vai ver a âncora no app compatível com AR, porque não há geometria anexada a ela. Vamos adicionar uma primitiva 3D simples à âncora: na hierarquia de cenas, clique com o botão direito do mouse no objeto de âncora do AR Geospatial Creator. No menu de contexto, escolha Objeto 3D > Cubo. Você vai ver um cubo cinza na visualização da cena como filho da âncora. Se você decidir mover a posição ou a rotação do objeto no editor, recomendamos mover o objeto de âncora raiz em vez da primitiva de cubo filho. Isso ajuda a reduzir o erro na tradução de latitude / longitude para coordenadas do jogo.
É claro que você também pode adicionar geometria mais complicada e componentes e filhos arbitrários à âncora.
Criar e executar o app
É hora de ver sua âncora no mundo real! Tente criar e executar o app e vá até o local onde você espera ver o cubo. Está lá? Parabéns! Agora você pode criar experiências de RA mais complexas com o Geospatial Creator.
Se você tiver algum problema, consulte o guia de solução de problemas.
Agora é um ótimo momento para adicionar mais âncoras do AR Geospatial Creator com geometrias diferentes. Teste várias âncoras de telhado e terreno e seus deslocamentos. Adicione scripts para animar ou ativar interações com os objetos.
Noções básicas sobre âncoras do Geospatial Creator e a classe ARGeospatialAnchor
Ao criar experiências de RA complexas e interativas, é útil entender a relação entre as âncoras do Geospatial Creator e a classe ARGeospatialAnchor C# do ARCore:
Um
ARGeospatialAnchor
só pode ser criado no tempo de execução invocando uma das funções em
ARAnchorManager,
e isso só pode ser feito depois que a sessão de RA for estabilizada. Uma âncora do Geospatial Creator pode ser considerada um marcador de posição que existe na sua cena, aguardando que a sessão de RA esteja pronta para resolver objetos ARGeospatialAnchor.
Quando a sessão estiver pronta, o marcador de posição vai chamar automaticamente o
ARAnchorManager para criar e resolver o ARGeospatialAnchor.
Imediatamente após a resolução da âncora de tempo de execução, a âncora do Geospatial Creator na hierarquia de cena se anexará como um filho ao novo GameObject.
Isso significa que qualquer componente ou filho da âncora do Geospatial Creator vai
se tornar um subcomponente ou neto do novo GameObject ARGeospatialAnchor. Por exemplo, o transform de uma primitiva de geometria anexada à âncora do Geospatial Creator vai herdar o transform do ARGeospatialAnchor e, portanto, será colocado no local esperado na sessão de AR de tempo de execução.
Se você precisar identificar GameObjects ARGeospatialAnchor específicos durante a execução,
pesquise na cena objetos cuja propriedade name corresponda à âncora
criada com o Geospatial Creator. Se a sessão de RA for inicializada, o
parent desse objeto será o objeto ARGeospatialAnchor correspondente.
Solução de problemas
Por que minha âncora está se movendo?
Você pode notar, principalmente quando o app é iniciado pela primeira vez, que a âncora parece "derivar" lentamente ou até mesmo pular vários metros de repente. Isso ocorre quando
a sessão do VPS ainda está determinando e refinando o local exato da
câmera. À medida que a acurácia horizontal e vertical melhora em vários frames, a âncora é redesenhada em um local mais preciso, a ilusão de movimento. Talvez você queira renderizar o objeto de maneira diferente (ou não renderizar) até que a precisão do local atinja um determinado limite. Para isso, consulte a propriedade
ARCoreEarthManager.CameraGeospatialPose
para determinar a precisão da atualização do frame atual.
Por que minha âncora aparece na altitude errada?
Ao usar o tipo de altitude "Manual" para âncoras do Geospatial Creator, a altitude da âncora será definida (em metros) de acordo com o WGS84. Em um determinado local, pode haver uma discrepância de até vários metros entre o nível do solo aparente mostrado nos blocos do mapa e o nível real do solo, conforme informado pelo Sistema de posicionamento visual (VPS) do Google. Se uma âncora geoespacial parecer estar localizada incorretamente no tempo de execução, recomendamos validar a altura do VPS pessoalmente usando a sobreposição de depuração no app de exemplo. Em seguida, você pode mudar a altitude no Unity Editor para corresponder à altura conhecida do VPS naquele local.
Os blocos do mapa não estão sendo renderizados corretamente na visualização de cena do editor
Se o Cesium3DTileset parecer estar carregando blocos, mas eles forem renderizados em magenta sólido na visualização da cena, adicione o pacote Shader Graph do Unity ao projeto. Esse pacote é exigido pelo Cesium, mas os projetos que usam o renderizador
integrado do Unity não o incluem por padrão.
Para adicionar o Shader Graph, abra o Unity Package Manager (Window > Package
Manager). Para navegar pelos pacotes disponíveis no Unity Package Registry, selecione "Packages: Unity Registry" no menu suspenso na parte de cima da janela do Package Manager. Pesquise o pacote com.unity.shadergraph e instale a versão mais recente. Quando o pacote for carregado, os blocos 3D serão recarregados e renderizados corretamente na visualização de cena.
O app mostra uma tela preta durante a execução em vez da visualização da câmera
O Pipeline de Renderização Universal (URP) do Unity não está configurado para a câmera de RA por padrão. Se você estiver vendo uma tela preta em tempo de execução em vez da saída da câmera, adicione o AR Background Renderer Feature a cada renderizador URP na sua cena.
Para adicionar o recurso, pesquise "renderer" no seu projeto. Para cada objeto URP Renderer, clique no botão "Add Renderer Feature" no Inspector e adicione o AR Background Renderer.
Por que as âncoras colocadas longe da origem parecem estar posicionadas incorretamente?
A conversão de coordenadas WGS84 para coordenadas do jogo Unity está sujeita a erros devido à precisão da aritmética de ponto flutuante, que pode ser minimizada garantindo que sua origem esteja próxima às âncoras de RA. Distâncias acima de 20 km podem levar a imprecisões. Recomendamos usar várias cenas, com uma âncora exclusiva em cada uma, se a experiência de RA abranger longas distâncias.