O ARCore Geospatial Creator para Unity permite visualizar o conteúdo Geospatial 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 ARCore para AR Foundation. Neste guia de início rápido, mostraremos como usar o Geospatial Creator no Unity para adicionar conteúdo de RA geoespacial ao app de amostra ARCore Geospatial.
Se você tiver um app que gostaria de usar em vez do exemplo Geoespacial, primeiro siga nosso Guia do desenvolvedor geoespacial para Unity. Depois que o app estiver configurado para uso da API Geospatial, pule para a etapa Adicionar dependências necessárias abaixo e continue.
Pré-requisitos
Consulte Introdução ao ARCore Extensions para AR Foundation para configurar seu ambiente do 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 requer o Unity 2021.3 ou uma versão mais recente.
Autorização da API
Você precisará 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 fotorrealista em 3D dos locais aceitos. Vamos usar esses blocos no Editor do Unity 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 blocos de mapas.
API ARCore Geospatial
A API ARCore Geospatial é usada pelo app no momento da execução para criar e interagir com âncoras geoespaciais.
Para ativar as APIs Geospatial, configure a API ARCore no seu aplicativo. É possível usar os métodos de autorização sem chave (recomendado) ou de chave de API.
Estender o app de exemplo Geospatial
Neste guia, mostraremos como usar o Geospatial Creator para adicionar conteúdo geoespacial ao app de amostra ARCore Geospatial.
Configurar o exemplo Geospatial
Primeiro, familiarize-se com o app de exemplo 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, abra Samples e importe o Geospatial Sample para seu projeto do Unity.
Antes de executar o app, é necessário ativar as funcionalidades ARCore e Geospatial no seu projeto. Use Edit > Project Settings... > Gerenciamento de plug-in XR. Marque as caixas apropriadas para ativar o provedor de plug-in do ARCore para Android e/ou do provedor de plug-ins do ARKit para iOS.
Em seguida, em Edit > Project Settings... > 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. Confira mais detalhes na documentação "Ativar a API Geospatial Unity" para Android e iOS.
Existem algumas outras configurações do player específicas da plataforma que são necessárias para qualquer app do Unity que use o ARCore. Consulte a seção Definir configurações do jogador para conferir as mudanças necessárias.
Neste ponto, não há objetos de jogo na sua cena além do que é necessário para executar o exemplo Geospatial. Esse é um bom momento para criar e executar o app. Se configurado corretamente, o app vai mostrar a visualização da câmera do dispositivo durante a execução. Conforme você se move, a precisão geoespacial exibida 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 movimenta.
A seguir, mostraremos como usar o Geospatial Creator para criar e visualizar conteúdos de RA sofisticados no Editor do Unity. Esse conteúdo vai aparecer no seu app em locais específicos de latitude / longitude do mundo.
Adicionar as dependências necessárias
O Geospatial Creator usa um pacote de terceiros do Unity, chamado Cesium, para renderizar blocos de mapas do Google Maps na janela Scene do editor do Unity. Antes de ativar os recursos do Geospatial Creator, vamos adicionar o pacote 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 (link em inglês). A versão atual recomendada 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 que você baixou na etapa 1.
- Pode ser solicitado que você instale outras dependências, como Text Mesh Pro.
Ativar o Geospatial Creator
Agora você já pode ativar o Geospatial Creator:
- Na caixa de diálogo "Build Settings", 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é Project Settings > XR Plug-in Management > ARCore Extensions.
- Se você não configurou suas chaves de API do ARCore 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 de ativar ou desativar o Geospatial Creator, um assistente não modal será exibido para confirmar que seu projeto é compatível com o Geospatial Creator.
- Clique em "Concluir" no assistente.
Depois de concluir o assistente, o Unity 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 mapas
Seu cenário precisa de exatamente um objeto "Geospatial Creator Origin". Esse objeto é usado como o ponto de referência para converter valores reais de latitude, longitude e altitude em coordenadas de jogos do Unity.
Para adicionar uma origem do Geospatial Creator ao seu cenário, selecione Game Object > XR > Geospatial Creator Origin. O objeto recém-criado requer uma referência geográfica, que vincula uma latitude, longitude e altitude específicas à posição da origem nas coordenadas do jogo. No painel Inspector do Geospatial Creator Origin, adicione uma referência geográfica clicando no botão Add Cesium Georeference Component.
Além de ser o ponto de referência para seus objetos de RA, a Georeferência do Cesium adiciona um objeto Cesium 3D Tileset à cena. Esse objeto renderiza blocos de mapas do Google Maps na visualização de cena do editor, permitindo que você veja exatamente em que lugar do mundo seu conteúdo de RA vai aparecer. Há um campo no inspetor do Geospatial Creator Origin para adicionar a chave de API Map Tiles que você configurou anteriormente. Depois de definir essa tecla, os blocos do mapa são carregados na visualização Scene.
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 seu app.
A visualização de cena no Editor agora mostra os blocos de mapa na latitude e longitude especificadas da origem. No tempo de execução, presumimos que seu app vai usar a câmera de RA, então o Geospatial Creator já configurou o objeto Cesium 3D Map Tileset com a tag "EditorOnly". Por isso, os blocos não serão transferidos nem renderizados no momento da execução do jogo. Isso pode ser mudado no inspetor do objeto Cesium3DTileset. Para saber mais sobre a Georeference e os GameObjects 3D Tileset do Cesium, consulte a documentação do Cesium para Unity (link em inglês).
Adicionar e posicionar uma âncora do Geospatial Creator
Agora está tudo pronto para você colocar conteúdo de RA na sua cena. Clique em GameObject > XR > Geospatial Creator Anchor para adicionar uma âncora à hierarquia de cenas. No Inspetor da âncora, é possível especificar a 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 em que lugar do mundo o objeto vai aparecer.
Ao ajustar a latitude e a longitude da âncora, escolha um lugar próximo para validar se ela está no lugar certo 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 durante a execução pelo Sistema de Posicionamento Visual. Se você não conhece as APIs Geospatial do ARCore, "Terreno" é uma boa escolha, porque a âncora será resolvida diretamente no chão com um alto grau de precisão vertical. O campo "Altitude Offset" permite posicionar a âncora acima ou abaixo do nível do solo por um valor fixo, em metros. Por exemplo, a especificação de um deslocamento de "1.0" faz com que a âncora "flutua" um metro acima do terreno.
- Rooftop coloca a âncora em relação ao topo de qualquer estrutura na latitude e longitude indicadas. Assim como a âncora de terreno, o campo "Altitude Offset" permite mover a âncora para cima ou para baixo em relação à posição do teto, em metros.
- O WGS84 coloca a âncora em uma altitude absoluta específica, em metros, com base no sistema de coordenadas WGS84. Posicionar 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 do GPS. Além disso, embora a latitude e a longitude dos blocos 3D renderizados sejam altamente precisas, tentar posicionar 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 geoespaciais.
As âncoras de terreno e telhado têm um campo WGS84 Altitude. Esse valor é usado apenas no modo Editor para definir a altura do objeto na visualização de cena. As alturas do terreno e do telhado são determinadas apenas no tempo de execução. O campo WGS84 Altitude permite visualizar a âncora a uma altura específica durante o desenvolvimento do app. O campo WGS84 Altitude é ignorado no tempo de execução para Âncoras de terreno e telhado.
Adicionar geometria à âncora
Se você criar e executar o app agora, a âncora não vai aparecer no app com RA. Isso ocorre porque não há geometria anexada a ele. Vamos adicionar um primitivo 3D simples à âncora: na hierarquia da cena, clique com o botão direito do mouse no seu objeto Âncora do Geospatial Creator em RA. No menu de contexto, escolha 3D Object > Cube. Você verá um cubo cinza na visualização de cena como filho da âncora. Se você decidir mover a posição ou a rotação do objeto no Editor, recomendamos mover o objeto Anchor raiz em vez do primitivo Cubo filho. Isso ajuda a reduzir erros na conversão de latitude / longitude para coordenadas do jogo.
Também é possível adicionar geometrias mais complicadas, componentes e filhos arbitrários à âncora.
Criar e executar o app
Chegou a hora de ver sua âncora no mundo real! Tente criar e executar seu app e, em seguida, vá para o local em que você espera ver o cubo. Está lá? Parabéns! Você já pode criar experiências de RA mais complexas com o Geospatial Creator.
Se tiver algum problema, consulte o Guia de solução de problemas.
Agora é um ótimo momento para adicionar outras âncoras do AR Geospatial Creator com diferentes geometrias. Tente testar várias âncoras de telhado e de terreno e os deslocamentos delas. Adicione scripts para animar ou ativar interações com os objetos.
Noções básicas sobre as â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
C# ARGeospatialAnchor do ARCore:
Um
ARGeospatialAnchor
só pode ser criado durante a execução invocando uma das funções em
ARAnchorManager
e só pode ser criado depois que a sessão de RA estiver estabilizada. Uma âncora do criador
geoespacial pode ser considerada um marcador de posição que existe na sua cena,
aguardando a sessão de RA ficar pronta para resolver objetos ARGeospatialAnchor.
Quando a sessão estiver pronta, o marcador vai chamar automaticamente
ARAnchorManager para criar e resolver a ARGeospatialAnchor.
Imediatamente após a âncora do ambiente de execução ser resolvida, a âncora do Geospatial Creator
na sua hierarquia de cenas será anexada ao novo GameObject como filha.
Isso significa que qualquer componente ou filho da âncora do Geospatial Creator se tornará
subcomponente ou neto do novo GameObject ARGeospatialAnchor. Por exemplo, o transform de um primitivo de geometria anexado à
Âncora do Geospatial Creator vai herdar do transform do
ARGeospatialAnchor e, portanto, será colocado no local esperado na
sessão de RA do ambiente de execução.
Se você precisar identificar GameObjects ARGeospatialAnchor específicos no momento da execução,
pesquise na cena objetos cuja propriedade name corresponda à âncora
criada usando 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?
Talvez você perceba, especialmente quando o app for iniciado pela primeira vez, que a âncora
pode parecer "desvio lentamente" ou até pular vários metros abruptamente. Isso ocorre quando a sessão VPS ainda está determinando e refinando a localização precisa da câmera. À medida que a precisão horizontal e vertical melhora em vários frames,
a âncora é redesenhada em um local mais preciso, criando a ilusão de
movimento. Talvez você queira renderizar o objeto de maneira diferente (ou não renderizar) até que a precisão da localização alcance um determinado limite. Para fazer 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 WGS84. Em um determinado local, pode haver uma discrepância de até vários metros entre o nível do solo aparente que aparece nos blocos do mapa e o solo real, conforme relatado pelo Sistema de Posicionamento Visual do Google (VPS, na sigla em inglês). Se uma âncora geoespacial parece estar localizada incorretamente no momento da execução, recomendamos validar a altura do VPS pessoalmente usando a sobreposição de depuração no app de exemplo. Você pode mudar a altitude no Editor do Unity para corresponder à altura do VPS conhecida nesse local.
Os blocos de mapa não são renderizados corretamente na visualização de cena do editor
Se o Cesium3DTileset parecer estar carregando blocos, mas eles estiverem renderizados em
magenta sólida na visualização de cena, adicione o pacote Shader Graph do Unity ao
projeto. Esse pacote é exigido pelo Cesium, embora os projetos que usam o renderizador
integrado do Unity não o incluam por padrão.
Para adicionar o Shader Graph, abra o Unity Package Manager (Window > Package
Manager). Verifique se você está procurando os pacotes disponíveis no Unity Package
Registry selecionando "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. Depois que o pacote é carregado, os blocos 3D
precisam ser 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, na sigla em inglês) do Unity não está configurado para a câmera de RA
por padrão. Se você vir uma tela preta durante a execução em vez da saída da
câmera, será necessário adicionar o AR Background Renderer Feature a cada renderizador de URP
na cena.
Para adicionar o recurso, procure por "renderizador" no projeto. Para cada objeto URP Renderer, clique no botão "Add Renderer Feature" no inspetor e adicione o renderizador de segundo plano de RA.
Por que as âncoras colocadas longe da origem parecem ter sido posicionadas incorretamente?
A conversão de coordenadas WGS84 em coordenadas de jogo do Unity está sujeita a erros devido à precisão aritmética de ponto flutuante, que pode ser minimizada garantindo que sua origem esteja próxima às âncoras de RA. Distâncias superiores a 20 km podem levar a imprecisões. Recomendamos o uso de várias cenas, com uma âncora exclusiva em cada uma delas, caso sua experiência de RA inclua longas distâncias.