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

Dowiedz się, jak korzystać z kotwic Cloud we własnych aplikacjach.

Wymagania wstępne

Zanim przejdziesz dalej, zapoznaj się z podstawowymi pojęciami dotyczącymi AR i dowiedz się, jak skonfigurować sesję ARCore.

Jeśli dopiero zaczynasz korzystać z Kotwic Cloud, dowiedz się, jak działają kotwice i kotwice w chmurze.

Włącz interfejs ARCore API

Zanim zaczniesz używać Cloud Anchor w swojej aplikacji, musisz włączyć ARCore API w nowym lub istniejącym projekcie Google Cloud Platform. Ta usługa jest odpowiedzialna za przechowywanie, przechowywanie i rozwiązywanie problemów z kotwicami Cloud.

Autoryzowanie aplikacji do wywoływania interfejsu ARCore API

Musisz zezwolić aplikacji na wywoływanie interfejsu ARCore API w celu hostowania i rozwiązywania kotwic Cloud. Aplikacje hostujące i rozwiązujące Cloud Anchor z czasem TTL przekraczającym 1 dzień muszą używać autoryzacji bez klucza.

Autoryzacja bez kluczy

Używaj autoryzacji bez klucza do hostowania i rozwiązywania problemów z kotwicami Cloud z TTL między 1 a 365 dni.

  1. Włącz ARCore API w nowym lub istniejącym projekcie Google Cloud Platform.

  2. Utwórz identyfikator klienta OAuth swojej aplikacji na Androida w konsoli Google Cloud przy użyciu identyfikatora aplikacji i odcisku cyfrowego podpisu SHA-1. Spowoduje to powiązanie aplikacji na Androida z projektem Google Cloud Platform.

    Aby pobrać odcisk cyfrowy certyfikatu podpisywania debugowania:

    • Otwórz panel Gradle w projekcie Android Studio.
    • Otwórz <project-name> > Tasks > android.
    • Uruchom zadanie signingReport.

    • Skopiuj odcisk cyfrowy SHA-1 wariantu debug do pola Odcisk cyfrowy certyfikatu SHA-1 w konsoli Google Cloud.

  3. Uwzględnij com.google.android.gms:play-services-auth:16+ w zależnościach aplikacji.

  4. Jeśli używasz ProGuard, dodaj ją do pliku build.gradle aplikacji

    buildTypes {
  release {
    ...
    proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
  }
}

    Dodaj do pliku proguard-rules.pro swojej aplikacji:

    -keep class com.google.android.gms.common.** { *; }
-keep class com.google.android.gms.auth.** { *; }
-keep class com.google.android.gms.tasks.** { *; }

Autoryzacja klucza interfejsu API

Użyj autoryzacji klucza interfejsu API do hostowania i rozwiązywania problemów z kotwicami Cloud z TTL do 24 godzin (1 dzień).

  1. Włącz ARCore API w nowym lub istniejącym projekcie Google Cloud Platform.
  2. Uzyskaj klucz interfejsu API tego projektu z konsoli Google Cloud.

  3. W Android Studio dodaj do projektu nowy klucz interfejsu API. Umieść klucz interfejsu API w elemencie <meta-data> w elemencie <application> w app/manifests/AndroidManifest.xml:

    <meta-data
   android:name="com.google.android.ar.API_KEY"
   android:value="API_KEY"/>

Włącz możliwości Cloud Anchor w konfiguracji sesji

Po włączeniu funkcji Cloud zakotwiczonych w aplikacji włącz jej funkcje konfiguracji sesji AR, aby mogła ona 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 zakotwiczenia w chmurze

Hosting rozpoczyna się od połączenia z ArSession_hostCloudAnchorAsync(). ARCore prześle dane wizualne, pozycje urządzenia i pozycję kotwicy do interfejsu ARCore API. Interfejs API przetwarza te informacje, aby utworzyć mapę cech 3D. W rezultacie zwraca unikalny identyfikator kotwicy Cloud na urządzeniu.

Możesz też przedłużyć okres ważności hostowanej kotwicy za pomocą interfejsu ARCore Cloud Anchor Management API.

Aby dokończyć hostowanie Cloud Anchor, wykonaj te czynności:

  1. Zadzwoń pod numer ArSession_hostCloudAnchorAsync().
  2. Poczekaj na oddzwonienie lub sprawdzaj stan w przyszłości.
  3. Sprawdź stan wyniku, aby ustalić, czy operacja się udała, lub zinterpretuj kod błędu, jeśli się nie udało.
  4. Udostępnij wynik Cloud zakotwiczenia innym klientom i użyj go, aby rozwiązać problem z kotwicą Cloud w ArSession_resolveCloudAnchorAsync().

Sprawdź jakość mapowania punktów cech

ArFeatureMapQuality wskazuje jakość punktów prezentowanych przez ARCore w ciągu ostatnich kilku sekund od danej pozycji kamery. Rozwiązujemy problem z kotwicami w chmurze obsługiwanymi przez funkcje wyższej jakości. Użyj metody ArSession_estimateFeatureMapQualityForHosting(), aby oszacować jakość mapy funkcji w przypadku danej pozycji.

Wartość Opis
INSUFFICIENT Jakość punktów cech określonych na podstawie pozycji w ciągu ostatnich kilku sekund jest niska. Ten stan wskazuje, że ARCore prawdopodobnie będzie mieć problemy z rozpoznawaniem kotwicy Cloud. Zachęć użytkownika do przeniesienia urządzenia, tak aby pożądana pozycja kotwicy w chmurze była widoczna z różnych kątów.
SUFFICIENT Jakość punktów cech określonych na podstawie pozycji w ciągu ostatnich kilku sekund prawdopodobnie wystarczy do rozwiązania ARCore w celu rozwiązania Cloud Anchor, chociaż dokładność podawanej pozycji będzie prawdopodobnie mniejsza. Zachęć użytkownika do przeniesienia urządzenia, tak aby pożądana pozycja kotwicy w chmurze była widoczna z różnych kątów.
GOOD Jakość punktów cech określonych na podstawie pozycji w ciągu ostatnich kilku sekund jest prawdopodobnie wystarczająca, aby ARCore udało się rozwiązać zadanie Cloud Anchor z dużą dokładnością.

Rozwiązywanie problemów z hostowaną wcześniej kotwicą

Wywołaj ArSession_resolveCloudAnchorAsync(), aby rozwiązać problem z hostowaną chmurą. Interfejs ARCore API okresowo porównuje elementy wizualne ze sceny z mapą funkcji 3D kotwicy, aby określić położenie i orientację użytkownika względem kotwicy. Po znalezieniu dopasowania interfejs API zwraca pozycję hostowanej wiadomości Cloud Anchor.

Możesz zainicjować decyzje dotyczące kilku kotwic Cloud w kolejności. Jednocześnie może być powiązanych maksymalnie 40 działań Cloud Anchor.

Anulowanie operacji lub usuwanie kotwicy Cloud

Wywołaj ArFuture_cancel(), aby anulować oczekującą operację Cloud Anchor. Wywołaj ArAnchor_detach(), aby przestać śledzić i zapomnieć już rozwiązaną chmurę Cloud Anchor. Odwołania do kotwicy muszą być anulowane przez wywołanie ArAnchor_release().

Sprawdzanie stanu wyniku operacji Cloud Anchor

Użyj polecenia ArCloudAnchorState, aby sprawdzić stan operacji hostowania lub rozwiązania problemu, 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 kotwicy Cloud.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED Hostowanie nie powiodło się, ponieważ serwer nie mógł przetworzyć zbioru danych dla danej kotwicy. Spróbuj ponownie, gdy urządzenie zbierze więcej danych ze środowiska.
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 ma połączenia z internetem. Minął limit czasu wysłania żądania do serwera. Nieprawidłowe połączenie sieciowe, niedostępność DNS, problemy z zaporą sieciową lub inne problemy, które mogą mieć wpływ na możliwość połączenia urządzenia z interfejsem ARCore API.
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL Hostowanie lub rozwiązywanie zadania dla tej kotwicy zakończyło się błędem wewnętrznym. Aplikacja nie powinna próbować odzyskać dostępu do tego błędu.
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED Autoryzacja udostępniona przez aplikację jest nieważna.
  • Projekt Google Cloud mógł nie włączyć interfejsu ARCore API lub operacja, którą próbujesz wykonać, jest niedozwolona.
  • Jeśli używasz autoryzacji klucza interfejsu API: klucz interfejsu API w pliku manifestu jest nieprawidłowy, nieautoryzowany lub nie istnieje. Może się też zdarzyć, że klucz interfejsu API jest ograniczony do zestawu aplikacji, które nie obejmują bieżącej.
  • Jeśli korzystasz z autoryzacji bez kluczy: nie udało się utworzyć klienta OAuth.
  • Usługi Google Play nie są zainstalowane, są zbyt stare lub działają nieprawidłowo (np. usługi zabite z powodu zbyt dużego napięcia pamięci).
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW Nie udało się znaleźć Cloud Anchor, ponieważ wersja pakietu SDK, z której można ją odczytać, jest nowsza niż wersja, w której jest hostowana, i niekompatybilna.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD Nie udało się znaleźć Cloud Anchor, ponieważ wersja pakietu SDK, której używa kotwica, jest starsza niż wersja, w której jest hostowana, i niezgodna z tą wersją.
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 dodatkowy limit ARCore API dla Twojego projektu.
AR_CLOUD_ANCHOR_STATE_SUCCESS Hostowanie lub rozwiązanie zadania dla tej kotwicy zostało zakończone.

Limity interfejsów API dla żą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
Żądania zakotwiczenia kotwicy 30 minuty Adres IP i projekt
Żądania zakotwiczenia rozstrzygnięcia 300 minuty Adres IP i projekt

Sprawdzone metody zapewniania wygody użytkownikom

Aby zapewnić użytkownikom pozytywne wrażenia z aplikacji, wykonaj te czynności:

  • Po rozpoczęciu sesji poczekaj kilka sekund, zanim spróbujesz umieścić kotwicę (przez umieszczenie obiektu itp.). Dzięki temu śledzenie ma czas na stabilizację.
  • Wybierając lokalizację na potrzeby kotwicy, znajdź obszar z cechami wizualnymi, które można łatwo odróżnić od siebie. Aby uzyskać najlepsze wyniki, unikaj powierzchni odblaskowych i powierzchni, które nie mają cech wizualnych, takich jak puste białe ściany.

  • Trzymaj aparat wytrenowany w środku zainteresowania i przesuwaj urządzenie wokół niego, aby obrazować otoczenie pod różnymi kątami, zachowując przy tym mniej więcej taką samą odległość fizyczną. Pomoże to w przechwytywaniu większej ilości danych wizualnych i zwiększa dokładność.

  • Zadbaj o wystarczające oświetlenie w rzeczywistym środowisku podczas hostowania i rozwiązywania problemów z Cloud Anchor.

Zasady wycofywania

  • Aplikacje utworzone przy użyciu ARCore SDK w wersji 1.12.0 lub nowszej są objęte zasadami wycofywania interfejsu Cloud Anchor API.
  • Aplikacje utworzone przy użyciu ARCore SDK w wersji 1.11.0 lub starszej nie mogą hostować ani rozwiązywać problemów z Cloud zakotwiczonych, ponieważ pakiet SDK korzysta ze starszego, wycofanego interfejsu ARCore API.

Co dalej?