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

Dowiedz się, jak używać usług zakotwiczonych Cloud we własnych aplikacjach.

Wymagania wstępne

Upewnij się, że znasz podstawowe pojęcia związane z AR. i dowiedz się, jak skonfigurować sesję ARCore, zanim przejdziesz dalej.

Jeśli dopiero zaczynasz korzystać z Cloud Anchors:

  • Upewnij się, że wiesz, jak działają kotwice i Cloud Anchor.
  • Aby poznać wymagania systemowe oraz instrukcje konfiguracji i instalacji, przeczytaj krótki przewodnik dotyczący Cloud Anchors.

Włączanie interfejsu ARCore API

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

Włącz funkcje 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 się komunikować 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 dane wizualne, pozy urządzenia i pozy 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 dokończyć hosting Cloud Anchor, Twoja aplikacja powinna wykonać te czynności:

  1. Zadzwoń pod numer hostCloudAnchorAsync().
  2. Poczekaj na połączenie zwrotne lub sprawdzaj stan Future, aż się zakończy.
  3. Sprawdzanie stanu wyniku , aby określić, czy operacja się powiodła, lub zinterpretować 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: resolveCloudAnchorAsync()

Sprawdź jakość mapowania punktów obiektu

Session.FeatureMapQuality wskazuje jakość punktów cech zarejestrowanych przez ARCore w ciągu ostatnich kilku sekund przy danej pozycji kamery. Punkty dokujące w chmurze hostowane przy użyciu funkcji o wyższej jakości są ogólnie bardziej dokładne. Użyj narzędzia Session.estimateFeatureMapQualityForHosting(), aby uzyskać oszacowanie jakości mapy cech w przypadku danej pozycji aparatu.

Wartość Opis
INSUFFICIENT Jakość punktów cech zidentyfikowanych na podstawie pozycji w ciągu ostatnich kilku 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 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 problemów z hostowaną wcześniej kotwicą

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ć sekwencje dla wielu elementów Cloud Anchor. Możesz jednocześnie wykonywać maksymalnie 40 operacji Cloud Anchor.

Anulowanie operacji i usuwanie usługi 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 Nie udało się rozwiązać problemu, ponieważ interfejs ARCore API nie mógł znaleźć podanego identyfikatora Cloud Anchor.
ERROR_HOSTING_DATASET_PROCESSING_FAILED Nie udało się przeprowadzić hostingu, ponieważ serwer nie może przetworzyć zbioru danych w przypadku danej kotwicy. Spróbuj ponownie, gdy urządzenie zbierze więcej danych o środowisku.
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 hostingu lub rozwiązywania tej kotwicy zakończyło się błędem wewnętrznym. Aplikacja nie powinna próbować naprawić tego błędu.
ERROR_NOT_AUTHORIZED Upoważnienie podane w aplikacji jest nieprawidłowe. 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żywana do rozwiązywania 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 musisz poprosić o zwiększenie limitu dla interfejsu ARCore API w projekcie.
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

Poleć im, aby wykonali te czynności, by zapewnić wygodę korzystania z aplikacji:

  • Zanim spróbujesz umieścić reklamę zakotwiczoną, odczekaj kilka sekund po rozpoczęciu sesji (umieszczając obiekt itp.). Dzięki temu śledzenie ustabilizuje się po pewnym czasie.
  • Wybierając lokalizację, w której chcesz umieścić kotwicę, znajdź obszar z elementami wizualnymi, które są łatwe do odróżnienia od siebie. Aby uzyskać jak najlepszy wynik, unikaj powierzchni odbijających światło oraz bez elementów wizualnych, takich jak puste białe ściany.

  • Trzymaj kamerę tak, aby znalazł się w centrum zainteresowania, i poruszaj urządzeniem wokół siebie w centrum zainteresowania, aby nanieść na mapę środowisko pod różnymi kątami, zachowując przy tym podobną odległość fizyczną. Pomoże to rejestrować więcej danych wizualnych i ułatwi rozwiązywanie problemów.

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

Zasady wycofywania

  • Aplikacje z pakietem ARCore SDK 1.12.0 lub nowszym podlegają zasadom wycofywania interfejsu Cloud Anchor API.
  • Aplikacje utworzone z pakietem SDK ARCore 1.11.0 lub starszym nie mogą hostować ani rozwiązywać punktów Cloud Anchors, ponieważ pakiet SDK korzysta ze starszego, przestarzałego interfejsu ARCore API.

Co dalej?