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

Kotwice geoprzestrzenne to typ 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 pozwalają umieszczać treści 3D na dowolnej szerokości geograficznej, długości i wysokości.

2. Elementy zakotwiczone terenu:
   Kotwice terenu umożliwiają umieszczanie treści tylko na podstawie szerokości geograficznej długość geograficzna i wysokość w odniesieniu do terenu w danej pozycji. Wysokość jest określana względem ziemi lub piętra, co jest znane przez VPS.

3. Reklamy zakotwiczone dachowe:
   Kotwice dachowe umożliwiają umieszczanie treści tylko na podstawie szerokości geograficznej długość geograficzna i wysokość w odniesieniu do dachu budynku w danym miejscu. Wysokość jest określana w odniesieniu do szczytu budynku o znanej nazwie autor: Streetscape Geometry. Jeśli nie zostanie umieszczona na budynku, domyślnie będzie wyświetlana wysokość ukształtowania terenu.

	WGS84	Teren	Dach
Pozycja w poziomie	Szerokość geograficzna, długość geograficzna	Szerokość geograficzna, długość geograficzna	Szerokość geograficzna, długość geograficzna
Pozycja w pionie	Względem wysokości WGS84	Względem poziomu terenu określonego przez Mapy Google	Względem dachów określonych przez Mapy Google
Wymaga rozwiązania przez serwer?	Nie	Tak	Tak

Wymagania wstępne

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

Umieść kotwice geoprzestrzenne

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ń

Kotwica geoprzestrzenna możesz też utworzyć na podstawie wyniku testu działań. Zastosuj pozycję z testu działań i przekształć ją w GeospatialPose. Służy do umieszczania dowolnego z 3 opisanych typów reklam zakotwiczonych.

Uchwyć pozycję 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 określone przez Ziemię położenie poziome, wysokość i obrót kwartionowy względem ramki współrzędnych wschód-południe na pozycję AR w odniesieniu do współrzędnych świata GL.

Wybierz metodę odpowiednią do Twojego zastosowania

Każda metoda tworzenia reklamy zakotwiczonej wiąże się z korzyściami, o których trzeba pamiętać:

• Jeśli korzystasz z funkcji Geometria Streetscape, za pomocą testów zgodności dołączonych treści do budynku.
• Preferuj reklamy zakotwiczone terenu / dachu zamiast reklam zakotwiczonych WGS84, ponieważ korzystają z wartości wysokości określonych 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 danych geoprzestrzennych, aby oglądać i wzbogacać świat za pomocą treści 3D bez konieczności fizycznego odwiedzania lokalizacji. Dzięki temu możesz wizualnie umieszczać wciągające treści 3D za pomocą Map Google w Edytorze Unity. Szerokość, długość geograficzna, obrót i wysokość treści zostaną obliczone automatycznie.
• Użyj Map Google
• Korzystanie z Google Earth. Pamiętaj, że uzyskanie tych współrzędnych w Google Earth, a nie w Mapach Google, powoduje margines błędu 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. Przejdź do Warstwy > Więcej.

   

   

3. Zmień Typ mapy na Satelita i usuń zaznaczenie pola wyboru Widok kuli ziemskiej w lewym dolnym rogu ekranu.

   

   Wymusi to widok z perspektywy 2D i wyeliminuje możliwe błędy, które mogą być spowodowane pod kątem widoku 3D.

4. Kliknij lokalizację prawym przyciskiem myszy i wybierz długość lub szerokość geograficzną na mapie, aby skopiować ją 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.

Uwaga: uzyskanie tych współrzędnych w Google Earth, a nie w Mapach Google, powoduje margines błędu wynoszący nawet kilka metrów. Zalecamy korzystanie z Map Google i interfejsu Elevation API do pobierania szerokości i długości geograficznej lokalizacji.

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

1. Otwórz Google Earth na komputerze.

2. Przejdź do menu z hamburgerami i wybierz Styl mapy.

   

3. Przesuń przełącznik Budynki 3D, aby go wyłączyć.

   

4. Po wyłączeniu przełącznika Budynki 3D kliknij ikonę pinezki , aby dodać oznaczenie miejsca 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 miejsca.

7. Kliknij strzałkę wstecz w panelu projektu i wybierz menu Więcej czynności.

8. W menu wybierz 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, przychodząc do niej fizycznie i wykonując lokalne obserwacje.

Pobierz kwartion rotacji

GeospatialPose.getEastUpSouthQuaternion() wyodrębnia orientację z pozycji geoprzestrzennej i podaje 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+ punkty na wschód, Y+ punkty w górę i Z+ punkty na południe. Wartości są zapisywane w kolejności {x, y, z, w}.

Kotwice WGS84

Reklamy zakotwiczone WGS84 to typ kotwicy, który umożliwia umieszczanie treści 3D na dowolnej szerokości, długości i wysokości. Jego umiejscowienie zależy od pozycji i orientacji, które musi znajdować się w świecie rzeczywistym. Pozycja składa się z szerokości, długości i wysokości nad poziomem morza, które są określone w układzie współrzędnych WGS84. Orientacja składa się z rotacji w kwartionach.

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

Umieść kotwicę WGS84 w świecie rzeczywistym

Określanie wysokości lokalizacji

Istnieje kilka sposobów na określenie wysokości lokalizacji na potrzeby umieszczania reklam zakotwiczonych:

• Jeśli kotwica znajduje się fizycznie blisko użytkownika, możesz użyć wysokości podobnej do wysokości jego urządzenia.
• Gdy poznasz długość i szerokość geograficzną, użyj interfejsu Elevation API, aby uzyskać wysokość na podstawie specyfikacji EGM96. Aby porównać wysokość z wysokością GeospatialPose, musisz przekonwertować wysokość w interfejsie API Map Google EGM96 na WGS84. Zobacz GeoidEval, który zawiera zarówno wiersz poleceń, jak i interfejs HTML. Interfejs Maps API bezpośrednio raportuje szerokość i długość geograficzną zgodnie ze specyfikacją WGS84.
• Długość i szerokość geograficzną lokalizacji oraz wysokość możesz sprawdzić w Google Earth. Dzięki temu margines błędu wynosi 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 znajdujący się w pobliżu obiekt zakotwiczony znajduje się oraz nie jesteś na stromym zboczu, możesz użyć wysokości z aparatu GeospatialPose bez korzystania z innego źródła, np. interfejsu API Map Google.

Tworzenie kotwicy

Po określeniu szerokości i długości geograficznej, wysokości i kwartionu obrotu użyj Earth.createAnchor() w celu zakotwiczenia treści w określonych przez Ciebie współrzędnych geograficznych.

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

Uwaga: tworzenie reklam zakotwiczonych znajdujących się w odległości 0,1 stopnia od bieguna północnego lub południowego (90 stopni) lub -90°) nie jest obsługiwane. Jeśli reklama zakotwiczona jest określona, parametr kotwicy nie zostanie utworzona.

Kotwice 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 wpisywać żądaną wysokość, podaj wysokość nad poziomem terenu. Jeśli wartość wynosi zero, kotwica jest wyrównana z terenem.

Ustawianie trybu wyszukiwania samolotu

Wyniki na płaszczyźnie są opcjonalne i nie są wymagane do korzystania z reklam zakotwiczonych. Pamiętaj, że używane są tylko płaszczyzny poziome. Poziome płaszczyzny ułatwiają dynamiczne wyrównanie elementów kotwicy terenu do ziemi.

Użyj ikony Config.PlaneFindingMode, aby określić, w jaki sposób aplikacja ma wykrywać samoloty.

Tworzenie kotwicy terenu za pomocą nowego interfejsu Async API

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

Reklama zakotwiczona nie będzie od razu gotowa i trzeba ją rozwiązać. Po rozwiązaniu problemu będzie on dostępny w 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
      }
    }
  )

Uwaga: tworzenie reklam zakotwiczonych znajdujących się w odległości 0,1 stopnia od bieguna północnego lub południowego (90 stopni) lub -90°) nie jest obsługiwane. Jeśli jest określona, Earth.resolveAnchorOnTerrainAsync() wywoła IllegalArgumentException, a kotwica nie zostanie utworzona.

Sprawdź przyszłość

Przyszłość będzie mieć powiązaną wartość FutureState.

Stan	Opis
FutureState.PENDING	Operacja jest nadal w toku.
FutureState.DONE	Operacja została zakończona i wyniki są dostępne.
FutureState.CANCELLED	Operacja została anulowana.

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

Anchor.TerrainAnchorState należy do operacji asynchronicznej i jest częścią ostatecznego wyniku typu 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.
  }
}

Kotwy dachowe

Kołki dachowe to rodzaj kotwic, które są bardzo podobne do podanych wyżej kotwic dachowych. Różnica polega na tym, że wysokość należy podać nad dachem, a nie nad poziomem terenu.

Uwaga: w przypadku niektórych lokalizacji informacje o dachach są dokładniejsze niż w przypadku innych. Więcej informacji znajdziesz w sekcji Jakość na stronie Geometria Streetscape.

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

Reklama zakotwiczona nie będzie od razu gotowa i trzeba ją rozwiązać.

Aby utworzyć i umieścić reklamę zakotwiczoną na dachu, wywołaj Earth.resolveAnchorOnRooftopAsync(). Podobnie jak w przypadku kotwicy terenu, uzyskasz też dostęp do FutureState przyszłości. Następnie możesz sprawdzić wynik w przyszłości, aby uzyskać dostęp do: 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
      }
    }
  )

Sprawdź przyszłość

Przyszłość będzie miała powiązaną wartość FutureState. Zobacz tabelę powyżej.

Sprawdzanie stanu zakotwiczenia dachu w przypadku wyniku przyszłego

Anchor.RooftopAnchorState należy do operacji asynchronicznej i jest częścią ostatecznego wyniku typu 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.
  }
}

Co dalej?

• Upewnij się, że znasz limit wykorzystania interfejsu API geoprzestrzenny.