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 połączenia z numerem hostCloudAnchorAsync(). ARCore prześle do interfejsu ARCore API dane wizualne, pozycje urządzeń i pozycję kotwicy. 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 się powiodła, lub zinterpretuj kod błędu, jeśli operacja się nie udała.
  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 danego ustawienia 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 Session.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 cech zidentyfikowanych w pozycji w ciągu ostatnich kilku sekund jest prawdopodobnie wystarczająca do rozpoznania przez ARCore rozwiązania Cloud Anchor, choć dokładność ustalenia pozycji będzie prawdopodobnie 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 hostowanej kotwicy

Wywołaj resolveCloudAnchorAsync(), aby rozpoznać hostowaną usługę Cloud Anchor. 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

Wywołaj cancel(), aby anulować oczekującą operację Cloud Anchor. 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 Interfejs ARCore API był nieosiągalny. Możliwych jest kilka przyczyn takiej sytuacji. Urządzenie może być w trybie samolotowym lub nie mieć połączenia z internetem. Możliwe, że upłynął limit czasu żądania wysłanego do serwera i nie otrzymano 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ć naprawić tego błędu.
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ć problemu kotwicy Cloud, ponieważ wersja pakietu SDK użyta do rozwiązania kotwicy jest nowsza od wersji użytej do jej hostowania i niezgodna z nią.
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ń przypisany do danego projektu 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 następujące 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 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). Daje to śledzącemu systemowi czas na stabilizację.
  • Wybierając lokalizację, w której chcesz umieścić kotwicę, poszukaj obszaru z elementami wizualnymi, które są łatwe do odróżnienia od siebie. Aby uzyskać najlepsze wyniki, unikaj powierzchni odbijających światło lub powierzchni, które nie mają żadnych wizualnych cech, takich jak puste białe ściany.

  • Ustaw aparat w centrum zainteresowania i przesuwaj urządzenie w okolicach interesującego Cię miejsca, aby mapować środowisko pod różnymi kątami. Utrzymuj mniej więcej taką samą odległość fizyczną jak w przypadku tej czynności. Dzięki temu uzyskasz więcej danych wizualnych i ułatwisz rozdzielczość.

  • Podczas hostowania i rozwiązywania problemów zakotwiczonych Cloud Anchor upewnij się, że w rzeczywistym środowisku 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?