Créer une application de réalité augmentée (RA) à l'aide de la nouvelle API ARCore Geospatial

1. Présentation

ARCore est le framework Google pour créer des expériences de réalité augmentée sur smartphone. La nouvelle API ARCore Geospatial apporte une nouvelle dimension à la réalité augmentée, en vous permettant de placer des points de repère de réalité augmentée spécifiques à un lieu autour de monuments réels.

Ce que vous allez faire

Dans cet atelier de programmation, vous allez faire vos premiers pas avec l'API ARCore Geospatial. Vous découvrirez les informations que l'API Geospatial peut offrir à votre expérience de RA globale, et comment ces données peuvent être utilisées pour alimenter une expérience de navigation en RA simple.

Points abordés

• Configurer un projet ARCore qui utilise l'API Geospatial
• Découvrez comment demander des données géographiques à l'API Geospatial et les afficher à l'aide de Google Maps.
• Comment placer une ancre associée à un lieu réel.

Prérequis

• Un appareil Android compatible ARCore, connecté à votre ordinateur de développement à l'aide d'un câble USB et configuré en mode débogage USB.
• Android Studio installé et configuré pour la compilation d'applications Android
• La version 1.31 ou ultérieure de l'application Services Google Play pour la RA installée sur l'appareil de développement Android

2. Configurer l'environnement de développement

Configurer Android Studio

Pour faire vos premiers pas avec l'API Geospatial, nous vous fournissons un projet de démarrage qui inclut les éléments de base d'un projet ARCore intégré au SDK Google Maps. Cela vous permet de démarrer rapidement avec l'API Geospatial.

1. Démarrez Android Studio et importez un projet depuis un système de gestion de versions.
   • Si vous avez déjà ouvert un projet, utilisez File > New > Project from Version Control… (Fichier > Nouveau > Projet provenant du contrôle des versions…).
   • Si la fenêtre Welcome to Android Studio (Bienvenue dans Android Studio) s'affiche, utilisez Get from VCS (Obtenir depuis VCS).
2. Sélectionnez Git, puis utilisez l'URL https://github.com/google-ar/codelab-geospatial.git pour importer le projet.

Configurer un projet Google Cloud

L'API Geospatial utilise des images Street View combinées aux informations du magnétomètre et du capteur de caméra de l'appareil pour améliorer les valeurs d'orientation. Pour utiliser ce service, vous devez configurer un projet Google Cloud.

1. Créez un projet dans la console Google Cloud :
   • Consultez Créer un projet dans Google Cloud Platform.
     
   • Saisissez un Nom du projet approprié (par exemple, "Projet d'API ARCore Geospatial") et sélectionnez un emplacement.
   • Cliquez sur Créer.
2. Activez les API nécessaires :
   • Dans la barre latérale, sélectionnez API et services, puis Bibliothèque.
   • Recherchez l'API ARCore.
   • Cliquez sur Activer.
   • Revenez à la bibliothèque.
   • Recherchez le SDK Maps pour Android.
   • Cliquez sur Activer.
3. Créez des identifiants de clé API :
   • Sous API et services, sélectionnez Identifiants.
   • Dans la barre supérieure, cliquez sur Créer des identifiants, puis sélectionnez Clé API.
   • Notez la clé qui a été créée, car vous en aurez besoin pour l'étape suivante. Revenez à la page Identifiants si vous devez le récupérer.

Vous venez de créer un projet Google Cloud avec une autorisation par clé API et vous êtes prêt à utiliser l'API Geospatial.

Intégrer la clé API au projet Android Studio

Pour associer la clé API de Google Cloud à votre projet, ouvrez le projet que vous avez créé dans Android Studio et modifiez les clés API :

1. Ouvrez app > src > AndroidManifest.xml.
2. Recherchez les entrées meta-data suivantes :

   <meta-data
       android:name="com.google.android.ar.API_KEY"
       android:value="PLACEHOLDER_API_KEY" />
   
   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="PLACEHOLDER_API_KEY" />
   

3. Remplacez PLACEHOLDER_API_KEY par la clé API que vous avez créée dans votre projet Google Cloud.

La valeur stockée dans com.google.android.ar.API_KEY autorise cette application à utiliser l'API Geospatial, et la valeur stockée dans com.google.android.geo.API_KEY autorise cette application à utiliser le SDK Google Maps.

Valider votre projet

Assurez-vous que votre projet est prêt. Dans Android Studio, exécutez votre application. Vous devriez voir une vue de la caméra, ainsi qu'une carte fonctionnelle en bas de l'écran.

3. Déterminer la position de l'utilisateur

Dans cette étape, vous allez ajouter du code à l'exemple de projet pour commencer à utiliser l'API Geospatial.

Configurer la session ARCore pour utiliser l'API Geospatial

Pour obtenir des données géospatiales, vous devez activer l'API Geospatial. Remplacez GeospatialMode par ENABLED dans la configuration de votre session en modifiant la fonction configureSession dans HelloGeoActivity.kt :

fun configureSession(session: Session) {
  session.configure(
    session.config.apply {
      // Enable Geospatial Mode.
      geospatialMode = Config.GeospatialMode.ENABLED
    }
  )
}

Lorsque le mode Geospatial est défini sur ENABLED, l'application peut obtenir des informations géospatiales.

Demander des données à l'API Geospatial

Dans HelloGeoRenderer.kt, recherchez la ligne suivante :

// TODO: Obtain Geospatial information and display it on the map.

En dessous, vérifiez que l'objet Earth est disponible. C'est le cas lorsqu'il comporte trackingState TrackingState.ENABLED.

val earth = session.earth
if (earth?.trackingState == TrackingState.TRACKING) {
  // TODO: the Earth object may be used here.
}

Sous TODO, demandez des informations géospatiales à ARCore. Ajoutez la ligne suivante :

val cameraGeospatialPose = earth.cameraGeospatialPose

Vous obtenez ainsi un GeospatialPose contenant les informations suivantes :

• Emplacement, exprimé en latitude et en longitude. Une estimation de la précision de la localisation est également fournie.
• l'altitude et une estimation de sa précision.
• Cap, une approximation de la direction vers laquelle l'appareil est orienté, et une estimation de la précision du cap.

Afficher les informations de positionnement sur la carte

Vous pouvez utiliser le GeospatialPose stocké dans cameraGeospatialPose pour déplacer un repère sur la carte qui indique où se trouve l'utilisateur. Reprenez là où vous vous êtes arrêté et ajoutez ce qui suit :

activity.view.mapView?.updateMapPosition(
  latitude = cameraGeospatialPose.latitude,
  longitude = cameraGeospatialPose.longitude,
  heading = cameraGeospatialPose.heading
)

Cela met à jour en permanence la position de la carte à l'aide des valeurs obtenues à partir de l'API Geospatial.

Essayer

Dans Android Studio, cliquez sur Play (Lire). Tenez votre appareil et déplacez-le pour aider ARCore à établir le suivi. Après un court instant, un repère vert devrait s'afficher sur la carte. Ce repère pivote lorsque vous regardez autour de vous. Elle doit également pointer dans la bonne direction : lorsque vous êtes physiquement orienté vers le nord, la flèche doit également pointer vers le nord.

4. Placer une ancre à l'aide de coordonnées terrestres

L'API Geospatial peut placer des ancres à n'importe quelle paire de coordonnées et rotation dans le monde réel. Cela permet à vos utilisateurs de voir des contenus ancrés lorsqu'ils visitent des lieux spécifiques.

Dans cette étape, vous allez ajouter un moyen de placer un ancrage en appuyant sur la carte.

Définir une action lorsque l'utilisateur appuie sur la carte

Le projet est fourni avec une fonction onMapClick, qui est appelée avec une latitude et une longitude lorsque l'utilisateur clique sur le fragment de carte. Recherchez la fonction onMapClick dans HelloGeoRenderer.kt.

Vérifier que l'objet Earth peut être utilisé

Avant de créer des ancres sur la Terre, assurez-vous que la propriété TrackingState de l'objet Terre est définie sur TRACKING, ce qui signifie que la position de la Terre est connue. Assurez-vous également que son EarthState est défini sur ENABLED, ce qui signifie qu'aucun problème n'a été rencontré avec l'API Geospatial. Ajoutez les lignes suivantes dans onMapClick :

val earth = session?.earth ?: return
if (earth.trackingState != TrackingState.TRACKING) {
  return
}

Déterminer le positionnement du nouvel ancrage

Après avoir confirmé que l'objet Terre est suivi, détachez le earthAnchor précédent, le cas échéant. Vous allez remplacer earthAnchor par une nouvelle ancre lors des prochaines étapes :

earthAnchor?.detach()

Utilisez ensuite cameraGeospatialPose pour déterminer l'altitude de la nouvelle ancre. Utilisez la paire de coordonnées issue du geste d'appui sur la carte comme positionnement de l'ancrage.

// Place the earth anchor at the same altitude as that of the camera to make it easier to view.
val altitude = earth.cameraGeospatialPose.altitude - 1
// The rotation quaternion of the anchor in the East-Up-South (EUS) coordinate system.
val qx = 0f
val qy = 0f
val qz = 0f
val qw = 1f
earthAnchor =
  earth.createAnchor(latLng.latitude, latLng.longitude, altitude, qx, qy, qz, qw)

createAnchor crée un Anchor fixé à des coordonnées géodésiques avec une rotation donnée. Cette ancre tente de rester stable et fixe aux coordonnées et à l'altitude spécifiées.

Les variables [qx, qy, qz, qw] déterminent la rotation de l'ancrage exprimée en quaternions, dans le système de coordonnées East-Up-South (EUS). Vous utilisez différentes valeurs pour faire pivoter l'ancrage, mais dans cet exemple, utilisez un quaternion unitaire pour la rotation par défaut. Dans une rotation de quaternion unitaire, l'ancrage est orienté de sorte que X+ pointe vers l'est, Y+ pointe vers le haut en s'éloignant du centre de la Terre et Z+ pointe vers le sud.

Afficher le repère placé sur la carte

Enfin, déplacez un nouveau repère pour indiquer où le repère a été placé :

activity.view.mapView?.earthMarker?.apply {
  position = latLng
  isVisible = true
}

Essayer

Dans Android Studio, cliquez sur Play (Lire). Tenez votre appareil et déplacez-le pour aider ARCore à établir le suivi. Au bout de quelques instants, un repère vert devrait apparaître sur la carte pour indiquer votre position actuelle.

Lorsque vous appuyez sur la carte, l'API Geospatial place une ancre, qui est fixée à un emplacement réel. Essayez de placer l'ancre près de votre position actuelle pour pouvoir la voir dans la vue RA. Il doit rester stable lorsque vous naviguez dans votre environnement.

5. Conclusion

Dans cet atelier de programmation, vous avez appris à utiliser l'API Geospatial pour créer une expérience de RA simple liée au monde réel.

Points abordés

• Configurer un projet Google Cloud avec l'API Geospatial activée
• Obtenir des informations géospatiales dans un projet ARCore et les afficher sur une carte
• Découvrez comment placer une ancre positionnée dans le monde réel à l'aide du positionnement géographique.

Ressources supplémentaires

Pour en savoir plus sur les concepts géographiques et les SDK utilisés dans cet atelier de programmation, consultez les ressources supplémentaires suivantes :

• Documentation de l'API ARCore Geospatial
• World Geodetic System (WGS)
• SDK Google Maps pour Android