Guide du développeur Cloud Anchors pour iOS

Le SDK ARCore pour iOS interagit avec ARKit pour fournir des fonctionnalités Cloud Anchor, ce qui vous permet de partager des ancres entre les appareils iOS et Android dans le même environnement.

Découvrez comment utiliser l'API ARCore Cloud Anchor ou le service ARCore Cloud Anchor dans vos propres applications.

Prérequis

  • Xcode version 13.0 ou ultérieure
  • CocoaPods 1.4.0 ou version ultérieure si vous utilisez CocoaPods
  • Un appareil Apple compatible avec ARKit fonctionnant sous iOS 12.0 ou version ultérieure (cible de déploiement d'iOS 12.0 ou version ultérieure requise)

Si vous débutez avec les Cloud Anchors :

Activer Cloud Anchors dans votre application

Pour utiliser l'API Cloud Anchors, vous devez créer un GARSessionConfiguration et définir la propriété cloudAnchorMode pour celui-ci, comme décrit dans la section Configurer une session ARCore sur iOS. Utilisez setConfiguration:error: (GARSession) pour définir la configuration.

Vous devez également activer l'API ARCore pour votre application.

Héberger et résoudre les ancres

Vous pouvez héberger et résoudre des ancres cloud avec l'API ARCore Cloud Anchor. L'API inclut des méthodes de rappel pour les opérations terminées, ainsi que des objets Future pouvant être interrogés.

Héberger une ancre

Héberger un ARAnchor place l'ancre dans un système de coordonnées commun pour tout espace physique donné.

Une requête d'hôte envoie des données visuelles à un serveur Google, qui cartographie la position de l'ARAnchor dans un système de coordonnées représentant l'espace physique actuel. Une requête d'hôte réussie renvoie un nouvel ID d'ancre cloud, qui peut être partagé et utilisé pour résoudre l'ancre ultérieurement.

- (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];
}

Résoudre une ancre

Résoudre un ARAnchor autorise les appareils Android et iOS dans un espace physique donné pour ajouter des ancres précédemment hébergées à de nouvelles scènes.

Une requête de résolution envoie à un serveur Google un ID d'ancrage cloud, ainsi que des données visuelles du frame actuel. Le serveur tentera de faire correspondre ces données visuelles avec les images de l'emplacement des Cloud Anchors actuellement hébergés. Une fois la résolution effectuée, un nouvel ancrage est ajouté à la session et renvoyé.

- (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;
    }
  }
}

Schéma d'interrogation GARSession facultatif

Si vous utilisez Metal ou si vous avez besoin d'une option de sondage, et que votre application s'exécute à un minimale de 30 ips, utilisez le format suivant pour transmettre des ARFrames à la GARSession:

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

Quotas d'API

L'API ARCore applique les quotas de bande passante de requête suivants :

Type de quota Maximum Durée Applicable à
Nombre d'ancres Illimité N/A Projet
Demandes d'ancrage host 30 minute Adresse IP et projet
Requêtes resolve ancrées 300 minute Adresse IP et projet

Problèmes connus et solutions temporaires

Des problèmes connus surviennent lorsque vous utilisez le SDK ARCore pour iOS.

Les paramètres de schéma par défaut provoquent un plantage intermittent de l'application

Les paramètres du schéma de capture de frame GPU et de validation de l'API Metal sont activés par défaut, ce qui peut parfois entraîner le plantage de l'application dans le SDK.

Diagnostiquer un plantage d'application

Chaque fois que vous pensez qu'un plantage s'est produit, examinez la trace de la pile. Si MTLDebugComputeCommandEncoder s'affiche dans la trace de la pile, cela est probablement dû aux paramètres de schéma par défaut.

Solution

  1. Accédez à Product > Scheme > Edit Scheme….

  2. Ouvrez l'onglet Run.

  3. Cliquez sur Options pour afficher vos paramètres actuels.

  4. Assurez-vous que GPU Frame Capture et Metal API Validation sont désactivés.

  5. Créez et exécutez votre application.

Pour en savoir plus sur les problèmes connus, consultez la page CHANGELOG de Cocoapods.

Limites

Le SDK ARCore pour iOS n'est pas compatible avec l'appel de la méthode setWorldOrigin(relativeTransform:) d'ARKit.

Considérations sur les performances

L'utilisation de la mémoire augmente lorsque vous activez l'API ARCore. La consommation de la batterie de l'appareil augmentera en raison d'une utilisation plus importante du réseau et du processeur.

Étapes suivantes