Usar âncoras geoespaciais para posicionar conteúdo real no iOS

As âncoras geoespaciais são um tipo de âncora que permite colocar conteúdo 3D no mundo real.

Tipos de âncoras geoespaciais

Existem três tipos de âncoras geoespaciais, que processam a altitude de maneira diferente:

  1. Âncoras WGS84:
    As âncoras WGS84 permitem colocar conteúdo 3D em qualquer latitude, longitude e altitude.

  2. Âncoras de terreno:
    As âncoras de terreno permitem posicionar conteúdo usando somente latitude e longitude com uma altura relativa ao terreno naquela posição. A altitude é determinada em relação ao solo ou ao andar, conforme conhecido pelo VPS.

  3. Âncoras no telhado:
    as âncoras no telhado permitem que você coloque conteúdo usando apenas latitude e longitude com uma altura relativa ao telhado de um edifício nessa posição. A altitude é determinada em relação ao topo de um edifício, como conhecido da Streetscape Geometry. O padrão será a altitude do terreno quando não estiver em um edifício.

WGS84 Relevo Telhado
Posição horizontal Latitude, longitude Latitude, longitude Latitude, longitude
Posição vertical Relativa à altitude WGS84 Em relação ao nível do terreno determinado pelo Google Maps Em relação ao nível do telhado determinado pelo Google Maps
Precisa ser resolvido pelo servidor? Não Sim Sim

Pré-requisitos

Ative a API Geospatial antes de continuar.

Colocar âncoras geoespaciais

Cada tipo de âncora possui APIs dedicadas para criá-las; consulte Tipos de âncoras geoespaciais para mais informações.

Criar uma âncora com base em um teste de hit

Também é possível criar uma âncora geoespacial a partir de um resultado de hit-test. Usar a transformação do teste de hit e convertê-la em um GARGeospatialTransform. Use-o para posicionar qualquer um dos três tipos de âncora descritos.

Extrair uma transformação geoespacial de uma transformação de RA

O GARSession.geospatialTransformFromTransform:error: oferece outra maneira de determinar a latitude e a longitude convertendo uma transformação de RA em uma transformação geoespacial.

Como conseguir uma transformação de RA com uma transformação geoespacial

GARSession.transformFromGeospatialCoordinate:altitude:eastUpSouthQTarget:error: converte uma posição horizontal, altitude e rotação de quatérnio especificadas pela Terra em relação a um frame de coordenadas leste-sul em uma transformação AR em relação à coordenada mundial GL.

Escolha o método adequado para seu caso de uso

Cada método de criação de uma âncora apresenta compensações associadas que devem ser lembradas:

  • Ao usar a Geometria da paisagem urbana, use um teste de hit para anexar conteúdo a um edifício.
  • Prefira âncoras de terreno ou telhado em vez de âncoras WGS84 porque elas usam valores de altitude determinados pelo Google Maps.

Determinar a latitude e a longitude de um local

Há três maneiras de calcular a latitude e a longitude de um local:

  • Use o Criador de geoespacial para conferir e ampliar o mundo com conteúdo 3D sem precisar ir até um local. Isso permite que você posicione conteúdo imersivo 3D visualmente usando o Google Maps no Editor do Unity. A latitude, a longitude, a rotação e a altitude do conteúdo serão calculadas automaticamente para você.
  • Usar o Google Maps
  • Usar o Google Earth. Observe que a obtenção dessas coordenadas usando o Google Earth, e não o Google Maps, lhe dará uma margem de erro de até vários metros.
  • Acessar o local físico

Usar o Google Maps

Para conferir a latitude e a longitude de um local usando o Google Maps, faça o seguinte:

  1. Acesse o Google Maps no seu computador desktop.

  2. Navegue até Camadas > Mais.

  3. Mude a opção Tipo de mapa para Satélite e desmarque a caixa de seleção Visualização de globo no canto inferior esquerdo da tela.

    Isso forçará uma perspectiva 2D e eliminará possíveis erros que possam vir de uma visualização 3D em ângulo.

  4. No mapa, clique com o botão direito do mouse no local e selecione a longitude/latitude para copiá-lo para a área de transferência.

Usar o Google Earth

Para calcular a latitude e a longitude de um local no Google Earth, clique em um local na interface e leia os dados dos detalhes do marcador.

Para conferir a latitude e a longitude de um local usando o Google Earth:

  1. Acesse o Google Earth em um computador desktop.

  2. Acesse o menu de navegação e selecione Estilo do mapa.

  3. Desative a opção Construções em 3D.

  4. Depois de desativar a opção Edifícios em 3D, clique no ícone de alfinete para adicionar um marcador de lugar no local selecionado.

  5. Especifique um projeto para conter o marcador de local e clique em Salvar.

  6. No campo Título do marcador de lugar, insira um nome.

  7. Clique na seta para voltar no painel do projeto e selecione o menu Mais ações.

  8. Escolha Exportar como arquivo KML no menu.

O arquivo KLM informa a latitude, longitude e altitude de um marcador na tag <coordinates> separados por vírgulas, da seguinte forma:

<coordinates>-122.0755182435043,37.41347299422944,7.420342565583832</coordinates>

Não use a latitude e a longitude das tags <LookAt>, que especificam a posição da câmera, não a localização.

Ir para o local físico

Você pode calcular a altitude de um local indo até lá e fazendo uma observação local.

Conseguir o quatérnion de rotação

GARGeospatialTransform.eastUpSouthQTarget extrai a orientação de uma transformação geoespacial e gera um quaternion que representa a matriz de rotação que transforma um vetor do destino para o sistema de coordenadas leste-cima-sul (EUS, na sigla em inglês). X+ aponta para o leste, Y+ para cima e Z+ para o sul. Os valores são gravados na ordem {x, y, z, w}.

Âncoras do WGS84

Uma âncora WGS84 é um tipo de âncora que permite posicionar conteúdo 3D em qualquer latitude, longitude e altitude. Ele depende de uma transformação e orientação para ser colocado no mundo real. A posição consiste em latitude, longitude e altitude, que são especificadas no sistema de coordenadas WGS84. A orientação consiste em uma rotação de quatérnio.

A altitude é informada em metros acima do elipsoide de referência WGS84, de modo que o nível do solo não seja zero. Seu app é responsável por fornecer essas coordenadas para cada âncora criada.

Colocar uma âncora WGS84 no mundo real

Determinar a altitude de um local

Há algumas maneiras de determinar a altitude de um local para colocar âncoras:

  • Se o local da âncora estiver fisicamente próximo ao usuário, use uma altitude semelhante à do dispositivo dele.
  • Quando você tiver a latitude e a longitude, use a API Elevation para conferir uma elevação com base na especificação EGM96. Você precisa converter a elevação da API Maps EGM96 para WGS84 para comparação com a altitude GARGeospatialTransform. Consulte a GeoidEval, que tem uma linha de comando e uma interface HTML. A API do Google Maps informa a latitude e longitude de acordo com a especificação WGS84 pronta para uso.
  • Você pode obter a latitude, longitude e altitude de um local no Google Earth. Isso vai dar uma margem de erro de até vários metros. Use a latitude, a longitude e a altitude das tags <coordinates>, não das tags <LookAt>, no arquivo KML.
  • Se uma âncora existente estiver por perto e você não estiver em uma inclinação íngreme, poderá usar a altitude da GARGeospatialTransform da câmera sem usar outra fonte, como a API Maps.

Criar a âncora

Depois de ter a latitude, a longitude, a altitude e o quatérnio da rotação, use createAnchorWithCoordinate:altitude:eastUpSouthQAnchor:error:. para fixar o conteúdo nas coordenadas geográficas especificadas.

  NSError *error = nil;
  GARAnchor *anchor = [self.garSession createAnchorWithCoordinate:coordinate
                                                         altitude:altitude
                                               eastUpSouthQAnchor:eastUpSouthQAnchor
                                                            error:&error];

Âncoras para terrenos

Uma âncora de terreno é um tipo de âncora que permite colocar objetos de RA usando apenas latitude e longitude, aproveitando informações de VPS para encontrar a altitude precisa acima do solo.

Em vez de inserir a altitude desejada, você fornece a altitude acima do terreno. Quando esse valor é zero, a âncora fica nivelada com o terreno.

Definir o modo de descoberta de avião

A detecção de plano é opcional e não é necessária para usar âncoras. Somente planos horizontais são usados. Planos horizontais ajudam no alinhamento dinâmico das âncoras de terreno no solo.

Use ARWorldTrackingConfiguration.PlaneDetection para selecionar como o app detecta planos.

Criar uma âncora de terreno usando a nova API Async

Para criar e posicionar uma âncora de terreno, chame GARSession.createAnchorWithCoordinate:altitudeAboveTerrain:eastUpSouthQAnchor:completionHandler:error:.

A âncora não estará pronta imediatamente e precisa ser resolvida. Depois que o problema for resolvido, ele vai ficar disponível no GARCreateAnchorOnTerrainFuture.

GARCreateAnchorOnTerrainFuture *future = [self.garSession createAnchorWithCoordinate:coordinate
                                                                altitudeAboveTerrain:altitude
                                                                  eastUpSouthQAnchor:eastUpSouthQTarget
                                                                   completionHandler:^(GARAnchor *anchor, GARTerrainAnchorState state) {
                                                                     // handle completion
                                                                   }
                                                                               error:&error];

Verificar o Estado do futuro

O Future terá um GARFutureState associado.

Estado Descrição
GARFutureStatePending A operação ainda está pendente.
GARFutureStateDone A operação foi concluída e o resultado está disponível.
GARFutureStateCancelled A operação foi cancelada.

Verificar o estado da âncora do terreno do resultado Futuro

O GARTerrainAnchorState pertence à operação assíncrona e faz parte do resultado final do Future.

switch (future.resultTerrainAnchorState) {
  case GARTerrainAnchorStateSuccess:
    // Terrain anchor finished resolving.
    break;
  case GARTerrainAnchorStateErrorUnsupportedLocation:
    // The requested anchor is in a location that isn't supported by the Geospatial API.
    break;
  case GARTerrainAnchorStateErrorNotAuthorized:
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/ios/group/GARTerrainAnchorState#garterrainanchorstateerrornotauthorized
    // for troubleshooting steps.
    break;
  case GARTerrainAnchorStateErrorInternal:
    // The Terrain anchor could not be resolved due to an internal error.
    break;
  default:
    break;
}

Âncoras para cobertura

Imagem principal das âncoras no telhado

As âncoras de telhado são um tipo de âncora e são muito semelhantes às Âncoras de terreno acima. A diferença é que você vai informar a altitude acima do telhado, e não a altitude acima do terreno.

Criar uma âncora Rooftop usando a nova API Async

A âncora não estará pronta imediatamente e precisa ser resolvida.

Para criar e posicionar uma âncora do Rooftop, chame GARSession.createAnchorWithCoordinate:altitudeAboveRooftop:eastUpSouthQAnchor:completionHandler:error:. Assim como as âncoras de terreno, você também vai acessar o GARFutureState do futuro. Em seguida, marque o resultado futuro para acessar o GARRooftopAnchorState.

GARCreateAnchorOnRooftopFuture *future = [self.garSession createAnchorWithCoordinate:coordinate
                                                                altitudeAboveRooftop:altitude
                                                                  eastUpSouthQAnchor:eastUpSouthQTarget
                                                                   completionHandler:^(GARAnchor *anchor, GARRooftopAnchorState state) {
                                                                     // handle completion
                                                                   }
                                                                               error:&error];

Confira o estado do futuro

O futuro terá um GARFutureState associado. Consulte a tabela acima.

Verificar o estado da âncora do telhado do resultado futuro

O GARRooftopAnchorState pertence à operação assíncrona e faz parte do resultado final do Future.

switch (future.resultRooftopAnchorState) {
  case GARRooftopAnchorStateSuccess:
    // Rooftop anchor finished resolving.
    break;
  case GARRooftopAnchorStateErrorUnsupportedLocation:
    // The requested anchor is in a location that isn't supported by the Geospatial API.
    break;
  case GARRooftopAnchorStateErrorNotAuthorized:
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/ios/group/GARRooftopAnchorState#garrooftopanchorstateerrornotauthorized
    // for troubleshooting steps.
    break;
  case GARRooftopAnchorStateErrorInternal:
    // The Rooftop anchor could not be resolved due to an internal error.
    break;
  default:
    break;
}

A seguir