Premiers pas avec les API Streetscape Geometry et Rooftop Anchors dans ARCore

Premiers pas avec les API Streetscape Geometry et Rooftop Anchors dans ARCore

À propos de cet atelier de programmation

Dernière mise à jour : avr. 20, 2023

Rédigé par Dereck Bridie

1. Avant de commencer

ARCore est le framework de Google qui permet de créer des expériences de réalité augmentée (RA) sur smartphone. Avec les API Geospatial Streetscape Geometry et Rooftop Anchor, vos expériences de RA peuvent analyser les bâtiments situés autour de vos utilisateurs.

Dans cet atelier de programmation, vous allez créer une application de RA qui visualise la géométrie du paysage urbain dans la zone où vous vous trouvez et qui vous permet d'en décorer les faces. Vous utiliserez ensuite des ancrages de toit pour ajouter des décorations en haut des toitures des bâtiments qui vous entourent.

Conditions préalables

• Vous disposez de connaissances de base sur la réalité augmentée.
• Vous disposez de connaissances de base sur l'API ARCore Geospatial.

Points abordés

• Configurer un projet Google Cloud pour utiliser les API ARCore Geospatial
• Obtenir une géométrie de paysage urbain à partir de l'API Geospatial
• Visualiser les bâtiments et terrains obtenus à partir de la géométrie du paysage urbain
• Réaliser des calculs simples sur les polygones obtenus
• Réaliser un test de positionnement sur la géométrie
• Utiliser des ancrages de toit pour attacher des contenus à la toiture des bâtiments

Ce dont vous avez besoin

• 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
• La version 1.37 ou ultérieure de Services Google Play pour la RA installée sur l'appareil de développement Android
• Android Studio installé et configuré pour la compilation d'applications Android

2. Configurer votre environnement

Pour utiliser les API Geospatial avec Kotlin et Android Studio, vous devez disposer d'un projet Google Cloud et de notre projet de démarrage.

Configurer un projet Google Cloud

L'API ARCore Geospatial se connecte à Google Cloud pour fournir des informations sur l'emplacement à partir du système VPS (Visual Positioning System) de Google dans les zones couvertes par Google Street View.

Pour utiliser ce serveur dans votre projet, procédez comme suit :

1. Créez un projet dans Google Cloud.
2. Dans le champ Nom du projet, saisissez un nom approprié, par exemple ARCore Geospatial API project, puis sélectionnez l'emplacement de votre choix.
3. Cliquez sur Créer.
4. Dans la console Google Cloud sur la page de sélection du projet, cliquez sur Créer un projet.
5. Cliquez sur le lien suivant pour afficher l'API ARCore dans ce projet, puis cliquez sur Activer :
   Activer l'API ARCore
6. Créez une clé API pour votre projet :
   1. Sous API et services, sélectionnez Identifiants.
   2. Cliquez sur Créer des identifiants et sélectionnez Clé API :
   3. Notez la clé, car vous en aurez besoin ultérieurement.

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

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é à l'API Geospatial.

Pour configurer Android Studio, procédez comme suit :

1. Ouvrez Android Studio, puis effectuez l'une des opérations suivantes :
   • Si vous avez déjà ouvert un projet, cliquez sur File > New > Project from version control (Fichier > Nouveau > Projet provenant d'un système de contrôle de versions).
   • Si vous voyez la fenêtre Welcome to Android Studio (Bienvenue dans Android Studio), cliquez sur Get from VCS (Obtenir depuis VCS).
2. Sélectionnez Git, puis saisissez https://github.com/google-ar/codelab-streetscape-geometry-rooftop-anchors.git pour importer le projet.

Intégrer la clé API au projet Android Studio

Pour associer la clé API de Google Cloud à votre projet, procédez comme suit :

1. Dans Android Studio, cliquez sur app > src, puis double-cliquez sur AndroidManifest.xml.
2. Recherchez les entrées meta-data suivantes :

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

3. Remplacez l'espace réservé 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.

Valider votre projet

• Pour valider votre projet, exécutez votre application sur votre appareil de développement. Vous devriez observer une vue de l'appareil photo et, en haut de l'écran, des informations géospatiales de débogage. Vous devriez également voir des boutons et des commandes qui ne semblent avoir aucune fonction : vous allez programmer leur fonctionnement dans votre projet lors de cet atelier.

Attention : Si l'API Geospatial ne s'initialise pas, vérifiez que la clé API a bien été insérée dans votre fichier AndroidManifest.xml exactement comme elle apparaît dans Google Cloud.

3. Visualiser des données de géométrie de paysage urbain

Après avoir confirmé que l'API Geospatial fonctionne sur votre appareil, vous allez récupérer une géométrie de paysage urbain à partir de l'API Geospatial.

Activer le mode streetscape-geometry

1. Dans le fichier StreetscapeGeometryActivity.kt, recherchez la ligne suivante :

   // TODO: Enable Streetscape Geometry.
   

2. Après cette ligne, activez le mode streetscape-geometry :

   streetscapeGeometryMode = Config.StreetscapeGeometryMode.ENABLED
   

   Une fois que l'API Geospatial et que le mode streetscape-geometry sont activés, votre application peut recevoir des informations de géométrie du paysage urbain qui entoure l'utilisateur.

Obtenir une géométrie de paysage urbain

1. Dans le fichier StreetscapeGeometryActivity.kt, recherchez la ligne suivante :

   // TODO: Obtain Streetscape Geometry.
   

2. Après cette ligne, obtenez la géométrie du paysage urbain en récupérant tous les objets Trackable et en filtrant par StreetscapeGeometry :

   val streetscapeGeometry = session.getAllTrackables(StreetscapeGeometry::class.java)
   

   Vous utiliserez ces éléments de géométrie dans une visualisation simple qui est fournie dans l'exemple de projet. La visualisation affiche chaque bâtiment ou polygone de terrain dans une couleur distincte.
3. À la ligne suivante, ajoutez le code ci-dessous :

   streetscapeGeometryRenderer.render(render, streetscapeGeometry)
   

4. Exécutez votre application et visitez un bâtiment dans votre région.
5. Une fois la localisation réalisée avec Geospatial, appuyez sur Paramètres  et activez la visualisation de la géométrie du paysage urbain.
6. Examinez un bâtiment en RA. Chaque bâtiment segmenté possède sa propre couleur, et les énumérations Quality et Type de la géométrie centrale sont affichées.

Attention : Si vous n'observez aucune géométrie de paysage urbain ou que vous ne voyez apparaître aucune décoration lorsque vous appuyez sur l'écran, suivez les étapes ci-dessous pour effectuer une réinitialisation à partir du point de contrôle de l'atelier de programmation.

1. Dans Android Studio, cliquez sur VCS > Git > Branches > Checkout > step-3 (VCS > Git > Branches > Extraire > step-3). Cette opération rétablit l'état de la troisième étape.
2. Ajoutez votre clé API au fichier AndroidManifest.xml comme expliqué dans les instructions de configuration.

4. Réaliser un test de positionnement avec des données de géométrie du paysage urbain

Maintenant que vous pouvez afficher la géométrie du paysage urbain, vous pouvez utiliser un test de positionnement pour décorer le bâtiment. Un test de positionnement permet de localiser l'intersection entre une géométrie virtuelle et un rayon. Vous allez utiliser un test de positionnement pour trouver l'élément de géométrie sur lequel l'utilisateur appuie.

Réaliser un test de positionnement

Dans cette section, vous allez placer une étoile sur la façade d'un bâtiment lorsque l'utilisateur appuie sur la géométrie correspondante. Pour cela, vous allez utiliser un test de positionnement à partir de la perspective de l'utilisateur dans le monde réel et vous allez enregistrer les objets de RA rencontrés par le test dans sa progression vers l'extérieur. Ensuite, vous allez utiliser ces informations pour vérifier si l'utilisateur a appuyé sur le polygone d'un bâtiment.

1. Dans le fichier StreetscapeCodelabRenderer.kt, recherchez la ligne suivante :

   // TODO: Create an anchor for a star, and add it to the starAnchors object.
   

2. Après cette ligne, ajoutez le code suivant :

   val centerHits = frame.hitTest(centerCoords[0], centerCoords[1])
   val hit = centerHits.firstOrNull {
     val trackable = it.trackable
     trackable is StreetscapeGeometry && trackable.type == StreetscapeGeometry.Type.BUILDING
   } ?: return
   

   Ce code se base sur les coordonnées centrales pour identifier une géométrie dans le paysage urbain qui correspond à un bâtiment. Vous allez utiliser ce résultat pour ajouter des décorations.

Ajouter une étoile en décoration en appuyant sur l'écran

1. Dans le fichier StreetscapeCodelabRenderer.kt, recherchez la ligne suivante :

   // TODO: Create an anchor for a star, and add it to the starAnchors object.
   

2. Après cette ligne, ajoutez le code suivant :

   val transformedPose = ObjectPlacementHelper.createStarPose(hit.hitPose)
   val anchor = hit.trackable.createAnchor(transformedPose)
   starAnchors.add(anchor)
   

   La classe ObjectPlacementHelper détermine un emplacement approprié pour placer votre étoile en examinant l'objet "pose" identifié dans le test d'emplacement. L'objet starAnchors sert à effectuer le rendu des étoiles dans la vue de RA.

Essayer

1. Exécutez votre application et visitez un bâtiment dans votre région.
2. Une fois la localisation géospatiale effectuée, dirigez votre appareil photo vers le bâtiment et appuyez sur l'écran. Vous voyez une étoile apparaître sur le bâtiment au centre de l'écran.

Attention : Si vous n'observez aucune géométrie de paysage urbain ou que vous ne voyez apparaître aucune décoration lorsque vous appuyez sur l'écran, suivez les étapes ci-dessous.

1. Dans Android Studio, cliquez sur VCS > Git > Branches > Checkout > step-4 (VCS > Git > Branches > Extraire > step-4).
2. Ajoutez votre clé API au fichier AndroidManifest.xml comme expliqué dans les instructions de configuration.

5. Utiliser des données d'ancrage de toit

Pour finir, vous allez utiliser des ancrages de toit afin d'ajouter des décorations à la toiture des bâtiments. Les ancrages de toit vous permettent d'attacher des ancres de RA à la toiture des bâtiments à partir d'une latitude et d'une longitude. Vous allez utiliser ces ancrages pour attacher des ballons à des bâtiments situés autour de l'utilisateur.

Ajouter des comportements au mode Ballon

Le projet comporte deux modes de placement d'assets : le mode Tournesol, que vous avez déjà utilisé, et le mode Ballon.

Pour programmer un comportement en mode Ballon, procédez comme suit :

1. Dans le fichier StreetscapeCodelabRenderer.kt, recherchez la ligne suivante :

   // TODO: Create an anchor for a balloon and add it to the balloonAnchors object.
   

2. Utilisez l'objet "pose" identifié par le test d'emplacement afin de créer un emplacement idéal pour votre ballon :

   val transformedPose = ObjectPlacementHelper.createBalloonPose(hit.hitPose)
   

3. Convertissez la variable transformedPose en objet "pose" géospatial :

   val earth = session?.earth ?: return
   val geospatialPose = earth.getGeospatialPose(transformedPose)
   

4. Créez un ancrage de toit utilisant la latitude et la longitude transformées :

   earth.resolveAnchorOnRooftopAsync(
     geospatialPose.latitude, geospatialPose.longitude,
     0.0,
     transformedPose.qx(), transformedPose.qy(), transformedPose.qz(), transformedPose.qw()
   ) { anchor, state ->
     if (!state.isError) {
       balloonAnchors.add(anchor)
     }
   }
   

Essayer

1. Exécutez votre application et visitez un bâtiment dans votre région.
2. Une fois la localisation géospatiale effectuée, passez en mode Ballon et appuyez sur un bâtiment. Vous voyez un ballon apparaître au dessus du bâtiment.

Si vous ne parvenez pas à reproduire le comportement attendu, suivez les étapes ci-dessous :

1. Dans Android Studio, cliquez sur VCS > Git > Branches > Checkout > step-5 (VCS > Git > Branches > Extraire > step-5).
2. Ajoutez votre clé API au fichier AndroidManifest.xml comme expliqué dans les instructions de configuration.

6. Conclusion

Félicitations ! Vous venez de créer une application de RA qui visualise la géométrie du paysage urbain dans la zone où vous vous trouvez et qui vous permet d'en décorer les faces à l'aide d'étoiles. Vous avez également utilisé des ancrages de toit pour ajouter des ballons à la toiture des bâtiments qui vous entourent.

En savoir plus

• Guide du développeur pour l'API Streetscape Geometry
• Guide du développeur pour l'API Rooftop Anchors
• Présentation de l'API Geospatial