Przewodnik dla programistów Cloud Anchors dla Androida (Kotlin/Java)

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 dopiero zaczynasz korzystać z 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:

Java

Config config = new Config(session);
config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED);
session.configure(config);

Kotlin

val config = Config(session)
config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED
session.configure(config)

Hostowanie Cloud Anchor

Gospodarz rozpoczyna rozmowę od zadzwonienia pod numer 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.

Możesz też wydłużyć czas trwania hostowanego kotwicy za pomocą interfejsu ARCore Cloud Anchor Management API.

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

  1. Zadzwoń pod numer hostCloudAnchorAsync().
  2. Poczekaj na połączenie zwrotne lub sprawdzaj stan Future, aż się zakończy.
  3. Sprawdź stan wyniku, aby określić, czy operacja zakończyła się sukcesem, czy niepowodzeniem. W tym drugim przypadku możesz zinterpretować kod błędu.
  4. Udostępnij identyfikator Cloud Anchor innym klientom i użyj go do rozwiązania Cloud Anchor za pomocą funkcji resolveCloudAnchorAsync().

Sprawdzanie jakości mapowania punktów funkcji

Session.FeatureMapQuality wskazuje jakość punktów funkcji zarejestrowanych przez ARCore w ciągu kilku ostatnich sekund od danej pozycji kamery. Punkty kotwiczenia w chmurze hostowane przy użyciu funkcji o wyższej jakości są ogólnie bardziej dokładne. Użyj wartości Session.estimateFeatureMapQualityForHosting(), aby uzyskać szacunkową jakość mapy cech dla danej pozycji kamery.

Wartość Opis
INSUFFICIENT Jakość punktów cech 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 jest prawdopodobnie wystarczająca, aby ARCore mógł poprawnie rozpoznać punkt kotwiczenia w chmurze, choć dokładność rozpoznanej pozycji może być mniejsza. Zachęć użytkownika do przeniesienia urządzenia, aby można było wyświetlić wybraną pozycję uchwytu Cloud Anchor pod różnymi kątami.
GOOD Jakość punktów funkcji zidentyfikowanych na podstawie pozy w ciągu kilku ostatnich sekund jest prawdopodobnie wystarczająca, aby ARCore mogła z wysoką dokładnością rozpoznać punkt Cloud Anchor.

Rozwiązywanie wcześniej hostowanego kotwicy

Aby rozwiązać hostowany punkt Cloud Anchor, zadzwoń pod numer 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 lub usuwanie łącznika Cloud Anchor

Aby anulować oczekującą operację Cloud Anchor, zadzwoń pod numer cancel(). Aby usunąć z aplikacji już rozwiązany punkt Cloud Anchor, wywołaj funkcję detach().

Sprawdzanie stanu wyniku operacji Cloud Anchor

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

Wartość Opis
ERROR_CLOUD_ID_NOT_FOUND Rozwiązywanie nie powiodło się, ponieważ interfejs ARCore API nie mógł znaleźć podanego identyfikatora Cloud Anchor.
ERROR_HOSTING_DATASET_PROCESSING_FAILED 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 z otoczenia.
ERROR_HOSTING_SERVICE_UNAVAILABLE 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.
ERROR_INTERNAL zadanie hostingowe lub zadanie rozwiązywania dotyczące tego kotwicy zostało zakończone z błędem wewnętrznym; Aplikacja nie powinna próbować odzyskać po tym błędzie.
ERROR_NOT_AUTHORIZED Autoryzacja aplikacji jest nieprawidłowa. Zobacz Rozwiązywanie problemów z autoryzacją interfejsu ARCore API.
ERROR_RESOLVING_SDK_VERSION_TOO_NEW Nie udało się rozwiązać punktu zakotwiczenia Cloud Anchor, ponieważ wersja pakietu SDK użyta do rozwiązania punktu zakotwiczenia jest nowsza i niezgodna z wersją używaną do jego hostowania.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD Nie udało się rozwiązać punktu Cloud Anchor, ponieważ wersja pakietu SDK użyta do rozwiązania punktu jest starsza i niezgodna z wersją używaną do jego hostowania.
ERROR_RESOURCE_EXHAUSTED 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 dotyczące tego kotwicy zostało wykonane.

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
Prośby o zakotwiczenie hosta 30 minuta Adres IP i projekt
Anuluj resolve 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). Daje to śledzącemu urządzeniu czas na stabilizację.
  • Wybierając lokalizację, w której ma się znajdować kotwica, spróbuj znaleźć obszar z elementami wizualnymi, które są łatwe do odróżnienia od siebie. Aby uzyskać najlepsze wyniki, unikaj powierzchni odbijających światło lub powierzchni 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 z starszego, przestarzałego interfejsu ARCore API.

Co dalej?