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

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.

Włączanie interfejsu ARCore API

Zanim zaczniesz używać Cloud Anchors w swojej aplikacji, musisz włączyć w niej interfejs ARCore API.

Włącz funkcje Cloud Anchor w konfiguracji sesji

Po włączeniu funkcji Cloud Anchors w swojej aplikacji włącz je w konfiguracji sesji AR aplikacji, aby umożliwić komunikację 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 kotwicy Cloud

Hosting zaczyna się od wywołania ArSession_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, co ostatecznie zwraca na urządzeniu unikalny identyfikator Cloud Anchor dla kotwicy.

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 ArSession_hostCloudAnchorAsync().
  2. Poczekaj na wywołanie zwrotne lub do czasu zakończenia sprawdzania sprawdzaj stan przyszły.
  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: ArSession_resolveCloudAnchorAsync()

Sprawdź jakość mapowania punktów obiektu

ArFeatureMapQuality wskazuje jakość punktów cech zarejestrowanych przez ARCore w ciągu ostatnich kilku sekund przy danej pozycji kamery. Elementy zakotwiczone w chmurze hostowane przy użyciu funkcji o wyższej jakości są zwykle dokładniej rozpoznawane. Użyj narzędzia ArSession_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 oznacza, że usługa ARCore prawdopodobnie będzie miała większe trudności z rozwiązywaniem Cloud Anchor. Poproś użytkownika o przesunięcie urządzenia tak, aby punkt zakotwiczenia w chmurze, który chce hostować, był widoczny 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. Poproś użytkownika o przesunięcie 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 problemów z hostowaną wcześniej kotwicą

Wywołaj ArSession_resolveCloudAnchorAsync(), aby rozpoznać hostowaną usługę Cloud Anchor. Interfejs ARCore API okresowo porównuje elementy wizualne sceny z mapą funkcji 3D reklamy zakotwiczonej, aby określić położenie i orientację użytkownika względem reklamy zakotwiczonej. Po znalezieniu dopasowania interfejs API zwraca pozycję hostowanej usługi Cloud Anchor.

Możesz inicjować sekwencje dla wielu elementów Cloud Anchor. Jednocześnie może istnieć maksymalnie 40 operacji Cloud Anchor.

Anulowanie operacji i usuwanie usługi Cloud Anchor

Wywołaj ArFuture_cancel(), aby anulować oczekującą operację Cloud Anchor. Wywołaj ArAnchor_detach(), aby zatrzymać śledzenie i zapomnieć rozwiązaną wcześniej kotwicę Cloud Anchor. Odwołania do reklamy zakotwiczonej należy anulować oddzielnie za pomocą wywołania ArAnchor_release().

Sprawdzanie stanu wyniku operacji Cloud Anchor

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

Wartość Opis
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND Nie udało się rozwiązać problemu, ponieważ interfejs ARCore API nie mógł znaleźć podanego identyfikatora Cloud Anchor.
AR_CLOUD_ANCHOR_STATE_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.
AR_CLOUD_ANCHOR_STATE_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ć działającego połączenia z internetem. Możliwe, że upłynął limit czasu żądania wysłanego do serwera i nie otrzymano odpowiedzi. Przyczyną może być nieprawidłowe połączenie sieciowe, niedostępność DNS, problem z zaporą sieciową lub inny problem, który może mieć wpływ na zdolność urządzenia do nawiązania połączenia z interfejsem ARCore API.
AR_CLOUD_ANCHOR_STATE_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.
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED Zobacz Rozwiązywanie problemów z autoryzacją w interfejsie ARCore API.
AR_CLOUD_ANCHOR_STATE_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ą.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD Nie udało się rozwiązać problemu kotwicy Cloud, ponieważ wersja pakietu SDK użyta do rozwiązania kotwicy jest starsza i niezgodna z wersją używaną do hostowania tej kotwicy i jest z nią niezgodna.
AR_CLOUD_ANCHOR_STATE_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.
AR_CLOUD_ANCHOR_STATE_SUCCESS Zadanie hostingu lub rozwiązywania tej kotwicy zostało ukończone.

Limity interfejsu API dotyczące hostów i realizacji żądań

Interfejs ARCore API ma następujące limity przepustowości żądań:

Typ limitu Maksimum Czas trwania Dotyczy:
Liczba reklam zakotwiczonych bez ograniczeń Nie dotyczy projekt
Żądania hosta kotwicy 30 minuta Adres IP i projekt
Rozwiązywanie żądań zakotwiczenia 300 minuta Adres IP i projekt

Sprawdzone metody dbania o wygodę 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 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ę 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 problemów zakotwiczonych Cloud Anchor upewnij się, że w rzeczywistym środowisku 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 za pomocą pakietu SDK ARCore lub starszego nie mogą hostować ani realizować elementów Cloud Anchor, ponieważ pakiet SDK używa starszego, wycofanego interfejsu ARCore API.

Co dalej?