Découvrez comment utiliser Cloud Anchors dans vos propres applications.
Prérequis
Assurez-vous de bien comprendre les concepts fondamentaux de la RA et de configurer une session ARCore avant de continuer.
Si vous débutez avec Cloud Anchors, assurez-vous de bien comprendre comment fonctionnent les ancres et les ancres cloud.
Activer l'API ARCore
Avant d'utiliser Cloud Anchors dans votre application, vous devez d'abord activer l'API ARCore.
Activer les fonctionnalités Cloud Anchor dans la configuration de la session
Une fois la fonctionnalité Cloud Anchors activée dans votre application, activez les fonctionnalités Cloud Anchors dans la configuration de la session de RA de votre application 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 importera les données visuelles, les postures de l'appareil et la posture de l'ancre dans l'API ARCore. L'API traite ensuite ces informations pour construire une carte d'éléments géographiques 3D, et renvoie au final un ID d'ancre cloud unique pour l'ancre à l'appareil.
Vous pouvez également prolonger la durée de vie d'une ancre hébergée à l'aide de l'API ARCore Cloud Anchor Management.
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 cette opération soit terminée.
- Vérifiez l'état du résultat pour déterminer si l'opération a réussi ou interprétez le code d'erreur si elle a échoué.
- Partagez l'ID d'ancre cloud résultant avec d'autres clients et utilisez-le pour résoudre l'ancre cloud avec
ArSession_resolveCloudAnchorAsync().
Vérifier la qualité de la mise en correspondance des points de caractéristiques
ArFeatureMapQuality indique la qualité des points de caractéristiques observés par ARCore au cours des quelques secondes précédentes à partir d'une position de caméra donnée. 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 de caractéristiques pour une posture de caméra donnée.
| Valeur | Description |
|---|---|
INSUFFICIENT |
La qualité des points de caractéristiques identifiés à partir de la posture au cours des quelques secondes précédentes est faible. Cet état indique qu'ARCore aura probablement plus de difficultés à résoudre Cloud Anchor. Encouragez l'utilisateur à déplacer l'appareil afin 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 puisse résoudre une ancre cloud. Toutefois, la précision de la pose résolue sera probablement réduite. Encouragez l'utilisateur à déplacer l'appareil afin 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 puisse 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 afin de déterminer la position et l'orientation de l'utilisateur par rapport à celle-ci. Lorsqu'une correspondance est trouvée, l'API renvoie la position 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 être exécutées simultanément.
Annuler une opération ou supprimer une ancre cloud
Appelez ArFuture_cancel() pour annuler une opération Cloud Anchor en attente.
Appelez ArAnchor_detach() pour arrêter le suivi et oublier une ancre cloud déjà résolue. Les références à l'ancre doivent être publiées séparément en appelant ArAnchor_release().
Vérifier l'état du résultat d'une opération Cloud Anchor
Utilisez ArCloudAnchorState pour vérifier l'état des résultats 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 |
Échec de l'hébergement, car le serveur n'a pas pu traiter correctement l'ensemble de données pour l'ancre donnée. Réessayez une fois que l'appareil a 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. Il est possible que l'appareil soit en mode Avion ou qu'il 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 y avoir une mauvaise connexion réseau, une indisponibilité DNS, des problèmes de pare-feu ou tout autre problème qui pourrait empêcher l'appareil de 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'appli ne doit pas tenter de corriger 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 Cloud Anchor, 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 antérieure à la version utilisée pour l'héberger et incompatible avec celle-ci. |
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 un quota supplémentaire d'API ARCore pour votre projet dans la Google Play Console. |
AR_CLOUD_ANCHOR_STATE_SUCCESS |
Une tâche d'hébergement ou de résolution pour cette ancre a bien été exécuté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 | unlimited | N/A | projet |
| Ancrer les requêtes host | 30 | minute | Adresse IP et projet |
| Ancrer les requêtes resolve | 300 | minute | Adresse IP et projet |
Bonnes pratiques pour une bonne expérience utilisateur
Demandez aux utilisateurs de procéder comme suit pour garantir une bonne expérience utilisateur sur votre application:
- Attendez quelques secondes après le démarrage de la session avant d'essayer 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 éléments visuels faciles à distinguer les uns des autres. Pour de meilleurs résultats, évitez les surfaces réfléchissantes ou sans caractéristiques visuelles, comme des murs blancs vierges.
Maintenez la caméra entraînée sur le centre d'intérêt et déplacez l'appareil autour de celui-ci pour cartographier l'environnement sous différents angles, en conservant à peu près la même distance physique. Cela permettra de capturer plus de données visuelles et de rendre la résolution plus robuste.
Assurez-vous que l'éclairage est suffisant dans l'environnement réel lors de l'hébergement et de la résolution des ancres cloud.
Règlement relatif aux abandons
- Les applications créées avec le SDK ARCore 1.12.0 ou version ultérieure sont couvertes par le Règlement relatif à l'abandon de l'API Cloud Anchor.
- Les applications créées avec le SDK 1.11.0 ou une version antérieure ARCore ne peuvent pas héberger ou résoudre des ancres cloud, car le SDK utilise une API ARCore plus ancienne et obsolète.
Étapes suivantes
- Consultez la documentation de référence du NDK Android pour découvrir d'autres façons d'utiliser ARCore dans votre application.