Découvrez comment utiliser les ancrages Cloud dans vos propres applications.
Prérequis
Avant de continuer, assurez-vous de bien comprendre les concepts fondamentaux de la RA et de savoir configurer une session ARCore.
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 les ancres cloud dans votre application, vous devez d'abord 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 les fonctionnalités Cloud Anchors dans la configuration de la session AR de votre application afin qu'elle puisse communiquer avec l'API ARCore:
Héberger une ancre cloud
L'hébergement commence par un appel à ARAnchorManager.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 ARCore Cloud Anchor Management.
Pour héberger une balise Cloud, votre application doit suivre ces étapes:
- Appelez
ARAnchorManager.HostCloudAnchorAsync(). - Démarrez une coroutine pour attendre que la promesse produise un résultat. Pour en savoir plus, consultez Coroutines dans Unity.
- 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 obtenu avec d'autres clients et utilisez-le pour résoudre l'ancre cloud avec
ARAnchorManagerExtensions.ResolveCloudAnchorAsync().
Vérifier la qualité de la cartographie des points d'intérêt
ARCoreExtensions.FeatureMapQuality 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 fonctionnalités de meilleure qualité sont généralement résolues plus précisément. Utilisez ARAnchorManagerExtensions.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 d'intérêt identifiés à partir de la pose 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 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 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 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 d'intérêt identifiés à partir de la pose au cours des quelques secondes précédentes est probablement suffisante pour qu'ARCore puisse résoudre une ancre cloud avec un degré de précision élevé. |
Résoudre une ancre précédemment hébergée
Appelez ARAnchorManagerExtensions.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'une correspondance est trouvée, 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. Vous pouvez exécuter jusqu'à 40 opérations d'ancrage cloud simultanées.
Annuler une opération ou supprimer une ancre cloud
ARCloudAnchor.OnDestroy() est appelé automatiquement lorsque le composant ARCloudAnchor est supprimé de l'objet de jeu qui le contient. Cela dissociera et libérera l'objet Cloud Anchor natif sous-jacent.
Vérifier l'état des résultats d'une opération Cloud Anchor
Utilisez CloudAnchorState 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 |
|---|---|
ErrorResolvingCloudIdNotFound |
La résolution a échoué, car l'API ARCore n'a pas trouvé l'ID d'ancre cloud fourni. |
ErrorHostingDatasetProcessingFailed |
L'hébergement a échoué, car le serveur n'a pas réussi à traiter l'ensemble de données pour l'ancre donnée. Réessayez une fois que l'appareil aura collecté plus de données sur l'environnement. |
ErrorHostingServiceUnavailable |
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 fonctionnelle. Le délai de 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 élément pouvant affecter la capacité de l'appareil à se connecter à l'API ARCore. |
ErrorInternal |
Une tâche d'hébergement ou de résolution de cet ancrage s'est terminée avec une erreur interne. L'application ne doit pas tenter de récupérer cette erreur. |
ErrorNotAuthorized |
L'application ne peut pas communiquer avec l'API ARCore en raison d'une autorisation non valide. Vérifiez que vous avez défini une stratégie d'autorisation valide dans Project Settings > XR > ARCore Extensions (Paramètres du projet > XR > Extensions ARCore). |
ErrorResolvingPackageTooNew |
L'ancre cloud n'a pas pu être résolue, car le package d'extensions ARCore utilisé pour la résoudre est plus récent que la version utilisée pour l'héberger et incompatible avec celle-ci. |
ErrorResolvingPackageTooOld |
L'ancre cloud n'a pas pu être résolue, car le package d'extensions ARCore utilisé pour la résoudre est plus ancien que la version utilisée pour l'héberger et n'est pas compatible avec elle. |
ErrorResourceExhausted |
L'application a épuisé le quota de requêtes alloué au projet Google Cloud donné. Vous devez demander un quota supplémentaire pour l'API ARCore pour votre projet dans la Google Developers Console. |
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 applique les quotas de bande passante de requête suivants:
| Type de quota | Maximum | Durée | Applicable à |
|---|---|---|---|
| Nombre d'ancres | illimité | N/A | projet |
| Ancrer les requêtes de l'hôte | 30 | minute | Adresse IP et projet |
| Demandes d'résolution des ancres | 300 | minute | Adresse IP et projet |
Bonnes pratiques pour une bonne expérience utilisateur
Demandez aux utilisateurs de suivre les instructions suivantes pour garantir une bonne expérience utilisateur dans votre application:
- Attendez quelques secondes après le début de la session avant d'essayer d'héberger une ancre (en plaçant un objet, par exemple). 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 dont les caractéristiques visuelles sont facilement distinguables 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 braqué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 maintenant à peu près la même distance physique. Vous pourrez ainsi capturer plus de données visuelles et améliorer la résolution.
Assurez-vous que l'environnement réel est suffisamment éclairé lorsque vous hébergez et résolvez des Cloud Anchors.
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 ARCore 1.11.0 ou version antérieure ne peuvent pas héberger ni résoudre d'ancres cloud, car le SDK utilise une ancienne API ARCore obsolète.
Étape suivante
- Consultez la documentation de référence sur les extensions ARCore pour AR Foundation pour découvrir d'autres façons d'utiliser ARCore dans votre application.