Używaj kotwic geoprzestrzennych do pozycjonowania rzeczywistych treści w pakiecie Android SDK (Kotlin/Java)

Kotwy geoprzestrzenne to rodzaj kotwic, które umożliwiają umieszczanie treści 3D w świecie rzeczywistym.

Rodzaje kotwic geoprzestrzennych

Istnieją 3 typy kotwic geoprzestrzennych, które w różny sposób określają wysokość:

1. Reklamy zakotwiczone WGS84:
   Reklamy zakotwiczone WGS84 umożliwiają umieszczanie treści 3D na dowolnej szerokości, długości i wysokości.

2. Punkty kotwiczenia na lądzie:
   Punkty kotwiczenia na lądzie umożliwiają umieszczanie treści tylko za pomocą szerokości i długości geograficznej z wysokością w stosunku do terenu w danym miejscu. Wysokość jest określana względem podłoża lub podłogi zgodnie z danymi VPS.

3. Punkty kotwiczenia na dachu:
   Punkty kotwiczenia na dachu umożliwiają umieszczanie treści tylko za pomocą współrzędnych geograficznych (szerokość i długość) z wysokością względną względem dachu budynku w tej pozycji. Wysokość jest określana względem szczytu budynku zgodnie z danymi z Streetscape Geometry. Jeśli nie jest umieszczona na budynku, domyślnie jest wyświetlana wysokość ukształtowania terenu.

Wymagania wstępne

Zanim przejdziesz dalej, włącz interfejs Geospatial API.

Umieszczenie kotwic geoprzestrzennych

Każdy typ kotwicy ma dedykowane interfejsy API do ich tworzenia. Więcej informacji znajdziesz w artykule Typy kotwic geoprzestrzennych.

Tworzenie kotwicy na podstawie testu działań

Możesz też utworzyć punkt odniesienia geoprzestrzennego na podstawie wyniku testu trafień. Użyj pozy z testu kolizji i przekształć ją w GeospatialPose. Za jej pomocą możesz dodać dowolny z 3 opisanych typów reklam zakotwiczonych.

Uzyskaj pozę geoprzestrzenną w pozycji AR

Earth.getGeospatialPose() zapewnia dodatkowy sposób określania szerokości i długości geograficznej przez przekształcenie pozycji AR na pozycję geoprzestrzenną.

Uzyskaj pozę AR w pozycji geoprzestrzennej

Earth.getPose() konwertuje pozycję poziomą, wysokość i rotację kwateranionową określoną przez Ziemię na ramkę współrzędnych wschód-góra-południe na pozę AR w ramach współrzędnych świata GL.

Wybierz metodę odpowiednią do Twojego przypadku użycia

Każda metoda tworzenia kotwicy ma związane z nią kompromisy, o których warto pamiętać:

• Jeśli używasz geometrii Streetscape, dołącz treści do budynku za pomocą testu kolizji.
• Zamiast punktów kotwiczenia WGS84 użyj punktów kotwiczenia Teren lub Dach, ponieważ wykorzystują one wartości wysokości określone przez Mapy Google.

Określanie szerokości i długości geograficznej lokalizacji

Długość i szerokość geograficzną lokalizacji można obliczyć na 3 sposoby:

• Korzystaj z Kreatora geoprzestrzennego, aby wyświetlać i rozszerzać świat o treści 3D bez konieczności fizycznego przemieszczania się do danej lokalizacji. Pozwala to wizualnie umieszczać w mapach Google w Edytorze Unity treści angażujące w 3D. Szerokość geograficzną, długość geograficzną, obrót i wysokość treści obliczymy automatycznie.
• Użyj Map Google
• Użyj Google Earth. Pamiętaj, że uzyskanie tych współrzędnych za pomocą Google Earth, a nie Google Maps, spowoduje powstanie marginesu błędu wynoszącego do kilku metrów.
• Przejdź do lokalizacji fizycznej

Użyj Map Google

Aby poznać szerokość i długość geograficzną lokalizacji w Mapach Google:

1. Otwórz Mapy Google na komputerze.

   

2. Kliknij Warstwy > Więcej.

   

   

3. Zmień Typ mapy na Satelita i odznacz pole wyboru Widok kuli ziemskiej w lewym dolnym rogu ekranu.

   

   Spowoduje to wymuszenie perspektywy 2D i wyeliminuje ewentualne błędy, które mogłyby wystąpić w przypadku widoku 3D pod kątem.

4. Na mapie kliknij lokalizację prawym przyciskiem myszy i wybierz długość i szerokość geograficzną, aby skopiować je do schowka.

Korzystanie z Google Earth

W Google Earth możesz obliczyć szerokość i długość geograficzną lokalizacji, klikając ją w interfejsie i odczytując dane ze szczegółów oznaczenia miejsca.

Aby uzyskać szerokość i długość geograficzną lokalizacji w Google Earth:

1. Otwórz Google Earth na komputerze stacjonarnym.

2. Kliknij menu hamburgera  i wybierz Styl mapy.

   

3. Wyłącz przełącznik Budynki 3D.

   

4. Po wyłączeniu przełącznika Budynki 3D kliknij ikonę szpilki , aby dodać punkt na mapie w wybranej lokalizacji.

5. Określ projekt, w którym chcesz umieścić oznaczenie miejsca, i kliknij Zapisz.

6. W polu Tytuł oznaczenia miejsca wpisz nazwę oznaczenia.

7. W panelu projektu kliknij strzałkę wstecz  i wybierz menu  Więcej działań.

8. W menu kliknij Eksportuj jako plik KML.

   

Plik KLM raportuje szerokość, długość i wysokość oznaczenia miejsca w tagu <coordinates> rozdzielone przecinkami w ten sposób:

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

Nie używaj szerokości i długości geograficznej z tagów <LookAt>, które określają pozycję kamery, a nie lokalizację.

Przejdź do lokalizacji fizycznej

Możesz obliczyć wysokość lokalizacji, udając się tam osobiście i wykonując obserwację lokalną.

Pobieranie kwaterniony rotacji

GeospatialPose.getEastUpSouthQuaternion() wyodrębnia orientację z pozycji geoprzestrzennej i generuje kwartion reprezentujący macierz obrotu, która przekształca wektor z miejsca docelowego na układ współrzędnych wschód-południe (EUS). X+ wskazuje na wschód, Y+ na górę, a Z+ na południe. Wartości są zapisywane w kolejności {x, y, z, w}.

Punkty kotwiczenia WGS84

Kotwica WGS84 to rodzaj kotwicy, która umożliwia umieszczanie treści 3D na dowolnej szerokości i długości geograficznej oraz na dowolnej wysokości. Wymaga umieszczenia w świecie rzeczywistym i pozycji. Pozycja składa się z szerokości geograficznej, długości geograficznej i wysokości, które są określone w systemie współrzędnych WGS84. Orientacja składa się z obrotu kwateranionowego.

Wysokość jest podawana w metrach nad elipsoidą WGS84, więc poziom gruntu nie wynosi zero. Twoja aplikacja jest odpowiedzialna za podanie tych współrzędnych w przypadku każdej utworzonej kotwicy.

Umieść kotwicę WGS84 w świecie rzeczywistym

Określanie wysokości lokalizacji

Istnieje kilka sposobów na określenie wysokości lokalizacji na potrzeby umieszczania punktów kotwiczenia:

• Jeśli lokalizacja kotwicy znajduje się fizycznie blisko użytkownika, możesz użyć wysokości podobnej do wysokości urządzenia użytkownika.
• Po uzyskaniu współrzędnych geograficznych użyj interfejsu Elevation API, aby uzyskać wysokość na podstawie specyfikacji EGM96. Aby porównać wysokość w usługach Mapy Google z usługami EGM96, musisz przekonwertować wysokość w usługach Mapy Google do WGS84.GeospatialPose Zapoznaj się z narzędziem GeoidEval, które ma zarówno interfejs wiersza poleceń, jak i interfejs HTML. Interfejs Maps API bezpośrednio raportuje szerokość i długość geograficzną zgodnie ze specyfikacją WGS84.
• Szerokość geograficzną, długość geograficzną i wysokość lokalizacji możesz sprawdzić w Google Earth. To da Ci margines błędu do kilku metrów. Użyj szerokości i długości geograficznej i wysokości z tagów <coordinates>, a nie z tagów <LookAt> w pliku KML.
• Jeśli istniejąca kotwica jest w pobliżu i nie znajdujesz się na stromym zboczu, możesz użyć wysokości z GeospatialPose kamery bez korzystania z innego źródła, takiego jak interfejs Maps API.

Tworzenie kotwicy

Gdy masz już szerokość, długość, wysokość i kwaternion obrotu, użyj atrybutu Earth.createAnchor(), aby zakotwiczyć treści w określonych przez siebie współrzędnych geograficznych.

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

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

Kotwice do terenu

Kotwica terenu to typ zakotwiczenia, który umożliwia umieszczanie obiektów AR tylko na podstawie szerokości i długości geograficznej i wykorzystuje informacje z VPS do określenia dokładnej wysokości nad poziomem gruntu.

Zamiast podawać żądaną wysokość, podajesz wysokość nad rzeźbą terenu. Jeśli wartość wynosi zero, kotwica jest wyrównana z terenem.

Ustawianie trybu wyszukiwania samolotu

Wyszukiwanie samolotów jest opcjonalne i nie jest wymagane do korzystania z kotwic. Pamiętaj, że używane są tylko płaszczyzny poziome. Płaszczyzny poziome pomogą w dynamicznym dopasowywaniu punktów kotwiczenia terenu do podłoża.

Użyj opcji Config.PlaneFindingMode, aby wybrać sposób wykrywania samolotów przez aplikację.

Tworzenie punktu kotwicznego terenu za pomocą nowego interfejsu API asynchronicznego

Aby utworzyć i umieścić reklamę zakotwiczoną terenu, wywołaj Earth.resolveAnchorOnTerrainAsync().

Kotwica nie będzie gotowa od razu i musi zostać rozwiązana. Gdy problem zostanie rozwiązany, będzie dostępny w sekcji ResolveAnchorOnTerrainFuture.

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
      }
    });

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
      }
    }
  )

Sprawdzanie stanu przyszłości

Przyszłość będzie powiązana z FutureState.

Sprawdzanie stanu zakotwiczenia terenu uzyskanego w wyniku przyszłości

Wartość Anchor.TerrainAnchorState należy do operacji asynchronicznej i jest częścią końcowego wyniku Future.

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;
}

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

Kotwice dachowe

Dachowe punkty kotwiczenia to rodzaj punktu kotwiczenia i są bardzo podobne do punktów kotwiczenia na terenie. Różnica polega na tym, że wysokość należy podać nad dachem, a nie nad poziomem terenu.

Utwórz reklamę zakotwiczoną na dachu za pomocą nowego interfejsu Async API

Kotwica nie będzie gotowa od razu i musi zostać rozwiązana.

Aby utworzyć i umieścić punkt kotwiczenia na dachu, wybierz Earth.resolveAnchorOnRooftopAsync(). Podobnie jak w przypadku punktów orientacyjnych na mapie, będziesz mieć też dostęp do FutureState z przyszłości. Następnie możesz sprawdzić wynik dotyczący przyszłości, aby uzyskać dostęp do Anchor.RooftopAnchorState.

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
      }
    });

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
      }
    }
  )

Sprawdzanie stanu przyszłości

Przyszłość będzie powiązana z FutureState (patrz tabela powyżej).

Sprawdzanie stanu zakotwiczenia dachu w przypadku wyniku przyszłego

Wartość Anchor.RooftopAnchorState należy do operacji asynchronicznej i jest częścią końcowego wyniku Future.

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;
}

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

Co dalej?

• Zapoznaj się z limitem korzystania z interfejsu API.