Usar âncoras geoespaciais para posicionar conteúdo real no SDK do Android (Kotlin/Java)

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

Tipos de âncoras geoespaciais

Há três tipos de âncoras geoespaciais, cada uma processa a altitude de maneira diferente:

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

2. Âncoras de terreno:
   as âncoras de terreno permitem colocar conteúdo usando apenas latitude e longitude com uma altura relativa ao terreno nessa 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 colocar 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, conforme conhecido pela Geometria da paisagem urbana. 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 tem APIs dedicadas para a criação. 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 usando um resultado de hit-test. Use a pose do teste de hit e converta-a em um GeospatialPose. Use-o para posicionar qualquer um dos três tipos de âncora descritos.

Extrair uma pose geoespacial de uma pose de RA

Earth.getGeospatialPose() oferece outra maneira de determinar a latitude e a longitude convertendo uma pose de RA em uma pose geoespacial.

Extrair uma pose de RA de uma pose geoespacial

Earth.getPose() converte uma posição horizontal, altitude e rotação de quaternion especificada pela Terra em relação a um frame de coordenadas leste-cima-sul em uma pose de RA em relação à coordenada mundial do GL.

Escolha o método que se adapta ao seu caso de uso

Cada método de criação de uma âncora tem compensações associadas que precisam ser consideradas:

• Ao usar a Geometria da paisagem urbana, use um teste de hit para anexar conteúdo a um edifício.
• Prefira as ancoragens de terreno ou de telhado em vez das ancoragens 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 aumentar o mundo com conteúdo 3D sem precisar ir a um local. Assim, você pode posicionar conteúdo imersivo 3D usando os mapas do Google 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
• Use o Google Earth. Vale lembrar que, ao usar o Google Earth em vez do Google Maps, você terá 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:

1. Acesse o Google Maps no seu computador.

   

2. Acesse Camadas > Mais.

   

   

3. Mude 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 poderiam 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 copiar 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.

Observação: ao usar o Google Earth, em vez do Google Maps, para encontrar essas coordenadas, você terá uma margem de erro de até vários metros. Recomendamos usar o Google Maps e a API Elevation para conferir a latitude e a longitude de um local.

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

1. Acesse o Google Earth no seu computador.

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

   

3. Desative a chave 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, a longitude e a altitude de um marcador de lugar na tag <coordinates> separada por vírgulas, conforme mostrado a seguir:

<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.

Acessar 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

GeospatialPose.getEastUpSouthQuaternion() extrai a orientação de uma pose geoespacial e gera um quatérnion que representa a matriz de rotação que transforma um vetor do alvo 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 colocar conteúdo 3D em qualquer latitude, longitude e altitude. Ele depende de uma pose 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 quaternion.

A altitude é informada em metros acima do elipsóide de referência WGS84, de modo que o nível do solo não está em 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.
• Depois de ter a latitude e a longitude, use a API Elevation para receber 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 GeospatialPose. Consulte o GeoidEval, que tem uma linha de comando e uma interface HTML. A API Maps informa a latitude e a longitude de acordo com a especificação WGS84.
• Você pode conferir a latitude, a longitude e a 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 as 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 GeospatialPose 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érnion de rotação, use Earth.createAnchor() para ancorar o conteúdo nas coordenadas geográficas especificadas.

Java

if (earth != null && earth.getTrackingState() == TrackingState.TRACKING) {
  Anchor anchor =
    earth.createAnchor(
      /* Location values */
      latitude,
      longitude,
      altitude,
      /* Rotational pose values */
      qx,
      qy,
      qz,
      qw);

  // Attach content to the anchor specified by geodetic location and pose.
}

Kotlin

if (earth.trackingState == TrackingState.TRACKING) {
  val anchor =
    earth.createAnchor(
      /* Location values */
      latitude,
      longitude,
      altitude,
      /* Rotational pose values */
      qx,
      qy,
      qz,
      qw
    )

  // Attach content to the anchor specified by geodetic location and pose.
}

Observação: não é possível criar âncoras a menos de 0,1 grau do Pólo Norte ou do Pólo Sul (90 graus ou -90 graus). Se essa âncora for especificada, ela não será criada.

Âncoras de terreno

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, informe a altitude acima do terreno. Quando esse valor é zero, a âncora fica no mesmo nível do terreno.

Definir o modo de busca de aviões

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

Use Config.PlaneFindingMode para selecionar como o app detecta aviões.

Criar uma âncora de terreno usando a nova API Async

Para criar e posicionar uma âncora de terreno, chame Earth.resolveAnchorOnTerrainAsync().

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

Java

final ResolveAnchorOnTerrainFuture future =
  earth.resolveAnchorOnTerrainAsync(
    latitude,
    longitude,
    /* altitudeAboveTerrain= */ 0.0f,
    qx,
    qy,
    qz,
    qw,
    (anchor, state) -> {
      if (state == TerrainAnchorState.SUCCESS) {
        // do something with the anchor here
      } else {
        // the anchor failed to resolve
      }
    });

Kotlin

var future =
  earth.resolveAnchorOnTerrainAsync(
    latitude,
    longitude,
    altitudeAboveTerrain,
    qx,
    qy,
    qz,
    qw,
    { anchor, state ->
      if (state == TerrainAnchorState.SUCCESS) {
        // do something with the anchor here
      } else {
        // the anchor failed to resolve
      }
    }
  )

Observação: não é possível criar âncoras a menos de 0,1 grau dos polos norte ou sul (90 graus ou -90 graus). Se essa âncora for especificada, Earth.resolveAnchorOnTerrainAsync() vai gerar uma IllegalArgumentException e a âncora não será criada.

Verificar o Estado do futuro

O Future terá um FutureState associado.

Estado	Descrição
FutureState.PENDING	A operação ainda está pendente.
FutureState.DONE	A operação foi concluída e o resultado está disponível.
FutureState.CANCELLED	A operação foi cancelada.

Verificar o estado de âncora do terreno do resultado futuro

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

Java

switch (terrainAnchorState) {
  case SUCCESS:
    // A resolving task for this Terrain anchor has finished successfully.
    break;
  case ERROR_UNSUPPORTED_LOCATION:
    // The requested anchor is in a location that isn't supported by the Geospatial API.
    break;
  case ERROR_NOT_AUTHORIZED:
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/java/com/google/ar/core/Anchor.TerrainAnchorState#error_not_authorized
    // for troubleshooting steps.
    break;
  case ERROR_INTERNAL:
    // The Terrain anchor could not be resolved due to an internal error.
    break;
  default:
    // not reachable
    break;
}

Kotlin

when (state) {
  TerrainAnchorState.SUCCESS -> {
    // A resolving task for this Terrain anchor has finished successfully.
  }
  TerrainAnchorState.ERROR_UNSUPPORTED_LOCATION -> {
    // The requested anchor is in a location that isn't supported by the Geospatial API.
  }
  TerrainAnchorState.ERROR_NOT_AUTHORIZED -> {
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/java/com/google/ar/core/Anchor.TerrainAnchorState#error_not_authorized
    // for troubleshooting steps.
  }
  TerrainAnchorState.ERROR_INTERNAL -> {
    // The Terrain anchor could not be resolved due to an internal error.
  }
  else -> {
    // Default.
  }
}

Âncoras para cobertura

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

Observação: alguns locais têm informações mais precisas sobre o telhado do que outros. Confira a seção "Qualidade" em Geometria do cenário urbano para mais informações.

Criar uma âncora do 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 Earth.resolveAnchorOnRooftopAsync(). Assim como as âncoras de terreno, você também vai acessar o FutureState do futuro. Em seguida, verifique o resultado futuro para acessar o Anchor.RooftopAnchorState.

Java

final ResolveAnchorOnRooftopFuture future =
  earth.resolveAnchorOnRooftopAsync(
    latitude,
    longitude,
    /* altitudeAboveRooftop= */ 0.0f,
    qx,
    qy,
    qz,
    qw,
    (anchor, state) -> {
      if (state == RooftopAnchorState.SUCCESS) {
        // do something with the anchor here
      } else {
        // the anchor failed to resolve
      }
    });

Kotlin

var future =
  earth.resolveAnchorOnRooftopAsync(
    latitude,
    longitude,
    altitudeAboveRooftop,
    qx,
    qy,
    qz,
    qw,
    { anchor, state ->
      if (state == RooftopAnchorState.SUCCESS) {
        // do something with the anchor here
      } else {
        // the anchor failed to resolve
      }
    }
  )

Verificar o Estado do futuro

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

Verificar o estado da âncora do telhado do resultado futuro

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

Java

switch (rooftopAnchorState) {
  case SUCCESS:
    // A resolving task for this Rooftop anchor has finished successfully.
    break;
  case ERROR_UNSUPPORTED_LOCATION:
    // The requested anchor is in a location that isn't supported by the Geospatial API.
    break;
  case ERROR_NOT_AUTHORIZED:
    // An error occurred while authorizing your app with the ARCore API.
    // https://developers.google.com/ar/reference/java/com/google/ar/core/Anchor.RooftopAnchorState#error_not_authorized
    // for troubleshooting steps.
    break;
  case ERROR_INTERNAL:
    // The Rooftop anchor could not be resolved due to an internal error.
    break;
  default:
    // not reachable
    break;
}

Kotlin

when (state) {
  RooftopAnchorState.SUCCESS -> {
    // A resolving task for this Rooftop anchor has finished successfully.
  }
  RooftopAnchorState.ERROR_UNSUPPORTED_LOCATION -> {
    // The requested anchor is in a location that isn't supported by the Geospatial API.
  }
  RooftopAnchorState.ERROR_NOT_AUTHORIZED -> {
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/java/com/google/ar/core/Anchor.RooftopAnchorState#error_not_authorized
    // for troubleshooting steps.
  }
  RooftopAnchorState.ERROR_INTERNAL -> {
    // The Rooftop anchor could not be resolved due to an internal error.
  }
  else -> {
    // Default.
  }
}

A seguir

• Entenda a cota de uso da API Geospatial.