Criar e editar âncoras de forma programática no Geospatial Creator no Unity

Este guia descreve como usar o Geospatial Creator para programar scripts em C# e realizar tarefas comuns rapidamente, como criar e mover objetos ARGeospatialCreatorAnchor no modo de edição do Unity. Isso pode ser útil para criar várias âncoras de uma lista predefinida, como uma planilha ou um arquivo KML.

O Geospatial Creator no Unity permite visualizar o conteúdo geoespacial no Editor do Unity. Nosso Guia de início rápido apresenta o Geospatial Creator e ensina a criar sua primeira experiência de RA habilitada para geoespacial com programação mínima usando a interface do Editor do Unity. Para projetos mais avançados, convém criar e manipular GameObjects do Geospatial Creator de maneira programática, em vez de usar a IU do Editor do Unity.

Para seguir este guia, você precisa conhecer os conceitos básicos do Geospatial Creator apresentados no Guia de início rápido e começar a adicionar âncoras do Geospatial Creator a uma cena. Você precisa ativar e configurar o Geospatial Creator com as chaves de API e os objetos iniciais da sessão de RA no seu cenário. Se estiver começando do zero, siga o guia de início rápido e inclua a seção "Ativar Geospatial Creator" antes de continuar.

Como começar

Neste exemplo, suponha que você tenha um conjunto de locais conhecidos perto da Prefeitura em São Francisco, Califórnia, EUA, onde quer colocar conteúdo de RA. Você precisará criar objetos de âncora em cada um desses locais e, em seguida, anexar uma geometria básica a essas âncoras.

Antes de criar âncoras, especifique um ARGeospatialCreatorOrigin, que é um ponto de referência para converter latitudes, longitudes e altitudes de/para coordenadas mundiais do Unity. A origem também vai conter um subcomponente CesiumGeoreference e um objeto filho Cesium3DTileset, que permite que o Cesium renderize a área ao redor na visualização Scene do editor do Unity. Para fazer isso, você precisa de uma chave da API Google Map Tiles, conforme descrito no Guia de início rápido.

Observação: as APIs abaixo podem ser usadas no modo Editor ao projetar e visualizar suas experiências de RA usando o Geospatial Creator. A maioria das propriedades descritas é somente leitura ou não está disponível no tempo de execução. Para criar cenas de RA dinâmicas no ambiente de execução, recomendamos usar as APIs Geospatial do ARCore diretamente em vez das APIs específicas do Geospatial Creator.

Criar uma origem

A API do Geospatial Creator inclui um método de fábrica para criar um ARGeospatialCreatorOrigin no cenário e adicionar os componentes necessários do Cesium. O código a seguir cria a origem em uma latitude, longitude e altitude próximas usando a chave de API Map Tiles fornecida:

ARGeospatialCreatorOrigin origin =
  GeospatialCreatorCesiumAdapter.CreateOriginWithCesiumGeoreference(
    37.77954, -122.417581, 0.0, "<MAP_TILES_KEY>");

Por padrão, esse objeto é colocado em (0, 0, 0) nas coordenadas mundiais do Unity, o que funciona bem para este exemplo.

Acessar a referência ARAnchorManager

Um ARAnchorManager é necessário para resolver âncoras geoespaciais durante a execução. Você também precisa de uma referência ao ARAnchorManager na cena. Se você começou com o aplicativo Geospatial Sample incluído nas extensões do ARCore, o Anchor Manager é anexado ao GameObject "Origem da sessão em RA". Supondo que você tenha exatamente um gerenciador de âncoras na cena, é possível fazer uma referência a ele assim:

ARAnchorManager anchorManager =
    Resources.FindObjectsOfTypeAll<ARAnchorManager>()[0];

Agora que você tem uma origem e um gerenciador de âncora, pode começar a criar os objetos ARGeospatialCreatorAnchor.

Criar âncoras de terreno

Considere a seguinte matriz bidimensional de valores double, representando a latitude e longitude precisas em três pontos no lado leste da prefeitura em São Francisco, Califórnia, EUA:

double[,] _cityHallEastPoints = {
    { 37.77936, -122.418617 }, // in front of city hall
    { 37.77965, -122.418680 }, // right of city hall
    { 37.77917, -122.418577 }}; // left of city hall

Suponha que você queira colocar um cubo de um metro em cada um desses locais, no nível do solo, no nosso aplicativo de RA. O código a seguir cria objetos ARGeospatialCreatorAnchor e atribui as propriedades deles aos valores adequados:

for (int i = 0; i < _cityHallEastPoints.GetLength(0); i++)
{
  ARGeospatialCreatorAnchor anchor =
    new GameObject("City Hall " + i).AddComponent<ARGeospatialCreatorAnchor>();
  anchor.Origin = origin;
  anchor.AnchorManager = anchorManager;
  anchor.Latitude = _cityHallEastPoints[i, 0];
  anchor.Longitude = _cityHallEastPoints[i, 1];
  anchor.AltitudeType = AnchorAltitudeType.Terrain;

  GameObject cube = GameObject.CreatePrimitive(PrimitiveType.Cube);
  cube.transform.parent = anchor.transform;
}

Isso cria âncoras de terreno em cada ponto. O Geospatial Creator coloca automaticamente as âncoras nas coordenadas mundiais apropriadas do Unity, calculando a localização delas em relação ao objeto ARGeospatialCreatorOrigin. Para ajustar a altitude de uma âncora de terreno, defina a propriedade Altitude em metros acima ou abaixo da superfície do terreno.

Durante a execução, as âncoras de terreno são resolvidas no nível do solo para o app em execução, deslocadas pela propriedade Altitude. No entanto, na visualização da cena do editor, eles são renderizados a uma altitude do WGS84 de 0 por padrão, não em relação à geometria de blocos 3D. Muitas vezes, você não quer que eles apareçam. Você pode substituir a altitude padrão da âncora na visualização da cena do editor definindo a propriedade UseEditorAltitudeOverride como true e especificando a altitude em metros WGS84 usando a propriedade EditorAltitudeOverride:

anchor.UseEditorAltitudeOverride = true;
anchor.EditorAltitudeOverride = -13.5; // WGS84 altitude at ground level for City Hall plaza

Essas duas propriedades não têm efeito fora do modo Editor e não são compiladas no app em execução.

Criar uma âncora no telhado

Para nossa próxima âncora, suponha que você queira colocar uma âncora no telhado do City Hall. A âncora pode ser criada exatamente da mesma maneira, exceto que a propriedade AltitudeType é definida como AnchorAltitudeType.Rooftop:

ARGeospatialCreatorAnchor cityHallRoofAnchor =
  new GameObject("City Hall Roof").AddComponent<ARGeospatialCreatorAnchor>();
cityHallRoofAnchor.Origin = origin;
cityHallRoofAnchor.AnchorManager = anchorManager;
cityHallRoofAnchor.Latitude = 37.77959;
cityHallRoofAnchor.Longitude = -122.419006;
cityHallRoofAnchor.AltitudeType = AnchorAltitudeType.Rooftop;

GameObject roofCube = GameObject.CreatePrimitive(PrimitiveType.Cube);
roofCube.transform.parent = cityHallRoofAnchor.transform;

Assim como nas âncoras de terreno, você pode ajustar a altitude de uma âncora no telhado na visualização de cena do editor usando as propriedades UseEditorAltitudeOverride e EditorAltitudeOverride. Neste exemplo, a altitude do teto no WGS84 é de aproximadamente 10,7 metros.

Criar uma âncora em uma altitude específica

Nossa âncora final será colocada no topo da cúpula da Prefeitura. Para essa âncora, a altitude precisa é importante. Portanto, você a definirá explicitamente usando uma âncora WGS84, em vez de uma âncora de terreno ou telhado:

ARGeospatialCreatorAnchor cityHallDomeAnchor =
  new GameObject("City Hall Dome").AddComponent<ARGeospatialCreatorAnchor>();
cityHallDomeAnchor.Origin = origin;
cityHallDomeAnchor.AnchorManager = anchorManager;
cityHallDomeAnchor.Latitude = 37.77928;
cityHallDomeAnchor.Longitude = -122.419241;
cityHallDomeAnchor.AltitudeType = AnchorAltitudeType.WGS84;
cityHallDomeAnchor.Altitude = 73;

GameObject domeCube = GameObject.CreatePrimitive(PrimitiveType.Cube);
domeCube.transform.parent = cityHallDomeAnchor.transform;

Não é necessário usar a substituição de altitude somente do editor, porque ela já é especificada de acordo com WGS84. Obviamente, se a altura da geometria dos blocos de mapa no editor estiver incorreta em comparação com o mundo real, você ainda poderá usar a substituição do editor para reposicionar a âncora na visualização da cena.