Przewodnik dla programistów Cloud Anchors dla iOS

Pakiet ARCore SDK na iOS współpracuje z ARKit, zapewniając usługę kotwicy w chmurze, umożliwiając udostępnianie kotwic między urządzeniami z iOS i Androidem w tym samym środowisku.

Dowiedz się, jak używać interfejsu ARCore Cloud Anchor API lub ARCore Cloud Anchor we własnych aplikacjach.

Wymagania wstępne

  • Xcode w wersji 13.0 lub nowszej.
  • Cocoapods w wersji 1.4.0 lub nowszej, jeśli używasz Cocoapods
  • zgodne z ARKit urządzenie Apple z systemem iOS 12.0 lub nowszym (wymagane jest wdrożenie w systemie iOS 12.0 lub nowszym).

Jeśli nie znasz jeszcze Cloud Anchors:

Włącz kotwice w chmurze w swojej aplikacji

Aby użyć interfejsu API Cloud Anchors, musisz utworzyć GARSessionConfiguration i ustawić dla niego właściwość cloudAnchorMode zgodnie z opisem w sekcji Konfigurowanie sesji ARCore w iOS. Aby ustawić konfigurację, użyj opcji setConfiguration:error: (GARSession).

Musisz też włączyć ARCore API w projekcie Google Cloud Platform.

Hostowanie i rozpoznawanie kotwic

Za pomocą interfejsu ARCore Cloud Anchor API możesz hostować i rozstrzygać kotwice w chmurze. Obejmuje on metody wywołań zwrotnych dotyczące zakończonych operacji oraz obiektów przyszłych, które mogą być odpytywane.

Hostowanie kotwicy

Hostowanie obiektu ARAnchor umieszcza kotwicę we wspólnym układzie współrzędnych w danej przestrzeni fizycznej.

Żądanie hosta wysyła na serwer Google dane wizualne, które mapują pozycję obiektu ARAnchor w układzie współrzędnych reprezentującym bieżącą przestrzeń fizyczną. Udane żądanie hosta zwraca nowy identyfikator kotwicy Cloud, który możesz udostępnić i wykorzystać do późniejszego rozpoznania kotwicy.

- (void)addAnchorWithTransform:(matrix_float4x4)transform {
  self.arAnchor = [[ARAnchor alloc] initWithTransform:transform];
  [self.sceneView.session addAnchor:self.arAnchor];

  __weak ExampleViewController *weakSelf = self;
  self.hostFuture = [self.cloudAnchorManager
      hostCloudAnchor:self.arAnchor
           completion:^(NSString *anchorId, GARCloudAnchorState cloudState) {
             [weakSelf handleHostAnchor:anchorId cloudState:cloudState];
           }
                error:nil];
  [self enterState:HelloARStateHosting];
}

Rozwiązywanie kotwicy

Naprawienie obiektu ARAnchor umożliwia urządzeniom z Androidem i iOS w danej przestrzeni fizycznej dodanie do nowych scen wcześniej hostowanych kotwic.

Żądanie rozwiązania wysyła do serwera Google identyfikator kotwicy w chmurze wraz z danymi wizualnymi z bieżącej ramki. Serwer spróbuje dopasować te dane wizualne do obrazu miejsca, w którym mapowane są aktualnie hostowane kotwice Cloud. Jeśli uda się rozwiązać problem, do sesji zostanie dodana i zwrócona nowa kotwica.

- (void)resolveAnchorWithIdentifier:(NSString *)identifier {
  GARResolveCloudAnchorFuture *garFuture =
      [self.gSession resolveCloudAnchorWithIdentifier:identifier
                                    completionHandler:completion
                                                error:&error];
}

// Pass the ARFRame to the ARCore session every time there is a frame update.
// This returns a GARFrame that contains a list of updated anchors. If your
// anchor's pose or tracking state changed, your anchor will be in the list.
- (void)cloudAnchorManager:(CloudAnchorManager *)manager didUpdateFrame:(GARFrame *)garFrame {
  for (GARAnchor *garAnchor in garFrame.updatedAnchors) {
    if ([garAnchor isEqual:self.garAnchor] && self.resolvedAnchorNode) {
      self.resolvedAnchorNode.simdTransform = garAnchor.transform;
      self.resolvedAnchorNode.hidden = !garAnchor.hasValidTransform;
    }
  }
}

Opcjonalny wzorzec odpytywania GARSession

Jeśli używasz Metal lub potrzebujesz opcji odpytywania a Twoja aplikacja działa z prędkością co najmniej 30 kl./s, użyj tego wzorca, aby przekazywać ARFrame do GARSession:

-(void)myOwnPersonalUpdateMethod {
  ARFrame *arFrame = arSession.currentFrame;
  NSError *error = nil;
  GARFrame *garFrame = [garSession update:arFrame error:&error];
  // your update code here
}

Hostowanie kotwicy w chmurze o trwałości

W wersjach ARCore w wersji 1.20 usługi Cloud kotwicy mogły być obsługiwane tylko przez 24 godziny od ich pierwszego hostowania. Dzięki trwałym kotwicom w chmurze możesz teraz za pomocą hostCloudAnchor:ttlDays:completionHandler:error: utworzyć kotwicę Cloud z czasem życia danych (TTL) od 1 do 365 dni. Możesz też przedłużyć czas trwania kotwicy po jej hostowaniu za pomocą Cloud Anchor Management API.

- (nullable GARHostCloudAnchorFuture *)
      hostCloudAnchor:(ARAnchor *)anchor
              TTLDays:(NSInteger)TTLDays
    completionHandler:(void (^_Nullable)(NSString *_Nullable cloudIdentifier,
                                         GARCloudAnchorState cloudState))completionHandler
                error:(NSError **)error;

Upoważnienie

Twoja aplikacja musi być autoryzowana do korzystania z interfejsu Cloud Anchors API. Możesz użyć podpisanego tokena internetowego JSON (JWT) lub autoryzacji klucza interfejsu API.

Autoryzacja tokena (podpisanego JWT)

Użyj podpisanej autoryzacji tokena sieciowego JSON (JWT) do hostowania Cloud Anchor na maksymalnie 365 dni. Użyj autoryzacji klucza interfejsu API do hostowania usługi Cloud Anchor na maksymalnie 1 dzień.

Obecnie jedynym obsługiwanym typem tokena jest podpisany token JWT (czyli token internetowy JSON podpisany przez konto usługi Google). Wprowadzenie do tokenów JWT znajdziesz na oficjalnej stronie JWT. Aby można było wygenerować tokeny internetowe JSON na iOS, serwer musi mieć punkt końcowy, który spełnia te wymagania:

  • Punkt końcowy musi być chroniony przez Twój własny mechanizm autoryzacji.

  • Punkt końcowy musi za każdym razem wygenerować nowy token, na przykład:

    • Każdy użytkownik otrzymuje unikalny token.
    • Tokeny nie wygasają od razu.

Utwórz konto usługi i klucz podpisywania

Aby utworzyć konto usługi Google i klucz podpisywania, wykonaj te czynności:

  1. W menu nawigacyjnym konsoli Google Cloud Platform wybierz APIs & Services > Credentials.

  2. Wybierz projekt i kliknij Create Credentials > Service account.

  3. W polu Service account details wpisz nazwę nowego konta, a następnie kliknij Create.

  4. Na stronie Service account permissions otwórz menu Select a role. Wybierz Service Accounts > Service Account Token Creator i kliknij Continue.

  5. Na stronie Grant users access to this service account kliknij Done. Wrócisz do aplikacji APIs & Services > Credentials.

  6. Na stronie Credentials przewiń w dół do sekcji Service Accounts i kliknij nazwę nowo utworzonego konta.

  7. Na stronie Service account details przewiń w dół do sekcji Keys i wybierz Add Key > Create new key.

  8. Wybierz JSON jako typ klucza i kliknij Create. Spowoduje to pobranie na Twój komputer pliku JSON z kluczem prywatnym. Zapisz pobrany plik klucza JSON w bezpiecznym miejscu.

Tworzenie tokenów na serwerze

Aby utworzyć nowe tokeny (JWT) na serwerze, użyj standardowych bibliotek JWT i pliku JSON bezpiecznie pobranego z nowego konta usługi.

Tworzenie tokenów na komputerze do programowania

Aby wygenerować tokeny JWT w maszynie do programowania, użyj tego polecenia oauth2l:

oauth2l fetch --jwt --json $KEYFILE $AUDIENCE --cache ""

Określenie pustej lokalizacji pamięci podręcznej za pomocą flagi --cache jest konieczne, aby mieć pewność, że za każdym razem będzie generowany inny token. Pamiętaj, aby przyciąć wynikowy ciąg, ponieważ dodatkowe spacje lub znaki nowego wiersza spowodują odrzucenie tokena przez ARCore.

Podpisz token

Aby podpisać token JWT, musisz użyć algorytmu RS256 i tych deklaracji:

  • iss – adres e-mail konta usługi.
  • sub – adres e-mail konta usługi.
  • iat – czas uniksowy generowania tokena (w sekundach).
  • exp – iat + 3600 (1 godzina). Czas uniksowy wygaśnięcia tokena (w sekundach).
  • aud – grupa odbiorców. Prawidłowa „odbiorca” dla interfejsu ARCore API to https://arcore.googleapis.com/.

Niestandardowe deklaracje nie są wymagane w ładunku JWT, ale deklaracja uid może być przydatna do identyfikacji odpowiedniego użytkownika.

Jeśli używasz innej metody generowania tokenów JWT, na przykład interfejsu Google API w środowisku zarządzanym przez Google, pamiętaj, aby podpisać tokeny JWT za pomocą deklaracji podanych w tej sekcji. Przede wszystkim musisz zadbać o prawidłową grupę odbiorców.

Przekazywanie tokena do sesji ARCore

Najpierw utwórz sesję za pomocą sessionWithError::

NSError *error = nil;
GARSession *session = [GARSession sessionWithError:&error];

Gdy uzyskasz token, przekaż go do sesji za pomocą setAuthToken:.

/**
 * Provide an auth token to use when authenticating with Google Cloud Services. If the
 * session was created with an API Key, the token will be ignored and an error will be logged.
 * Otherwise, the most recent valid auth token passed in will be used. Call this method each time
 * you refresh your token.
 *
 * @param authToken Token to use when authenticating with Google Cloud Services. This
 *                  must be a nonempty ASCII string with no spaces or control characters. This will
 *                  be used until another token is passed in. See documentation for supported token
 *                  types.
 */
- (void)setAuthToken:(NSString *)authToken;

Podczas przekazywania tokena do sesji pamiętaj o tych kwestiach:

  • Jeśli nie podasz prawidłowego tokena przed próbą hostowania lub rozwiązywania kotwicy, pojawią się błędy autoryzacji.

  • ARCore ignoruje tokeny zawierające spacje lub znaki specjalne. ARCore ignoruje wszystkie tokeny, jeśli utworzysz sesję z prawidłowym kluczem interfejsu API. Jeśli klucz interfejsu API był wcześniej używany i nie jest już potrzebny, zalecamy usunięcie go w Google Developers Console oraz usunięcie go z aplikacji po przeniesieniu użytkowników do najnowszej wersji.

  • Tokeny zazwyczaj tracą ważność po godzinie. Jeśli istnieje możliwość, że token wygaśnie podczas używania, uzyskaj nowy token i przekaż go do interfejsu API.

Autoryzacja klucza interfejsu API

Używaj opcji autoryzacji klucza interfejsu API do hostowania usługi Cloud Anchor na maksymalnie 1 dzień.

Aby uzyskać klucz interfejsu API i dodać go do projektu, wykonaj te czynności:

  1. Aby uzyskać klucz interfejsu API, odwiedź Centrum pomocy konsoli Google Cloud Platform.

  2. W Xcode przekaż nowy klucz interfejsu API do usługi sessionWithAPIKey:bundleIdentifier:error:, aby dodać go do projektu:

    NSError *error = nil;
GARSession *session = [GARSession sessionWithAPIKey:@"your-api-key" bundleIdentifier:nil error:&error];

Jakość mapowania

Interfejs API jakości mapowania szacuje jakość punktów cech wizualnych widocznych przez ARCore w ciągu ostatnich kilku sekund i widocznych w podanym przekształceniu kamery. Przekształcenia kotwicy Cloud hostowane przy użyciu funkcji wyższej jakości są zwykle łatwiejsze i dokładniejsze. Jeśli w przypadku danej przekształcenia nie można oszacować jakości mapy cech, ARCore zarejestruje komunikat z ostrzeżeniem i zwraca GARFeatureMapQualityInsufficient. Ten stan wskazuje, że ARCore będzie prawdopodobnie mieć większe trudności z rozpoznawaniem kotwicy w Cloud. Zachęć użytkownika do przeniesienia urządzenia, aby żądana pozycja kotwicy w chmurze była wyświetlana z różnych kątów.

/**
 * @param transform The camera transform to use to estimate the mapping quality.
 * @param error Out parameter for an `NSError`. Possible errors:
 *        GARSessionErrorCodeNotTracking - Bad current ARTrackingState.
 * @return The estimated quality of the visual feature points seen
 *        by ARCore in the preceding few seconds and visible from the provided camera
 *        transform.
 */
- (GARFeatureMapQuality)estimateFeatureMapQualityForHosting:(simd_float4x4)transform
                                                      error:(NSError **)error;

Limity interfejsu API

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

Typ limitu Maksimum Czas trwania Dotyczy:
Liczba kotwic Bez limitu Nie dotyczy Projekt
Żądania dotyczące hosta zakotwiczonego 30 minuta Adres IP i projekt
Żądania rozwiązywania problemów zakotwiczonych 300 minuta Adres IP i projekt

Znane problemy i sposoby obejścia

Podczas korzystania z pakietu ARCore SDK na iOS występuje kilka znanych problemów.

Domyślne ustawienia schematu powodują sporadyczną awarię aplikacji

Ustawienia schematu GPU Frame Capture i Metal API Validation są domyślnie włączone, co może czasami powodować awarię aplikacji w pakiecie SDK.

Diagnozowanie awarii aplikacji

Za każdym razem, gdy podejrzewasz, że wystąpiła awaria, sprawdź zrzut stosu. Jeśli w zrzucie stosu widzisz MTLDebugComputeCommandEncoder, prawdopodobnie wynika to z domyślnych ustawień schematu.

Obejście

  1. Otwórz: Product > Scheme > Edit Scheme….

  2. Otwórz kartę Run.

  3. Kliknij Options, aby wyświetlić bieżące ustawienia.

  4. Upewnij się, że funkcje GPU Frame Capture i Metal API Validation są wyłączone.

  5. Utwórz i uruchom aplikację.

Więcej znanych problemów znajdziesz na stronie CocoaPods CHANGELOG.

Ograniczenia

Pakiet ARCore SDK na iOS nie obsługuje wywołania metody ARKit setWorldOrigin(relativeTransform:).

Możliwe spowolnienie działania witryny

Wykorzystanie pamięci wzrasta po włączeniu interfejsu ARCore API. Spodziewaj się, że wykorzystanie baterii przez urządzenie wzrośnie ze względu na większe wykorzystanie sieci i mocy procesora.

Dalsze kroki