Przewodnik dla programistów Cloud Anchors dla Unity (AR Foundation)

Dowiedz się, jak używać punktów zakotwiczenia w chmurze w swoich aplikacjach.

Wymagania wstępne

Zanim przejdziesz dalej, upewnij się, że rozumiesz podstawowe zagadnienia związane z rozszerzoną rzeczywistością oraz że wiesz, jak skonfigurować sesję ARCore.

Jeśli nie znasz jeszcze Cloud Anchors, dowiedz się, jak działają ankre i Cloud Anchors.

Włącz interfejs ARCore API

Zanim użyjesz w aplikacji punktów orientacyjnych w chmurze, musisz najpierw włączyć w niej interfejs ARCore API.

Włączanie funkcji Cloud Anchor w konfiguracji sesji

Po włączeniu funkcji Cloud Anchors w aplikacji włącz funkcje Cloud Anchors w konfiguracji sesji AR, aby aplikacja mogła komunikować się z interfejsem ARCore API:

Hostowanie Cloud Anchor

Gospodarz rozpoczyna rozmowę od połączenia z numerem ARAnchorManager.HostCloudAnchorAsync(). ARCore prześle dane wizualne, pozy urządzenia i pozycję kotwicy do interfejsu ARCore API. Następnie interfejs API przetwarza te informacje, aby utworzyć mapę funkcji 3D, zwracając w końcu unikalny identyfikator Cloud Anchor dla kotwicy na urządzeniu.

Czas życia hostowanej kotwicy możesz też przedłużyć za pomocą interfejsu ARCore Cloud Anchor Management API.

Aby hostować Cloud Anchor w aplikacji, wykonaj te czynności:

  1. Zadzwoń pod numer ARAnchorManager.HostCloudAnchorAsync().
  2. Uruchom coroutine, aby zaczekać, aż obietnica zwróci wynik. Więcej informacji znajdziesz w artykule Coroutines in Unity (Coroutines w Unity).
  3. Sprawdź stan wyniku, aby określić, czy operacja się powiodła, lub zinterpretuj kod błędu, jeśli operacja się nie udała.
  4. Udostępnij wynikowy identyfikator Cloud Anchor innym klientom i użyj go do rozpoznania elementu Cloud Anchor z usługą ARAnchorManagerExtensions.ResolveCloudAnchorAsync().

Sprawdzanie jakości mapowania punktów funkcji

ARCoreExtensions.FeatureMapQuality wskazuje jakość punktów cech zarejestrowanych przez ARCore w ciągu ostatnich kilku sekund przy danej pozycji kamery. Punkty kotwiczenia w chmurze hostowane przy użyciu funkcji o wyższej jakości są zwykle określane z większą dokładnością. Użyj wartości ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting(), aby uzyskać szacowaną jakość mapy cech dla danej pozycji kamery.

Wartość Opis
Insufficient Jakość punktów charakterystycznych zidentyfikowanych na podstawie pozy w ciągu kilku ostatnich sekund jest niska. Ten stan wskazuje, że ARCore prawdopodobnie będzie miało większe trudności z rozpoznaniem punktu Cloud Anchor. Zachęć użytkownika do przeniesienia urządzenia, aby można było wyświetlić wybraną pozycję uchwytu Cloud Anchor pod różnymi kątami.
Sufficient Jakość punktów funkcji zidentyfikowanych na podstawie pozy w ciągu kilku ostatnich sekund prawdopodobnie wystarczy, aby ARCore mogła poprawnie rozpoznać punkt kotwiczenia w chmurze, choć dokładność rozpoznanej pozycji może być mniejsza. Zachęć użytkownika do przeniesienia urządzenia tak, aby punkt zakotwiczenia w chmurze, który chce hostować, był widoczny pod różnymi kątami.
Good Jakość punktów cech zidentyfikowanych w pozycji w ciągu ostatnich kilku sekund jest prawdopodobnie wystarczająca, aby ARCore mogła z dużą dokładnością rozpoznać punkt zakotwiczenia w chmurze.

Rozwiązywanie wcześniej hostowanej kotwicy

Aby rozwiązać hostowany punkt Cloud Anchor, zadzwoń pod numer ARAnchorManagerExtensions.ResolveCloudAnchorAsync(). Interfejs ARCore API okresowo porównuje wizualne cechy sceny z mapą cech 3D kotwicy, aby określić pozycję i orientację użytkownika względem kotwicy. Po znalezieniu dopasowania interfejs API zwraca pozę hostowanego Cloud Anchora.

Możesz inicjować rozwiązywanie wielu punktów zakotwiczenia w chmurze w kolejności. Możesz jednocześnie wykonywać do 40 operacji Cloud Anchor.

Anulowanie operacji i usuwanie usługi Cloud Anchor

ARCloudAnchor.OnDestroy() jest wywoływany automatycznie, gdy komponent ARCloudAnchor zostanie usunięty z obiektu gry, który go zawiera. Spowoduje to odłączenie i zwolnienie natywnego obiektu Cloud Anchor.

Sprawdzanie stanu wyniku operacji Cloud Anchor

Użyj CloudAnchorState, aby sprawdzić stan wyniku operacji hostingu lub rozwiązywania, w tym błędów.

Wartość Opis
ErrorResolvingCloudIdNotFound Rozwiązywanie nie powiodło się, ponieważ interfejs ARCore API nie mógł znaleźć podanego identyfikatora Cloud Anchor.
ErrorHostingDatasetProcessingFailed Hosting nie powiódł się, ponieważ serwer nie mógł przetworzyć zbioru danych dla danego kotwicy. Spróbuj ponownie, gdy urządzenie zbierze więcej danych o środowisku.
ErrorHostingServiceUnavailable Nie udało się połączyć z interfejsem ARCore API. Możliwych jest kilka przyczyn takiej sytuacji. Urządzenie może być w trybie samolotowym lub nie mieć połączenia z internetem. żądanie wysłane na serwer mogło przekroczyć limit czasu bez odpowiedzi; Może to być spowodowane słabą jakością połączenia sieciowego, brakiem dostępu do DNS, problemami z zaporą sieciową lub innymi czynnikami, które mogą wpływać na możliwość połączenia urządzenia z interfejsem ARCore API.
ErrorInternal Zadanie hostingu lub rozwiązywania tej kotwicy zakończyło się błędem wewnętrznym. Aplikacja nie powinna próbować naprawić tego błędu.
ErrorNotAuthorized Aplikacja nie może komunikować się z interfejsem ARCore API z powodu nieprawidłowego autoryzowania. Sprawdź Ustawienia projektu > XR > Rozszerzenia ARCore, aby sprawdzić, czy jest to prawidłowa strategia autoryzacji.
ErrorResolvingPackageTooNew Nie udało się rozwiązać problemu Cloud Anchor, ponieważ pakiet rozszerzeń ARCore użyty do rozwiązania Cloud Anchor jest nowszy i niezgodny z wersją używaną do hostowania tego elementu.
ErrorResolvingPackageTooOld Nie udało się rozwiązać punktu Cloud Anchor, ponieważ pakiet rozszerzeń ARCore użyty do rozwiązania punktu Cloud Anchor jest starszy i niezgodny z wersją używaną do jego hostowania.
ErrorResourceExhausted Aplikacja wyczerpała limit żądań przydzielony danemu projektowi Google Cloud. W Google Developers Console możesz poprosić o dodatkową pulę interfejsu ARCore API dla swojego projektu.
Success Zadanie hostingu lub rozwiązywania tej kotwicy zostało ukończone.

Limity interfejsu API dotyczące żądań hosta i rozwiązywania

Interfejs ARCore API ma te limity przepustowości żądań:

Typ limitu Maksimum Czas trwania Dotyczy:
Liczba kotwic bez ograniczeń Nie dotyczy projekt
Żądania hosta kotwicy 30 minuta Adres IP i projekt
Anuluj prośby o rozwiązanie 300 minuta Adres IP i projekt

Sprawdzone metody zapewnienia wygody użytkowników

Aby zapewnić użytkownikom dobre wrażenia z korzystania z aplikacji, poproś ich o wykonanie tych czynności:

  • Poczekaj kilka sekund od rozpoczęcia sesji, zanim spróbujesz umieścić kotwicę (np. przez umieszczenie obiektu). Dzięki temu śledzenie ustabilizuje się po pewnym czasie.
  • Wybierając lokalizację, w której ma się wyświetlać reklama zakotwiczona, staraj się znaleźć obszar z elementami wizualnymi, które łatwo odróżnić od innych. Aby uzyskać jak najlepszy wynik, unikaj powierzchni odbijających światło oraz bez elementów wizualnych, takich jak puste białe ściany.

  • Trzymaj kamerę skierowaną na punkt zainteresowania i porusz urządzenie wokół tego punktu, aby stworzyć mapę otoczenia z różnych kątów, zachowując mniej więcej tę samą odległość fizyczną. Pomoże to uzyskać więcej danych wizualnych i zwiększyć rozdzielczość.

  • Podczas hostowania i rozwiązywania punktów Cloud Anchors upewnij się, że w środowisku rzeczywistym jest wystarczające oświetlenie.

Zasady wycofywania

  • Aplikacje utworzone za pomocą pakietu ARCore SDK w wersji 1.12.0 lub nowszej podlegają zasadom wycofywania interfejsu Cloud Anchor API.
  • Aplikacje utworzone za pomocą pakietu SDK ARCore w wersji 1.11.0 lub starszej nie mogą hostować ani rozwiązywać punktów Cloud Anchors, ponieważ pakiet SDK korzysta ze starszego, przestarzałego interfejsu ARCore API.

Co dalej?