ARCore Geospatial Creator for Unity umożliwia wyświetlanie podglądu treści geoprzestrzennych w edytorze Unity poprzez wyświetlanie danych z Map Google w nowym formacie kafelków 3D. Dzięki temu możesz zobaczyć, gdzie treści będą umieszczone w świecie rzeczywistym podczas tworzenia aplikacji.
Kreator obiektów geoprzestrzennych jest dostępny w ramach rozszerzeń ARCore dla AR Foundation. Z tego przewodnika dowiesz się, jak używać narzędzia Geospatial Creator w Unity do dodawania treści AR związanych z geoprzestrzenią do aplikacji ARCore Geospatial Sample.
Jeśli masz już aplikację, której chcesz używać zamiast Geospatial Sample, musisz najpierw zapoznać się z naszym przewodnikiem dla deweloperów Geospatial w Unity. Po skonfigurowaniu aplikacji do korzystania z interfejsu Geospatial API przejdź do kroku Dodaj wymagane zależności poniżej i kontynuuj od tego miejsca.
Wymagania wstępne
Aby skonfigurować środowisko Unity do tworzenia projektów AR, postępuj zgodnie z instrukcjami w artykule „Wprowadzenie do rozszerzeń ARCore dla AR Foundation”.
Rozszerzenia ARCore obsługują starsze wersje Unity, ale Geospatial Creator wymaga Unity w wersji 2021.3 lub nowszej.
Autoryzacja interfejsu API
Aby korzystać z interfejsu ARCore Geospatial API i interfejsu Google Map Tiles API, musisz skonfigurować dostęp do interfejsu API.
Google Map Tiles API
Interfejs Map Tiles API udostępnia fotorealistyczną reprezentację 3D obsługiwanych lokalizacji. Będziemy używać tych kafelków w edytorze Unity, aby wyświetlać podgląd obszaru wokół sceny AR.
Aby włączyć interfejs API i dowiedzieć się więcej o fragmentach mapy, odwiedź stronę interfejsu Map Tiles API.
ARCore Geospatial API
Interfejs ARCore Geospatial API jest używany przez aplikację w czasie działania do tworzenia i obsługi kotwic przestrzennych.
Aby włączyć interfejsy Geospatial API, skonfiguruj ARCore API w swojej aplikacji. Możesz użyć metody autoryzacji bez klucza (zalecana) lub klucza API.
Rozszerzanie przykładowej aplikacji Geospatial
W tym przewodniku pokażemy, jak za pomocą narzędzia Geospatial Creator dodać treści przestrzenne do przykładowej aplikacji ARCore Geospatial.
Konfigurowanie próbki geoprzestrzennej
Najpierw zapoznaj się z aplikacją ARCore Geospatial Sample. W nowym projekcie Unity otwórz Menedżera pakietów Unity i wybierz pakiet ARCore Extensions. W panelu szczegółów Menedżera pakietów rozwiń Przykłady i zaimportuj przykład przestrzenny do projektu Unity.
Zanim uruchomisz aplikację, musisz włączyć w projekcie ARCore i funkcje przestrzenne. Kliknij Edytuj > Ustawienia projektu... > Zarządzanie wtyczkami XR. Zaznacz odpowiednie pola, aby włączyć dostawcę wtyczki ARCore na Androida lub dostawcę wtyczki ARKit na iOS.
Następnie kliknij Edytuj > Ustawienia projektu… > XR Plug-in Management otwórz panel ARCore Extensions. Sprawdź, czy pole „Geoprzestrzenne” jest zaznaczone (nie musisz jeszcze włączać narzędzia Geospatial Creator) i wpisz dane logowania do interfejsu API. Więcej informacji znajdziesz w dokumentacji „Włączanie interfejsu Geospatial Unity API” na Android i iOS.
Istnieje kilka innych ustawień odtwarzacza specyficznych dla platformy, które są wymagane w przypadku każdej aplikacji Unity korzystającej z ARCore. Wymagane zmiany znajdziesz w sekcji Konfigurowanie ustawień odtwarzacza w naszej dokumentacji.
W tym momencie w scenie nie ma żadnych obiektów gry poza tymi, które są wymagane do uruchomienia przykładu przestrzennego. To dobry moment, aby skompilować i uruchomić aplikację. Jeśli została prawidłowo skonfigurowana, w czasie działania będzie wyświetlać widok z kamery urządzenia. W miarę przemieszczania się dokładność geoprzestrzenna wyświetlana u góry ekranu będzie się zwiększać. Dotykając ekranu, utworzysz przestrzenne punkty zakotwiczenia, które pozostaną w swojej pierwotnej lokalizacji, gdy będziesz się poruszać.
Następnie pokażemy, jak za pomocą narzędzia Geospatial Creator tworzyć i wizualizować zaawansowane treści AR w Edytorze Unity. Te treści będą wyświetlane w aplikacji w określonych lokalizacjach na świecie (szerokość i długość geograficzna).
Dodawanie wymaganych zależności
Geospatial Creator korzysta z pakietu Unity innej firmy o nazwie Cesium, aby renderować kafelki Map Google w oknie sceny edytora Unity. Zanim włączysz funkcje Geospatial Creator, dodaj do projektu pakiet Cesium.
Zalecamy zainstalowanie najnowszej wersji pakietu Cesium for Unity ze strony GitHub Cesium:
- Pobierz najnowszą wersję wstępnie skompilowanego pakietu
.tgzCesium for Unity ze strony GitHub Releases. Obecna zalecana wersja pakietu Cesium for Unity to 1.1.0. - Otwórz Menedżera pakietów Unity, klikając menu „Window” (Okno) w Unity, a następnie wybierając „Package Manager” (Menedżer pakietów).
- Kliknij ikonę „+” i wybierz „Add package from tarball” (Dodaj pakiet z pliku tar).
- Wybierz plik .tgz Cesium for Unity pobrany w kroku 1.
- Może pojawić się prośba o zainstalowanie dodatkowych zależności, takich jak Text Mesh Pro.
Włączanie Geospatial Creator
Możesz teraz włączyć Kreatora obiektów geoprzestrzennych:
- W oknie dialogowym Ustawienia kompilacji upewnij się, że wybrana platforma to „Android” lub „iOS”. Funkcje Geospatial Creator nie są obecnie dostępne na innych platformach.
- Kliknij Ustawienia projektu > Zarządzanie wtyczkami XR > Rozszerzenia ARCore.
- Jeśli w poprzednim kroku nie ustawiono kluczy interfejsu API ARCore na Androida lub iOS, zrób to teraz.
- Włącz przełączniki „Geoprzestrzenne” i „Geospatial Creator”. Po kliknięciu przełącznika włączającego Kreator obiektów geoprzestrzennych wyświetli się niemodalny kreator, który potwierdzi, że Twój projekt jest zgodny z Kreatorem obiektów geoprzestrzennych.
- W kreatorze kliknij „Zakończ”.
Po zakończeniu pracy kreatora Unity uruchomi kompilację skryptów. Zanim przejdziesz dalej, poczekaj na zakończenie ponownej kompilacji. (Jeśli wybrana platforma nie jest „Androidem” ani „iOS-em”, przełącz się na jedną z nich).
Dodawanie źródła Geospatial Creator za pomocą kafelków mapy
Scena musi zawierać dokładnie 1 obiekt „Geospatial Creator Origin”. Ten obiekt jest używany jako punkt odniesienia do przekształcania rzeczywistych wartości szerokości i długości geograficznej oraz wysokości na współrzędne gry w Unity.
Aby dodać do sceny punkt początkowy Geospatial Creator, wybierz Game Object > XR > Geospatial Creator Origin. Nowo utworzony obiekt wymaga georeferencji, która łączy konkretną szerokość i długość geograficzną oraz wysokość z położeniem źródła w współrzędnych gry. W panelu Inspektor w Geospatial Creator Origin dodaj georeferencję, klikając przycisk Add Cesium Georeference Component (Dodaj komponent georeferencji Cesium).
Oprócz tego, że jest punktem odniesienia dla obiektów AR, CesiumGeoreference dodaje do sceny obiekt Cesium 3D Tileset. Ten obiekt będzie renderować kafelki Map Google w widoku sceny edytora, co pozwoli Ci zobaczyć, w którym miejscu na świecie będą wyświetlane Twoje treści AR. W inspektorze źródła narzędzia Geospatial Creator znajduje się pole, w którym możesz dodać klucz interfejsu Map Tiles API, który został wcześniej skonfigurowany. Po ustawieniu tego klucza w widoku Scena powinny się wczytać kafelki mapy.
Teraz zmień pola szerokości, długości i wysokości geograficznej, aby znajdowały się w pobliżu miejsca, w którym chcesz wyświetlać treści AR w aplikacji.
Widok sceny w Edytorze powinien teraz wyświetlać kafelki mapy w określonej szerokości i długości geograficznej punktu początkowego. Zakładamy, że w czasie działania aplikacji będzie ona korzystać z kamery AR, więc narzędzie Geospatial Creator skonfigurowało już obiekt Cesium 3D Map Tileset za pomocą tagu „EditorOnly”. Z tego powodu kafelki nie będą pobierane ani renderowane w czasie działania gry. Można to zmienić w inspektorze obiektu Cesium3DTileset. Więcej informacji o obiektach Georeference i 3D Tileset w Cesium znajdziesz w dokumentacji Cesium dla Unity.
Dodawanie i umieszczanie kotwicy Kreatora obiektów geoprzestrzennych
Możesz teraz umieścić treści AR w scenie. Kliknij GameObject > XR > Geospatial Creator Anchor, aby dodać kotwicę do hierarchii sceny. W inspektorze kotwicy możesz określić dokładną szerokość i długość geograficzną oraz wysokość. Transformacja obiektu zostanie natychmiast zaktualizowana do prawidłowej pozycji w scenie, dzięki czemu zobaczysz dokładnie, gdzie na świecie pojawi się obiekt.
Podczas dostosowywania szerokości i długości geograficznej punktu zakotwiczenia wybierz miejsce, które znajduje się w pobliżu, aby w czasie działania aplikacji móc sprawdzić, czy jest ono we właściwym miejscu. Podczas ustawiania wysokości kotwicy Geospatial Creator Anchor masz 3 możliwości:
- Teren umieszcza kotwicę na poziomie gruntu na podstawie podanej szerokości i długości geograficznej. Poziom gruntu jest określany w czasie działania przez system pozycjonowania wizualnego. Jeśli dopiero zaczynasz korzystać z interfejsów Geospatial API w ARCore, wybierz „Terrain” (Teren), ponieważ kotwica zostanie umieszczona bezpośrednio na ziemi z dużą dokładnością pionową. Pole „Przesunięcie wysokości” umożliwia umieszczenie punktu zakotwiczenia powyżej lub poniżej poziomu gruntu o stałą wartość wyrażoną w metrach. Na przykład określenie przesunięcia „1,0” spowoduje, że kotwica będzie „unosić się” metr nad terenem.
- Dach umieszcza kotwicę względem szczytu dowolnej konstrukcji o podanej szerokości i długości geograficznej. Podobnie jak w przypadku kotwicy terenu, pole „Przesunięcie wysokości” umożliwia przesuwanie kotwicy w górę lub w dół względem pozycji dachu w metrach.
- WGS84 umieszcza punkt zakotwiczenia na określonej wysokości bezwzględnej w metrach, na podstawie układu współrzędnych WGS84. Umieszczenie obiektu w ten sposób może wymagać prób i błędów, ponieważ wysokość „0” w WSG84 niekoniecznie oznacza średni poziom morza i może nie odpowiadać wysokości podawanej przez GPS. Chociaż szerokość i długość geograficzna renderowanych kafelków 3D jest bardzo dokładna, próba umieszczenia obiektu na poziomie gruntu przy użyciu kafelków 3D jako punktu odniesienia może spowodować błąd wysokości wynoszący nawet kilka metrów.
Więcej informacji o różnych typach kotwic przestrzennych ARCore znajdziesz w przewodniku dla programistów dotyczącym przestrzennych interfejsów API.
Zarówno kotwice terenu, jak i kotwice dachu mają pole WGS84 Altitude (Wysokość WGS84). Ta wartość jest używana tylko w trybie edytora do ustawiania wysokości obiektu w widoku sceny. Wysokość terenu i dachu jest określana tylko w czasie wykonywania, więc pole Wysokość WGS84 umożliwia wizualizację punktu zakotwiczenia na określonej wysokości podczas tworzenia aplikacji. Pole Wysokość WGS84 jest ignorowane w czasie wykonywania w przypadku punktów zakotwiczenia na terenie i dachu.
Dodawanie geometrii do kotwicy
Jeśli teraz skompilujesz i uruchomisz aplikację, nie zobaczysz w niej kotwicy. Dzieje się tak, ponieważ nie jest do niej dołączona żadna geometria. Dodajmy do kotwicy prosty obiekt 3D: w hierarchii sceny kliknij prawym przyciskiem myszy obiekt AR Geospatial Creator Anchor. W menu kontekstowym wybierz Obiekt 3D > Sześcian. W widoku sceny powinien pojawić się szary sześcian jako element podrzędny kotwicy. Jeśli zdecydujesz się zmienić pozycję lub rotację obiektu w edytorze, zalecamy przeniesienie głównego obiektu Anchor zamiast podrzędnego obiektu Cube. Pomoże to zmniejszyć błąd w tłumaczeniu z szerokości i długości geograficznej na współrzędne gry.
Oczywiście do kotwicy możesz też dodać bardziej skomplikowaną geometrię oraz dowolne komponenty i elementy podrzędne.
Tworzenie i uruchamianie aplikacji
Czas zobaczyć swój kotwicę w realnym świecie! Spróbuj skompilować i uruchomić aplikację, a następnie przejdź do miejsca, w którym powinien pojawić się sześcian. Czy to tam jest? Gratulujemy. Możesz już tworzyć bardziej złożone projekty AR za pomocą narzędzia Geospatial Creator.
W razie problemów zapoznaj się z przewodnikiem rozwiązywania problemów.
Teraz jest dobry moment, aby dodać kolejne kotwice przestrzenne AR Creator o różnych geometriach. Eksperymentuj z różnymi punktami zaczepienia na dachu i terenie oraz ich przesunięciami. Dodaj skrypty, aby animować obiekty lub włączyć interakcje z nimi.
Informacje o kotwicach Geospatial Creator i klasie ARGeospatialAnchor
Podczas tworzenia złożonych i interaktywnych projektów AR warto poznać relację między kotwicami narzędzia Geospatial Creator a klasą ARGeospatialAnchor C# w ARCore:
ARGeospatialAnchor
można utworzyć tylko w czasie działania programu, wywołując jedną z funkcji na obiekcie ARAnchorManager. Można je utworzyć dopiero po ustabilizowaniu się sesji AR. Kotwicę Geospatial Creator Anchor można traktować jako symbol zastępczy w scenie, który czeka na gotowość sesji AR do rozpoznania obiektów ARGeospatialAnchor.
Gdy sesja będzie gotowa, element zastępczy automatycznie wywoła funkcję ARAnchorManager, aby utworzyć i rozwiązać ARGeospatialAnchor.
Natychmiast po rozwiązaniu kotwicy czasu wykonania kotwica Geospatial Creator Anchor w hierarchii sceny zostanie dołączona jako element podrzędny do nowego obiektu GameObject.
Oznacza to, że wszystkie komponenty i elementy podrzędne kotwicy Geospatial Creator Anchor staną się podkomponentami lub elementami podrzędnymi nowego obiektu ARGeospatialAnchorGameObject. Na przykład transform pierwotnego kształtu geometrycznego dołączonego do kotwicy Geospatial Creator Anchor będzie dziedziczyć wartość transform z ARGeospatialAnchor, a tym samym zostanie umieszczony w oczekiwanym miejscu w sesji AR w czasie działania.
Jeśli musisz zidentyfikować konkretne obiekty ARGeospatialAnchor GameObject w czasie działania, możesz wyszukać w scenie obiekty, których właściwość name pasuje do kotwicy utworzonej za pomocą narzędzia Geospatial Creator. Jeśli sesja AR jest zainicjowana, parent tego obiektu będzie odpowiednim obiektem ARGeospatialAnchor.
Rozwiązywanie problemów
Dlaczego mój punkt zakotwiczenia się przesuwa?
Szczególnie przy pierwszym uruchomieniu aplikacji możesz zauważyć, że kotwica powoli „dryfuje” lub nagle przeskakuje o kilka metrów. Dzieje się tak, gdy sesja VPS wciąż określa i doprecyzowuje dokładną lokalizację kamery. W miarę jak dokładność w płaszczyźnie poziomej i pionowej poprawia się w kolejnych klatkach, punkt zostaje ponownie narysowany w dokładniejszym miejscu, co daje iluzję ruchu. Możesz renderować obiekt inaczej (lub wcale), dopóki dokładność lokalizacji nie osiągnie określonego progu. Aby to zrobić, możesz wysłać zapytanie do właściwości ARCoreEarthManager.CameraGeospatialPose, aby określić dokładność bieżącej aktualizacji klatki.
Dlaczego mój punkt zakotwiczenia pojawia się na niewłaściwej wysokości?
Jeśli w przypadku kotwic w Geospatial Creator Anchors używasz typu wysokości „Ręcznie”, wysokość kotwicy (w metrach) zostanie ustawiona zgodnie z systemem WGS84. W danej lokalizacji może występować rozbieżność do kilku metrów między pozornym poziomem gruntu widocznym na kafelkach mapy a rzeczywistym poziomem gruntu zgłoszonym przez wizualny system pozycjonowania Google (VPS). Jeśli kotwica przestrzenna wydaje się być nieprawidłowo umieszczona w czasie działania, zalecamy sprawdzenie wysokości VPS osobiście za pomocą nakładki debugowania w przykładowej aplikacji. Następnie możesz zmienić wysokość w edytorze Unity, aby dopasować ją do znanej wysokości VPS w danym miejscu.
Kafelki mapy nie renderują się prawidłowo w widoku sceny w edytorze
Jeśli w widoku sceny widać, że kafelki Cesium3DTileset się wczytują, ale są renderowane w jednolitym kolorze magenta, dodaj do projektu pakiet Shader Graph Unity. Ten pakiet jest wymagany przez Cesium, ale projekty korzystające z wbudowanego renderera Unity nie zawierają go domyślnie.
Aby dodać Shader Graph, otwórz Menedżera pakietów Unity (Window > Package Manager). Upewnij się, że przeglądasz pakiety dostępne w rejestrze pakietów Unity, wybierając „Packages: Unity Registry” (Pakiety: rejestr Unity) w menu u góry okna Package Manager. Wyszukaj com.unity.shadergraph
pakiet i zainstaluj najnowszą wersję. Po wczytaniu pakietu kafelki 3D powinny się ponownie wczytać i prawidłowo renderować w widoku sceny.
Aplikacja wyświetla czarny ekran zamiast widoku z kamery
Potok renderowania uniwersalnego (URP) Unity nie jest domyślnie skonfigurowany dla kamery AR. Jeśli w czasie działania zamiast obrazu z kamery widzisz czarny ekran, musisz dodać AR Background Renderer Feature do każdego renderera URP w scenie.
Aby dodać tę funkcję, wyszukaj w projekcie słowo „renderer”. W przypadku każdego obiektu URP Renderer kliknij przycisk „Add Renderer Feature” (Dodaj funkcję renderowania) w inspektorze i dodaj AR Background Renderer.
Dlaczego kotwice umieszczone daleko od punktu początkowego wydają się nieprawidłowo umieszczone?
Konwersja współrzędnych WGS84 na współrzędne gry w Unity jest obarczona błędem wynikającym z precyzji arytmetyki zmiennoprzecinkowej. Można go zminimalizować, dbając o to, aby punkt początkowy znajdował się w pobliżu kotwic AR. Odległości powyżej 20 km mogą być niedokładne. Jeśli Twoje doświadczenie AR obejmuje duże odległości, zalecamy używanie wielu scen z unikalnym punktem zakotwiczenia w każdej z nich.