Guide du développeur Cloud Anchors pour Android NDK (C)

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 Cloud Anchors, assurez-vous de comprendre le fonctionnement des ancrages et des Cloud Anchors.

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:

// 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 fonctionnalités 3D, et renvoie finalement un ID d'ancre cloud unique pour l'ancre de 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.

Pour héberger une balise Cloud, votre application doit suivre ces étapes:

1. Appelez ArSession_hostCloudAnchorAsync().
2. Attendez le rappel ou vérifiez continuellement l'état Future jusqu'à ce qu'il soit terminé.
3. Vérifiez l'état du résultat pour déterminer si l'opération a réussi ou interpréter le code d'erreur en cas d'échec.
4. 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é de la cartographie des points d'intérêt

ArFeatureMapQuality indique la qualité des points de caractéristiques vus par ARCore au cours des quelques secondes précédentes à partir d'une position d'appareil photo donnée. 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 ArSession_estimateFeatureMapQualityForHosting() pour obtenir une estimation de la qualité de la carte de caractéristiques pour une position de caméra donnée.

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 éléments visuels de la scène à la carte des éléments 3D de l'ancrage pour déterminer la position et l'orientation de l'utilisateur par rapport à l'ancrage. 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 Cloud Anchors de manière séquentielle. Vous pouvez exécuter jusqu'à 40 opérations d'ancrage cloud simultanées à la fois.

Annuler une opération ou supprimer un Cloud Anchor

Appelez ArFuture_cancel() pour annuler une opération d'ancrage cloud 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 libéré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 du résultat de l'opération d'hébergement ou de résolution, y compris les erreurs.

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:

Bonnes pratiques pour une bonne expérience utilisateur

Pour garantir une bonne expérience utilisateur dans votre application, demandez aux utilisateurs de suivre les instructions suivantes:

• Attendez quelques secondes après le début de la session avant de tenter d'héberger une ancre (en plaçant un objet, par exemple). Cela permet 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échisantes ou celles qui ne présentent pas de caractéristiques visuelles, comme les murs 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 couvertes par le Règlement d'abandon 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 du NDK Android pour découvrir d'autres façons d'utiliser ARCore dans votre application.