Dowiedz się, jak używać kotwic w chmurze we własnych aplikacjach.
Wymagania wstępne
Zanim przejdziesz dalej, upewnij się, że znasz podstawowe pojęcia związane z AR i wiesz, jak skonfigurować sesję ARCore.
Jeśli nie masz doświadczenia z kotwicami w chmurze, upewnij się, że wiesz, jak działają kotwice i zakotwiczone w chmurze.
Włącz interfejs ARCore API
Zanim użyjesz w swojej aplikacji kotwicy Cloud, musisz włączyć w niej ARCore API.
Włącz możliwości usługi Cloud Anchor w konfiguracji sesji
Gdy włączysz funkcję kotwicy Cloud w aplikacji, włącz jej funkcje w konfiguracji sesji AR w aplikacji, aby mogły 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 kotwicy w chmurze
Hosting rozpoczyna się od wywołania metody ArSession_hostCloudAnchorAsync(). ARCore prześle do interfejsu ARCore API dane wizualne, pozycje urządzeń i pozycję kotwicy. Interfejs API przetwarza te informacje, aby utworzyć mapę funkcji 3D, a ostatecznie zwraca do urządzenia unikalny identyfikator kotwicy w chmurze.
Możesz też przedłużyć czas życia hostowanej kotwicy za pomocą interfejsu ARCore Cloud Anchor Management API.
Aby zakończyć hosting usługi kotwicy w chmurze, aplikacja powinna wykonać te czynności:
- Zadzwoń pod numer
ArSession_hostCloudAnchorAsync(). - Poczekaj na wywołanie zwrotne lub stale sprawdzaj stan przyszły, dopóki się nie zakończy.
- Sprawdź stan wyniku, aby określić, czy operacja się powiodła, lub zinterpretuj kod błędu, jeśli się nie uda.
- Udostępnij wynik identyfikatora kotwicy Cloud innym klientom i użyj go do rozpoznania kotwicy Cloud za pomocą:
ArSession_resolveCloudAnchorAsync().
Sprawdzanie jakości mapowania punktów cech
ArFeatureMapQuality wskazuje jakość punktów cech zarejestrowanych przez ARCore w ciągu ostatnich kilku sekund w danej pozycji kamery. Kotwice w chmurze hostowane z użyciem funkcji wyższej jakości są zwykle dokładniej rozpoznawane. Użyj narzędzia ArSession_estimateFeatureMapQualityForHosting(), aby oszacować jakość mapy obiektów w danej pozycji kamery.
| Wartość | Opis |
|---|---|
INSUFFICIENT |
Jakość punktów cech zidentyfikowanych na podstawie pozycji w ostatnich kilku sekundach jest niska. Ten stan wskazuje, że ARCore prawdopodobnie będzie mieć większe problemy z rozpoznaniem usługi kotwicy w chmurze. Zachęć użytkownika do przesunięcia urządzenia tak, aby żądana pozycja kotwicy w chmurze, którą chce hostować, była widoczna 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 zakotwiczenia w chmurze przez ARCore, ale dokładność zatwierdzonej pozycji prawdopodobnie się zmniejszy. Zachęć użytkownika do przesunięcia urządzenia tak, aby żądana pozycja kotwicy w chmurze, którą chce hostować, była widoczna pod różnymi kątami. |
GOOD |
Jakość punktów cech zidentyfikowanych w pozycji w ciągu ostatnich kilku sekund wystarczy, aby aplikacja ARCore mogła skutecznie rozpoznać kotwicę w chmurze z dużą dokładnością. |
Rozwiązywanie wcześniej hostowanej kotwicy
Wywołaj ArSession_resolveCloudAnchorAsync(), aby znaleźć hostowaną kotwicę Cloud. Interfejs ARCore API okresowo porównuje cechy 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 kotwicy Cloud.
Możesz zainicjować rozstrzygnięcia dla wielu zakotwiczonych w chmurze w sekwencji. W danym momencie może istnieć do 40 równoczesnych operacji w Cloud Anchor.
Anulowanie operacji lub usuwanie kotwicy w chmurze
Wywołaj ArFuture_cancel(), aby anulować oczekującą operację kotwicy Cloud.
Wywołaj metodę ArAnchor_detach(), aby zatrzymać śledzenie i zapomnieć już rozwiniętą kotwicę Cloud. Odniesienia do kotwicy muszą być zwolnione oddzielnie, wywołując metodę ArAnchor_release().
Sprawdzanie stanu wyniku operacji zakotwiczonej w chmurze
Użyj parametru ArCloudAnchorState, aby sprawdzić stan wyników operacji hostingu lub rozwiązywania problemów, 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 w chmurze. |
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 działającego połączenia z internetem. Żądanie wysłane do serwera mogło zostać przekroczony i nie uzyskać odpowiedzi. Może to być złe połączenie sieciowe, niedostępność DNS, problemy z zaporą sieciową lub coś innego, co wpływa na zdolność urządzenia do łączenia się z interfejsem ARCore API. |
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL |
Zadanie hostingu lub rozwiązywania problemów z tą kotwicą zostało zakończone z błędem wewnętrznym. Aplikacja nie powinna podejmować prób usunięcia konta po tym błędzie. |
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ę ustalić wersji pakietu SDK Cloud, ponieważ wersja pakietu SDK użyta do rozpoznania kotwicy jest nowsza i niezgodna z wersją użytą do jej hostowania. |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD |
Nie udało się ustalić wersji pakietu SDK Cloud, ponieważ wersja pakietu SDK użyta do rozpoznania kotwicy jest starsza i niezgodna z wersją użytą do jej hostowania. |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED |
Aplikacja wyczerpała limit żądań przypisany do danego projektu Google Cloud. Aby zgłosić prośbę o zwiększenie limitu interfejsu ARCore API w projekcie, skorzystaj z Google Developers Console. |
AR_CLOUD_ANCHOR_STATE_SUCCESS |
Udało się wykonać zadanie hostingu lub rozwiązywania problemów tej kotwicy. |
Limity interfejsów API dotyczące żądań hostów i rozwiązywania
W interfejsie ARCore API obowiązują następujące limity przepustowości żądań:
| Typ limitu | Maksimum | Czas działania | Dotyczy: |
|---|---|---|---|
| Liczba kotwic | bez ograniczeń | Nie dotyczy | projekt |
| Żądania kotwicy hosta | 30 | minuta | Adres IP i projekt |
| resolve żądań zakotwiczonych | 300 | minuta | Adres IP i projekt |
Sprawdzone metody dbania o wygodę użytkowników
Poproś ich o wykonanie tych czynności, aby zapewnić im dobre wrażenia z aplikacji:
- Zaczekaj kilka sekund po rozpoczęciu sesji, zanim spróbujesz hostować kotwicę (np. umieszczając obiekt). To zapewni trochę czasu na ustabilizowanie się śledzenia.
- Wybierając miejsce, w którym ma się wyświetlać kotwica, znajdź obszar z elementami wizualnymi, które łatwo się od siebie odróżnić. Aby uzyskać najlepsze wyniki, unikaj powierzchni odbijających światło i powierzchni pozbawionych elementów wizualnych, np. pustych białych ścian.
Kamera powinna być ustawiona w taki sposób, aby znalazła się w centrum zainteresowania, i poruszać urządzenie po całym centrum, aby zmapować środowisko z różnych kątów, zachowując mniej więcej taką samą odległość jak tutaj. Pomoże to rejestrować więcej danych wizualnych i zwiększyć dokładność rozpoznawania.
Podczas hostowania i rozmowywania kotwic w chmurze upewnij się, że w rzeczywistym środowisku jest wystarczająco oświetlone.
Zasady wycofywania
- Aplikacje utworzone przy użyciu pakietu SDK ARCore w wersji 1.12.0 lub nowszej są objęte zasadami wycofywania interfejsu Cloud Anchor API.
- Aplikacje utworzone przy użyciu pakietu SDK w wersji 1.11.0 lub starszej ARCore nie mogą hostować ani wyświetlać kotwic w chmurze, ponieważ pakiet SDK używa starszego, wycofanego interfejsu ARCore API.
Co dalej
- Więcej informacji o korzystaniu z ARCore w aplikacji znajdziesz w dokumentacji referencyjnej dotyczącej pakietu Android NDK.