Przewodnik dla programistów Cloud Anchors dla pakietu Android NDK (C)

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:

// Create a new ARCore session.
ArSession* session = NULL;
CHECK(ArSession_create(env, context, &session) == AR_SUCCESS);

// Create a session config.
ArConfig* config = NULL;
ArConfig_create(session, &config);
ArSession_getConfig(session, config);

// Enable Cloud Anchor mode.
ArConfig_setCloudAnchorMode(session, config,
                            AR_CLOUD_ANCHOR_MODE_ENABLED);

// Configure the session.
ArSession_configure(session, config);
ArConfig_destroy(config);

Hostowanie Cloud Anchor

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

Sprawdzanie jakości mapowania punktów funkcji

ArFeatureMapQuality 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 ArSession_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 ArSession_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 ArFuture_cancel(). Aby zatrzymać śledzenie i zapomnieć o rozwiązanym już punkcie Cloud Anchor, zadzwoń pod numer ArAnchor_detach(). Odwołania do kotwicy muszą być zwalniane osobno przez wywołanie funkcji ArAnchor_release().

Sprawdzanie stanu wyniku operacji Cloud Anchor

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

Wartość Opis
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND Rozwiązywanie nie powiodło się, ponieważ interfejs ARCore API nie mógł znaleźć podanego identyfikatora Cloud Anchor.
AR_CLOUD_ANCHOR_STATE_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.
AR_CLOUD_ANCHOR_STATE_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.
AR_CLOUD_ANCHOR_STATE_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.
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED Zobacz Rozwiązywanie problemów z autoryzacją interfejsu ARCore API.
AR_CLOUD_ANCHOR_STATE_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.
AR_CLOUD_ANCHOR_STATE_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.
AR_CLOUD_ANCHOR_STATE_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.
AR_CLOUD_ANCHOR_STATE_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?