Découvrez comment utiliser Cloud Anchors dans vos propres applications.
Prérequis
Assurez-vous de bien maîtriser les concepts fondamentaux de la RA. et comment configurer une session ARCore avant de continuer.
Si vous débutez avec les ancres cloud, assurez-vous de bien comprendre le fonctionnement des ancres et des ancres cloud.
Activer l'API ARCore
Avant d'utiliser Cloud Anchors dans votre application, vous devez activer l'API ARCore dans votre application.
Activer les fonctionnalités Cloud Anchor dans la configuration de la session
Une fois la fonctionnalité Cloud Anchors activée dans votre application, activez-la dans la configuration de la session de RA afin qu'elle puisse communiquer avec l'API ARCore:
// 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);
Héberger une ancre cloud
L'hébergement commence par un appel à ArSession_hostCloudAnchorAsync(). ARCore importe les données visuelles, les positions de l'appareil et la position de l'ancre dans l'API ARCore. L'API traite ensuite ces informations pour créer une carte de caractéristiques 3D, puis renvoie à l'appareil un ID d'ancre cloud unique pour l'ancre.
Vous pouvez également prolonger la durée de vie d'une ancre hébergée à l'aide de l'API Cloud Anchor Management ARCore.
Votre application doit suivre ces étapes pour terminer l'hébergement d'une ancre cloud:
- Appelez
ArSession_hostCloudAnchorAsync(). - Attendez le rappel ou vérifiez continuellement l'état "Future" jusqu'à ce que cela soit terminé.
- Vérifier l'état du résultat pour déterminer si l'opération a réussi ou interpréter le code d'erreur si elle a échoué.
- Partagez l'ID d'ancre cloud obtenu avec d'autres clients et utilisez-le pour résoudre l'ancre cloud avec
ArSession_resolveCloudAnchorAsync()
Vérifier la qualité du mappage des points d'élément
ArFeatureMapQuality indique la qualité des points de caractéristiques vus par ARCore au cours des quelques secondes précédentes à partir d'une position donnée de la caméra. Les ancres cloud hébergées à l'aide de caractéristiques de meilleure qualité sont généralement résolues avec plus de précision. Utilisez ArSession_estimateFeatureMapQualityForHosting() pour obtenir une estimation de la qualité de la carte pour une position de caméra donnée.
| Valeur | Description |
|---|---|
INSUFFICIENT |
La qualité des points de caractéristiques identifiés à partir de la position au cours des quelques secondes précédentes est faible. Cet état indique qu'ARCore aura probablement plus de difficultés à résoudre l'ancre cloud. Encouragez l'utilisateur à déplacer l'appareil de sorte que la position souhaitée de l'ancre cloud qu'il souhaite héberger puisse être vue sous différents angles. |
SUFFICIENT |
La qualité des points de caractéristiques identifiés à partir de la position au cours des quelques secondes précédentes est probablement suffisante pour qu'ARCore réussisse à résoudre une ancre cloud, même si la précision de la pose résolue sera probablement réduite. Encouragez l'utilisateur à déplacer l'appareil de sorte que la position souhaitée de l'ancre cloud qu'il souhaite héberger puisse être vue sous différents angles. |
GOOD |
La qualité des points de caractéristiques identifiés à partir de la position au cours des quelques secondes précédentes est probablement suffisante pour qu'ARCore réussisse à résoudre une ancre cloud avec un haut degré de précision. |
Résoudre une ancre précédemment hébergée
Appelez ArSession_resolveCloudAnchorAsync() pour résoudre une ancre cloud hébergée. L'API ARCore compare régulièrement les caractéristiques visuelles de la scène à la carte de caractéristiques 3D de l'ancre pour indiquer la position et l'orientation de l'utilisateur par rapport à l'ancre. Lorsqu'elle trouve une correspondance, l'API renvoie la pose de l'ancre cloud hébergée.
Vous pouvez lancer des résolutions pour plusieurs ancres cloud dans l'ordre. Jusqu'à 40 opérations Cloud Anchor peuvent exister simultanément à la fois.
Annuler une opération ou supprimer une ancre cloud
Appelez ArFuture_cancel() pour annuler une opération d'ancre cloud en attente.
Appelez ArAnchor_detach() pour arrêter le suivi et supprimer une ancre cloud déjà résolue. Les références à l'ancre doivent être libérées séparément en appelant ArAnchor_release().
Vérifier l'état du résultat d'une opération d'ancre cloud
Utilisez ArCloudAnchorState pour vérifier l'état du résultat de l'opération d'hébergement ou de résolution, y compris les erreurs.
| Valeur | Description |
|---|---|
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND |
Échec de la résolution, car l'API ARCore n'a pas trouvé l'ID d'ancre cloud fourni. |
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED |
L'hébergement a échoué, car le serveur n'a pas pu traiter l'ensemble de données pour l'ancre donnée. Réessayez lorsque l'appareil aura collecté davantage de données dans l'environnement. |
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE |
Impossible d'accéder à l'API ARCore. Ce problème peut avoir plusieurs causes. L'appareil est peut-être en mode Avion ou ne dispose pas d'une connexion Internet opérationnelle. La requête envoyée au serveur a peut-être expiré sans réponse. Il peut s'agir d'une mauvaise connexion réseau, d'une indisponibilité du DNS, de problèmes de pare-feu ou de tout autre problème pouvant affecter la capacité de l'appareil à se connecter à l'API ARCore. |
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL |
Une tâche d'hébergement ou de résolution pour cette ancre s'est terminée avec une erreur interne. L'application ne doit pas tenter de récupérer les données de cette erreur. |
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED |
Consultez la section Résoudre les problèmes d'autorisation de l'API ARCore. |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW |
Impossible de résoudre l'ancre cloud, car la version du SDK utilisée pour résoudre l'ancre est plus récente et incompatible avec la version utilisée pour l'héberger. |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD |
Impossible de résoudre l'ancre cloud, car la version du SDK utilisée pour résoudre l'ancre est plus ancienne et incompatible avec la version utilisée pour l'héberger. |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED |
L'application a épuisé le quota de requêtes alloué au projet Google Cloud donné. Vous devez demander des quotas supplémentaires pour l'API ARCore pour votre projet dans la Google Developers Console. |
AR_CLOUD_ANCHOR_STATE_SUCCESS |
Une tâche d'hébergement ou de résolution pour cette ancre a bien été effectuée. |
Quotas d'API pour les requêtes d'hôte et de résolution
L'API ARCore dispose des quotas suivants pour la bande passante des requêtes:
| 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 |
Bonnes pratiques pour une bonne expérience utilisateur
Pour garantir une bonne expérience utilisateur sur votre application, demandez aux utilisateurs de procéder comme suit:
- Attendez quelques secondes après le démarrage de la session avant de tenter d'héberger une ancre (en plaçant un objet, etc.). Cela laisse le temps au suivi de se stabiliser.
- Lorsque vous sélectionnez un emplacement pour héberger l'ancre, essayez de trouver une zone avec des caractéristiques visuelles faciles à distinguer les unes des autres. Pour de meilleurs résultats, évitez les surfaces réfléchissantes ou dépourvues d'éléments visuels, comme des murs blancs et blancs.
Maintenez la caméra entraînée sur le centre d'intérêt et déplacez l'appareil centre d'intérêt afin de cartographier l'environnement sous différents angles, en conservant à peu près la même distance physique que vous le faites. Cela vous aidera à capturer des données plus visuelles et à rendre la résolution plus robuste.
Assurez-vous que l'éclairage est suffisant en environnement réel lors de l'hébergement et de la résolution des ancres cloud.
Règlement d'obsolescence
- Les applications créées avec le SDK ARCore 1.12.0 ou version ultérieure sont soumises au Règlement relatif aux abandons de l'API Cloud Anchor.
- Les applications créées avec le SDK 1.11.0 ou version antérieure ARCore ne peuvent pas héberger ni résoudre des ancres cloud, car le SDK utilise une API ARCore plus ancienne et obsolète.
Étape suivante
- Consultez la documentation de référence du NDK Android pour découvrir d'autres façons d'utiliser ARCore dans votre application.