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.
- Włącz ARCore API w nowym lub istniejącym projekcie Google Cloud Platform.
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.
- Otwórz panel Gradle w projekcie Android Studio.
Uwzględnij
com.google.android.gms:play-services-auth:16+
w zależnościach aplikacji.Jeśli używasz ProGuard, dodaj ją do pliku
build.gradle
aplikacjibuildTypes { 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ń).
- Włącz ARCore API w nowym lub istniejącym projekcie Google Cloud Platform.
- Uzyskaj klucz interfejsu API tego projektu z konsoli Google Cloud.
W Android Studio dodaj do projektu nowy klucz interfejsu API. Umieść klucz interfejsu API w elemencie
<meta-data>
w elemencie<application>
wapp/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:
- Zadzwoń pod numer
ArSession_hostCloudAnchorAsync()
. - Poczekaj na oddzwonienie lub sprawdzaj stan w przyszłości.
- Sprawdź stan wyniku, aby ustalić, czy operacja się udała, lub zinterpretuj kod błędu, jeśli się nie udało.
- 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.
|
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?
- Więcej informacji na temat używania ARCore w aplikacji znajdziesz w dokumentacji referencyjnej NDK na Androida.