Utwórz aplikację rzeczywistości rozszerzonej (AR) za pomocą nowego interfejsu ARCore Geospatial API

1. Przegląd

ARCore to platforma Google do tworzenia projektów rzeczywistości rozszerzonej na smartfony. Nowy ARCore Geospatial API nadaje rzeczywistości rozszerzonej nowy wymiar, umożliwiając umieszczanie w rzeczywistych miejscach charakterystycznych punktów orientacyjnych w rzeczywistości rozszerzonej.

Co utworzysz

W tym ćwiczeniu z programowania zaczniesz korzystać z interfejsu ARCore Geospatial API. Dowiesz się, jakie informacje może zaoferować interfejs Geospatial API w kontekście ogólnych wrażeń związanych z AR i jak te dane mogą być wykorzystywane do tworzenia prostych funkcji nawigacji w AR.

Czego się nauczysz

• Jak skonfigurować projekt ARCore, który korzysta z interfejsu Geospatial API.
• Jak wysyłać do interfejsu Geospatial API prośby o dane geograficzne i wyświetlać je za pomocą Map Google.
• Jak umieścić kotwicę przywiązaną do rzeczywistej lokalizacji.

Czego potrzebujesz

• Obsługiwane urządzenie z Androidem i ARCore podłączone do komputera używanego do programowania za pomocą kabla USB i skonfigurowane pod kątem debugowania USB.
• Android Studio zainstalowane i skonfigurowane do tworzenia aplikacji na Androida.
• Usługi Google Play dla AR w wersji 1.31 lub nowszej zainstalowane na urządzeniu deweloperskim z Androidem.

2. Konfigurowanie środowiska programistycznego

Konfigurowanie Android Studio

Aby ułatwić Ci rozpoczęcie pracy z interfejsem Geospatial API, udostępniliśmy projekt startowy, który zawiera podstawy projektu ARCore zintegrowanego z pakietem Google Maps SDK. Dzięki temu możesz szybko rozpocząć korzystanie z interfejsu Geospatial API.

1. Uruchom Android Studio i zaimportuj projekt z VCS.
   • Jeśli masz już otwarty projekt, kliknij Plik > Nowy > Projekt z systemu kontroli wersji....
   • Jeśli zobaczysz okno Welcome to Android Studio (Witamy w Android Studio), kliknij Get from VCS (Pobierz z VCS).
2. Wybierz Git i użyj adresu URL https://github.com/google-ar/codelab-geospatial.git, aby zaimportować projekt.

Konfigurowanie projektu Google Cloud

Interfejs Geospatial API wykorzystuje zdjęcia Street View w połączeniu z informacjami z magnetometru i czujnika aparatu urządzenia, aby poprawić wartości orientacji. Aby korzystać z tej usługi, musisz skonfigurować projekt Google Cloud.

1. Utwórz projekt w konsoli Google Cloud:
   • Otwórz stronę Tworzenie projektu w Google Cloud Platform.
     
   • Wpisz odpowiednią nazwę projektu (np. „Projekt ARCore Geospatial API”) i wybierz dowolną lokalizację.
   • Kliknij Utwórz.
2. Włącz niezbędne interfejsy API:
   • Na pasku bocznym wybierz Interfejsy API i usługi, a potem Biblioteka.
   • Wyszukaj ARCore API.
   • Kliknij Włącz.
   • Wróć do Biblioteki.
   • Wyszukaj Maps SDK na Androida.
   • Kliknij Włącz.
3. Utwórz dane logowania klucza interfejsu API:
   • W sekcji Interfejsy API i usługi wybierz Dane logowania.
   • Na pasku u góry kliknij Utwórz dane logowania, a potem wybierz Klucz interfejsu API.
   • Zapisz utworzony klucz, ponieważ będzie Ci potrzebny w następnym kroku. Jeśli chcesz go odzyskać, wróć na stronę Dane logowania.

Po wykonaniu tych czynności utworzysz projekt Google Cloud z autoryzacją klucza interfejsu API i będziesz gotowy(-a) do korzystania z interfejsu Geospatial API.

Integrowanie klucza interfejsu API z projektem Android Studio

Aby powiązać klucz interfejsu API z Google Cloud z projektem, otwórz utworzony projekt w Android Studio i zmodyfikuj klucze interfejsu API:

1. Otwórz app > src > AndroidManifest.xml.
2. Znajdź te wpisy meta-data:

   <meta-data
       android:name="com.google.android.ar.API_KEY"
       android:value="PLACEHOLDER_API_KEY" />
   
   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="PLACEHOLDER_API_KEY" />
   

3. Zastąp PLACEHOLDER_API_KEY kluczem interfejsu API utworzonym w projekcie w chmurze Google.

Wartość przechowywana w com.google.android.ar.API_KEY autoryzuje tę aplikację do korzystania z interfejsu Geospatial API, a wartość przechowywana w com.google.android.geo.API_KEY autoryzuje tę aplikację do korzystania z pakietu SDK Map Google.

Weryfikacja projektu

Upewnij się, że projekt jest gotowy. Uruchom aplikację w Android Studio. Powinien być widoczny obraz z kamery oraz działająca mapa u dołu ekranu.

3. Określanie pozycji użytkownika

W tym kroku dodasz kod do przykładowego projektu, aby rozpocząć korzystanie z interfejsu Geospatial API.

Skonfiguruj sesję ARCore tak, aby korzystała z interfejsu Geospatial API

Aby uzyskać dane geoprzestrzenne, musisz włączyć interfejs Geospatial API. Zmień wartość GeospatialMode w konfiguracji sesji na ENABLED, modyfikując funkcję configureSession w HelloGeoActivity.kt:

fun configureSession(session: Session) {
  session.configure(
    session.config.apply {
      // Enable Geospatial Mode.
      geospatialMode = Config.GeospatialMode.ENABLED
    }
  )
}

Gdy tryb przestrzenny jest ENABLED, aplikacja może uzyskiwać informacje przestrzenne.

Wysyłanie żądań danych do interfejsu Geospatial API

W pliku HelloGeoRenderer.kt znajdź ten wiersz:

// TODO: Obtain Geospatial information and display it on the map.

Sprawdź, czy obiekt Earth jest dostępny. Wtedy ma trackingState TrackingState.ENABLED.

val earth = session.earth
if (earth?.trackingState == TrackingState.TRACKING) {
  // TODO: the Earth object may be used here.
}

Pod TODO wyślij do ARCore prośbę o informacje geoprzestrzenne. Dodaj ten wiersz:

val cameraGeospatialPose = earth.cameraGeospatialPose

Otrzymasz GeospatialPose, który zawiera te informacje:

• Lokalizacja wyrażona w szerokości i długości geograficznej. Podawana jest też szacunkowa dokładność lokalizacji.
• wysokość bezwzględną i szacunkową dokładność wysokości bezwzględnej;
• kierunek, czyli przybliżone określenie kierunku, w którym jest zwrócone urządzenie, oraz szacunkową dokładność tego kierunku;

Wyświetlanie informacji o położeniu na mapie

Możesz użyć GeospatialPose przechowywanego w cameraGeospatialPose, aby przenieść na mapie znacznik wskazujący miejsce, w którym znajduje się użytkownik. Kontynuuj od miejsca, w którym skończyłeś(-aś), i dodaj:

activity.view.mapView?.updateMapPosition(
  latitude = cameraGeospatialPose.latitude,
  longitude = cameraGeospatialPose.longitude,
  heading = cameraGeospatialPose.heading
)

Ta funkcja stale aktualizuje pozycję mapy za pomocą wartości uzyskanych z interfejsu Geospatial API.

Wypróbuj

W Android Studio kliknij Play. Podnieś urządzenie i przesuwaj nim, aby ARCore mogło rozpocząć śledzenie. Po chwili na mapie powinien pojawić się zielony znacznik. Ten znacznik obraca się, gdy rozglądasz się po okolicy. Powinna też wskazywać właściwy kierunek: gdy stoisz twarzą na północ, strzałka również powinna wskazywać północ.

4. Umieszczanie kotwicy za pomocą współrzędnych geograficznych

Interfejs Geospatial API może umieszczać kotwice w dowolnej parze współrzędnych i dowolnym obrocie w świecie rzeczywistym. Dzięki temu użytkownicy mogą zobaczyć przypięte treści, gdy odwiedzą określone lokalizacje.

W tym kroku dodasz możliwość umieszczania kotwicy przez kliknięcie mapy.

Ustawianie działania po dotknięciu mapy

Projekt zawiera funkcję onMapClick, która jest wywoływana z szerokością i długością geograficzną po kliknięciu fragmentu mapy. Znajdź funkcję onMapClick w pliku HelloGeoRenderer.kt.

Sprawdź, czy obiekt Earth może być używany

Przed utworzeniem kotwic na Ziemi upewnij się, że właściwość TrackingState obiektu Ziemi ma wartość TRACKING, co oznacza, że pozycja Ziemi jest znana. Sprawdź też, czy jego EarthState ma wartość ENABLED, co oznacza, że nie wystąpiły żadne problemy z interfejsem Geospatial API. Dodaj te wiersze wewnątrz onMapClick:

val earth = session?.earth ?: return
if (earth.trackingState != TrackingState.TRACKING) {
  return
}

Określ położenie nowego punktu zakotwiczenia.

Po potwierdzeniu, że obiekt Ziemi jest śledzony, odłącz poprzedni element earthAnchor, jeśli istnieje. W kolejnych krokach zastąpisz znak earthAnchor nowym kotwiczeniem:

earthAnchor?.detach()

Następnie użyj ikony cameraGeospatialPose, aby określić wysokość nowego punktu. Użyj pary współrzędnych uzyskanych po kliknięciu mapy jako pozycji kotwicy.

// Place the earth anchor at the same altitude as that of the camera to make it easier to view.
val altitude = earth.cameraGeospatialPose.altitude - 1
// The rotation quaternion of the anchor in the East-Up-South (EUS) coordinate system.
val qx = 0f
val qy = 0f
val qz = 0f
val qw = 1f
earthAnchor =
  earth.createAnchor(latLng.latitude, latLng.longitude, altitude, qx, qy, qz, qw)

createAnchor tworzy Anchor przypięty do współrzędnych geodezyjnych z określonym obrotem. Ten punkt zakotwiczenia próbuje zachować stabilność i pozostać w określonych współrzędnych i na określonej wysokości.

Zmienne [qx, qy, qz, qw] określają obrót punktu zakotwiczenia wyrażony w kwaternionach w układzie współrzędnych wschód-góra-południe (EUS). Do obracania punktu zakotwiczenia używasz różnych wartości, ale w tym przykładzie użyj kwaternionu jednostkowego do domyślnego obrotu. Jednostkowa kwaternionowa rotacja ma punkt zakotwiczenia zorientowany w taki sposób, że oś X+ jest skierowana na wschód, oś Y+ w górę od środka Ziemi, a oś Z+ na południe.

Wyświetlanie umieszczonego znacznika na mapie

Na koniec przesuń nowy znacznik, który wskazuje miejsce, w którym został umieszczony:

activity.view.mapView?.earthMarker?.apply {
  position = latLng
  isVisible = true
}

Wypróbuj

W Android Studio kliknij Play. Podnieś urządzenie i poruszaj nim, aby pomóc ARCore w ustaleniu śledzenia. Po chwili na mapie powinien pojawić się zielony znacznik wskazujący Twoją bieżącą pozycję.

Kliknięcie mapy powoduje użycie interfejsu Geospatial API do umieszczenia kotwicy, która jest przypisana do rzeczywistej lokalizacji. Spróbuj umieścić punkt blisko bieżącej lokalizacji, aby był widoczny w widoku AR. Powinien pozostawać stabilny podczas poruszania się po otoczeniu.

5. Podsumowanie

Z tego ćwiczenia z programowania dowiedziałeś się, jak używać interfejsu Geospatial API do tworzenia prostych doświadczeń AR powiązanych ze światem rzeczywistym.

Omówione zagadnienia

• Jak skonfigurować projekt Google Cloud z włączonym interfejsem Geospatial API.
• Jak uzyskać informacje geoprzestrzenne w projekcie ARCore i wyświetlić je na mapie.
• Jak umieścić kotwicę w rzeczywistym świecie za pomocą pozycjonowania geograficznego.

Dodatkowe materiały

Więcej informacji o pojęciach geograficznych i pakietach SDK używanych w tym samouczku znajdziesz w tych dodatkowych materiałach:

• Dokumentacja interfejsu ARCore Geospatial API
• World Geodetic System (WGS)
• Mapy Google SDK na Androida