Premiers pas avec Geospatial Creator dans Unity

ARCore Geospatial Creator pour Unity vous permet de prévisualiser du contenu géospatial dans l'éditeur Unity en affichant des données Google Maps dans un nouveau format de tuiles 3D. Cela vous aide à visualiser où le contenu sera placé dans le monde réel pendant que vous développez votre application.

Geospatial Creator est disponible dans les extensions ARCore pour ARFoundation. Ce guide de démarrage rapide vous explique comment utiliser Geospatial Creator dans Unity pour ajouter du contenu de RA géospatial à l'application exemple ARCore Geospatial.

Si vous disposez d'une application existante que vous souhaitez utiliser à la place de l'exemple géospatial, vous devez d'abord suivre notre Guide du développeur Geospatial pour Unity. Une fois votre application configurée pour l'utilisation de l'API Geospatial, passez à l'étape Ajouter les dépendances requises ci-dessous et continuez à partir de là.

Prérequis

Suivez Premiers pas avec les extensions ARCore pour AR Foundation afin de configurer votre environnement Unity pour créer des expériences de RA.

Bien que les extensions ARCore soient compatibles avec les versions antérieures d'Unity, Geospatial Creator nécessite Unity 2021.3 ou version ultérieure.

Autorisation de l'API

Vous devrez configurer l'accès aux API pour utiliser l'API ARCore Geospatial et l'API Google Map Tiles.

API Google Map Tiles

L'API Map Tiles fournit une représentation 3D photoréaliste des lieux compatibles. Nous utiliserons ces tuiles dans l'éditeur Unity pour prévisualiser la zone autour de votre scène AR.

Consultez la page de l'API Map Tiles pour activer l'API et en savoir plus sur Map Tiles.

API ARCore Geospatial

L'API ARCore Geospatial est utilisée par votre application au moment de l'exécution pour créer des ancres géospatiales et interagir avec elles.

Pour activer les API Geospatial, configurez l'API ARCore dans votre application. Vous pouvez utiliser la méthode d'autorisation sans clé (recommandée) ou avec clé API.

Étendre l'application exemple géospatiale

Dans ce guide, nous allons vous montrer comment utiliser Geospatial Creator pour ajouter du contenu géospatial à l'application exemple ARCore Geospatial.

Configurer l'exemple de données géospatiales

Commencez par vous familiariser avec l'application exemple ARCore Geospatial. Dans un nouveau projet Unity, ouvrez le gestionnaire de packages Unity et sélectionnez le package ARCore Extensions. Dans le panneau d'informations du gestionnaire de packages, développez Exemples et importez l'exemple géospatial dans votre projet Unity.

Avant d'exécuter l'application, vous devez activer les fonctionnalités ARCore et Geospatial dans votre projet. Utilisez Modifier > Paramètres du projet… > XR Plug-in Management (Gestion des plug-ins XR). Cochez les cases appropriées pour activer le fournisseur de plug-in ARCore pour Android et/ou le fournisseur de plug-in ARKit pour iOS.

Ensuite, accédez à Edit > Project Settings… > XR Plug-in Management (Gestion des plug-ins XR), ouvrez le panneau ARCore Extensions (Extensions ARCore). Assurez-vous que l'option "Géospatial" est cochée (vous n'avez pas encore besoin d'activer Geospatial Creator), puis saisissez vos identifiants API. Pour en savoir plus, consultez la documentation "Activer l'API Geospatial Unity" pour Android et iOS.

Il existe d'autres paramètres du lecteur spécifiques à la plate-forme qui sont requis pour toute application Unity utilisant ARCore. Consultez la section Configurer les paramètres du lecteur de notre documentation pour connaître les modifications requises.

À ce stade, votre scène ne contient aucun objet de jeu, à l'exception de ceux nécessaires à l'exécution de l'exemple Geospatial. C'est le bon moment pour compiler et exécuter l'application. Si elle est correctement configurée, elle affichera la vue de la caméra de votre appareil lors de l'exécution. À mesure que vous vous déplacez, la précision géospatiale affichée en haut de l'écran s'améliore. En appuyant sur l'écran, vous créez des ancres géospatiales qui restent à leur emplacement d'origine lorsque vous vous déplacez.

Nous allons ensuite vous montrer comment utiliser Geospatial Creator pour créer et visualiser du contenu de RA sophistiqué dans l'éditeur Unity. Ce contenu s'affichera dans votre application à des coordonnées de latitude et de longitude spécifiques dans le monde.

Ajouter les dépendances requises

Geospatial Creator utilise un package Unity tiers appelé Cesium pour afficher les tuiles Google Maps dans la fenêtre "Scene" de l'éditeur Unity. Avant d'activer les fonctionnalités Geospatial Creator, ajoutons le package Cesium à votre projet.

Nous vous recommandons d'installer la dernière version du package Cesium pour Unity à partir de la page GitHub de Cesium :

  1. Téléchargez la dernière version de .tgz précompilé de Cesium pour Unity sur la page des versions GitHub. La version recommandée actuelle du package Cesium pour Unity est la version 1.1.0.
  2. Ouvrez le gestionnaire de paquets Unity en cliquant sur le menu "Window " (Fenêtre) d'Unity, puis en sélectionnant "Package Manager" (Gestionnaire de paquets).
  3. Cliquez sur l'icône "+" et sélectionnez "Add package from tarball" (Ajouter un package à partir d'une archive tar).
  4. Sélectionnez le fichier .tgz Cesium pour Unity téléchargé à l'étape 1.
  5. Vous serez peut-être invité à installer des dépendances supplémentaires, comme Text Mesh Pro.

Ajouter un package .tgz avec le gestionnaire de packages Unity

Activer Geospatial Creator

Vous êtes maintenant prêt à activer Geospatial Creator :

  1. Dans la boîte de dialogue "Build Settings" (Paramètres de compilation), assurez-vous que la plate-forme sélectionnée est "Android" ou "iOS". Les fonctionnalités Geospatial Creator ne sont pas disponibles pour les autres plates-formes pour le moment.
  2. Accédez à Project Settings > XR Plug-in Management > ARCore Extensions (Paramètres du projet > Gestion des plug-ins XR > Extensions ARCore).
  3. Si vous n'avez pas défini vos clés API ARCore pour Android et/ou iOS lors d'une étape précédente, veillez à le faire maintenant.
  4. Activez les options "Geospatial" et "Geospatial Creator". Après avoir cliqué pour activer le bouton bascule Geospatial Creator, un assistant non modal s'affiche pour confirmer que votre projet est compatible avec Geospatial Creator.
  5. Cliquez sur "Terminer" dans l'assistant.

Une fois l'assistant terminé, Unity déclenche une compilation de vos scripts. Attendez la fin de la recompilation avant de continuer. (Si la plate-forme sélectionnée n'est pas "Android" ni "iOS", passez à l'une de ces plates-formes maintenant.)

Ajouter une origine Geospatial Creator avec des tuiles de carte

Votre scène doit contenir un seul objet "Origine du créateur géospatial". Cet objet sert de point de référence pour convertir les valeurs réelles de latitude, de longitude et d'altitude en coordonnées de jeu Unity.

Pour ajouter une origine Geospatial Creator à votre scène, sélectionnez Game Object > XR > Geospatial Creator Origin (Objet de jeu > XR > Origine Geospatial Creator). L'objet nouvellement créé nécessite une géoréférence, qui associe une latitude, une longitude et une altitude spécifiques à la position de l'origine dans les coordonnées du jeu. Dans le volet Inspector (Inspecteur) de l'origine Geospatial Creator, ajoutez une géoréférence en cliquant sur le bouton Add Cesium Georeference Component (Ajouter un composant de géoréférencement Cesium).

Ajouter l'objet de jeu "Geospatial Creator Origin"

En plus d'être le point de référence pour vos objets de RA, la géoréférence Cesium ajoute un objet Cesium 3D Tileset à la scène. Cet objet affichera les tuiles Google Maps dans la vue Scène de l'éditeur, ce qui vous permettra de visualiser exactement où votre contenu de RA apparaîtra dans le monde. L'inspecteur de l'origine Geospatial Creator comporte un champ permettant d'ajouter la clé API Map Tiles que vous avez configurée précédemment. Une fois cette clé définie, les tuiles de carte devraient se charger dans la vue "Scène".

Modifiez maintenant les champs de latitude, de longitude et de hauteur pour vous situer à l'endroit où vous souhaitez que le contenu de RA apparaisse dans votre application.

La vue Scène de l'éditeur doit maintenant afficher les tuiles de carte à la latitude et à la longitude spécifiées de votre origine. Lors de l'exécution, nous supposons que votre application utilisera la caméra AR. Geospatial Creator a donc déjà configuré l'objet Cesium 3D Map Tileset avec le tag "EditorOnly". De ce fait, les tuiles ne seront pas téléchargées ni affichées au moment de l'exécution dans votre jeu. Vous pouvez modifier ce paramètre dans l'inspecteur de l'objet Cesium3DTileset. Pour en savoir plus sur les GameObjects de géoréférencement et de tilesets 3D de Cesium, consultez la documentation Cesium pour Unity.

Ajouter et placer une ancre Geospatial Creator

Vous êtes maintenant prêt à placer du contenu de RA dans votre scène. Cliquez sur GameObject > XR > Geospatial Creator Anchor (GameObject > XR > Ancre Geospatial Creator) pour ajouter une ancre à la hiérarchie de votre scène. Dans l'inspecteur d'ancrage, vous pouvez spécifier une latitude, une longitude et une hauteur exactes. La transformation de l'objet est immédiatement mise à jour pour correspondre à la position correcte dans votre scène. Vous pouvez ainsi voir exactement où l'objet apparaîtra dans le monde.

Ajouter l'ancre Geospatial Creator

Lorsque vous ajustez la latitude et la longitude de l'ancrage, choisissez un lieu à proximité pour pouvoir vérifier qu'il se trouve au bon endroit au moment de l'exécution. Lorsque vous définissez l'altitude d'une ancre Geospatial Creator, vous avez trois options :

  • Terrain place l'ancrage au niveau du sol à la latitude et à la longitude spécifiées. Le niveau du sol est déterminé au moment de l'exécution par le système de positionnement visuel. Si vous ne connaissez pas les API géospatiales d'ARCore, "Terrain" est un bon choix, car l'ancrage sera résolu directement au sol avec un haut degré de précision verticale. Le champ "Décalage d'altitude" vous permet de positionner l'ancre au-dessus ou en dessous du niveau du sol d'un montant fixe, en mètres. Par exemple, si vous spécifiez un décalage de "1.0", l'ancrage "flotte" à un mètre au-dessus du terrain.
  • Toit place l'ancrage par rapport au sommet de n'importe quelle structure à la latitude et à la longitude données. Comme pour l'ancrage au terrain, le champ "Décalage d'altitude" vous permet de déplacer l'ancrage vers le haut ou vers le bas par rapport à la position du toit, en mètres.
  • WGS84 place l'ancrage à une altitude absolue spécifique, en mètres, en fonction du système de coordonnées WGS84. Il faudra peut-être procéder à quelques essais pour placer l'objet de cette manière, car une hauteur de "0" dans WGS84 n'indique pas nécessairement le niveau moyen de la mer et peut ne pas correspondre à l'altitude d'un GPS. De plus, bien que la latitude et la longitude des tuiles 3D affichées soient très précises, tenter de placer l'objet au niveau du sol en utilisant les tuiles 3D comme référence peut entraîner une erreur de hauteur pouvant atteindre plusieurs mètres.

Pour en savoir plus sur les différents types d'ancrages ARCore Geospatial, consultez le guide du développeur Geospatial.

Les ancres de terrain et de toit comportent un champ Altitude WGS84. Cette valeur n'est utilisée que dans le mode Éditeur pour définir la hauteur de l'objet dans la vue Scène. La hauteur du terrain et des toits n'est déterminée qu'au moment de l'exécution. Le champ Altitude WGS84 vous permet donc de visualiser l'ancrage à une hauteur spécifique lors du développement de l'application. Le champ Altitude WGS84 est ignoré au moment de l'exécution pour les ancrages de terrain et de toit.

Ajouter une géométrie à l'ancrage

Si vous compilez et exécutez l'application maintenant, vous ne verrez pas l'ancrage dans votre application compatible avec la RA, car aucune géométrie n'y est associée. Ajoutons une primitive 3D simple à l'ancrage : dans la hiérarchie de la scène, effectuez un clic droit sur votre objet AR Geospatial Creator Anchor. Dans le menu contextuel, sélectionnez Objet 3D > Cube. Vous devriez voir un cube gris dans la vue de scène en tant qu'enfant de votre point d'ancrage. Si vous décidez de modifier la position ou la rotation de l'objet dans l'éditeur, nous vous recommandons de déplacer l'objet Anchor racine au lieu de la primitive Cube enfant. Cela permettra de réduire les erreurs de traduction des coordonnées de latitude / longitude en coordonnées de jeu.

Ancre Geospatial Creator avec une primitive Cube

Bien sûr, vous pouvez également ajouter une géométrie plus complexe, ainsi que des composants et des enfants arbitraires à l'ancrage.

Compiler et exécuter votre application

Il est temps de voir votre ancre dans le monde réel ! Essayez de créer et d'exécuter votre application, puis déplacez-vous vers l'emplacement où vous vous attendez à voir le cube. Est-ce que c'est là ? Félicitations, vous êtes prêt à créer des expériences de RA plus complexes avec Geospatial Creator !

Si vous rencontrez des problèmes, consultez le guide de dépannage.

C'est le moment idéal pour ajouter d'autres ancres AR Geospatial Creator avec différentes géométries. Essayez d'expérimenter avec plusieurs ancres de toit et de terrain, ainsi que leurs décalages. Ajoutez des scripts pour animer les objets ou permettre les interactions avec eux.

Comprendre les ancres Geospatial Creator et la classe ARGeospatialAnchor

Lorsque vous créez des expériences de RA complexes et interactives, il est utile de comprendre la relation entre les ancrages Geospatial Creator et la classe C# ARGeospatialAnchor d'ARCore :

Un ARGeospatialAnchor ne peut être créé qu'au moment de l'exécution en appelant l'une des fonctions sur ARAnchorManager, et uniquement une fois que la session AR s'est stabilisée. Une ancre Geospatial Creator peut être considérée comme un espace réservé dans votre scène, en attendant que la session de RA soit prête à résoudre les objets ARGeospatialAnchor. Une fois la session prête, le code de substitution appellera automatiquement ARAnchorManager pour créer et résoudre le ARGeospatialAnchor.

Immédiatement après la résolution de l'ancrage d'exécution, l'ancrage Geospatial Creator de la hiérarchie de votre scène s'attachera en tant qu'enfant au nouveau GameObject. Cela signifie que tous les composants ou enfants de l'ancrage Geospatial Creator deviendront des sous-composants ou des petits-enfants du nouveau GameObject ARGeospatialAnchor. Par exemple, le transform d'une primitive géométrique associée à l'ancrage Geospatial Creator hérite du transform de ARGeospatialAnchor et est donc placé à l'emplacement attendu dans la session de RA d'exécution.

Si vous devez identifier des ARGeospatialAnchor GameObjects spécifiques au moment de l'exécution, vous pouvez rechercher dans la scène les objets dont la propriété name correspond à l'ancrage créé à l'aide de Geospatial Creator. Si la session AR est initialisée, le parent de cet objet sera l'objet ARGeospatialAnchor correspondant.

Dépannage

Pourquoi mon point d'ancrage se déplace-t-il ?

Vous remarquerez peut-être, surtout au premier lancement de l'application, que l'ancrage peut sembler "dériver" lentement, voire sauter brusquement de plusieurs mètres. Cela se produit lorsque la session VPS est encore en train de déterminer et d'affiner la position exacte de la caméra. À mesure que la précision horizontale et verticale s'améliore au fil des images, l'ancrage est redessiné à un emplacement plus précis, ce qui donne l'illusion d'un mouvement. Vous pouvez choisir d'afficher l'objet différemment (ou pas du tout) jusqu'à ce que la précision de la position atteigne un certain seuil. Pour ce faire, vous pouvez interroger la propriété ARCoreEarthManager.CameraGeospatialPose afin de déterminer la précision de la mise à jour actuelle du frame.

Pourquoi mon point d'ancrage apparaît-il à la mauvaise altitude ?

Lorsque vous utilisez le type d'altitude "Manuel" pour les ancres Geospatial Creator, l'altitude de l'ancre (en mètres) est définie selon WGS84. À un endroit donné, il peut y avoir une différence de plusieurs mètres entre le niveau du sol apparent affiché dans les tuiles de carte et le niveau du sol réel tel qu'indiqué par le système de positionnement visuel (VPS) de Google. Si une ancre géospatiale semble être mal placée au moment de l'exécution, nous vous recommandons de valider la hauteur VPS en personne à l'aide de la superposition de débogage dans l'application exemple. Vous pouvez ensuite modifier l'altitude dans l'éditeur Unity pour qu'elle corresponde à la hauteur VPS connue à cet emplacement.

Les tuiles de carte ne s'affichent pas correctement dans la vue "Scene" (Scène) de l'éditeur

Si Cesium3DTileset semble charger des tuiles, mais qu'elles sont affichées en magenta uni dans la vue de scène, ajoutez le package Shader Graph d'Unity à votre projet. Ce package est requis par Cesium, mais les projets utilisant le moteur de rendu intégré d'Unity ne l'incluent pas par défaut.

Pour ajouter Shader Graph, ouvrez le gestionnaire de packages Unity (Window > Package Manager). Assurez-vous de parcourir les packages disponibles dans le registre de packages Unity en sélectionnant "Packages : registre Unity" dans le menu déroulant en haut de la fenêtre du gestionnaire de packages. Recherchez le package com.unity.shadergraph et installez la dernière version. Une fois le package chargé, les tuiles 3D devraient se recharger et s'afficher correctement dans la vue Scène.

L'application affiche un écran noir au moment de l'exécution au lieu de la vue de la caméra

Le pipeline de rendu universel (URP) d'Unity n'est pas configuré par défaut pour la caméra AR. Si vous voyez un écran noir au moment de l'exécution au lieu de la sortie de la caméra, vous devez ajouter AR Background Renderer Feature à chaque rendu URP de votre scène.

Ajouter la fonctionnalité de rendu d'arrière-plan AR

Pour ajouter la fonctionnalité, recherchez "renderer" dans votre projet. Pour chaque objet URP Renderer, cliquez sur le bouton "Add Renderer Feature" (Ajouter une fonctionnalité de rendu) dans l'inspecteur, puis ajoutez AR Background Renderer.

Pourquoi les ancres placées loin de l'origine semblent-elles mal positionnées ?

La conversion des coordonnées WGS84 en coordonnées de jeu Unity est sujette à des erreurs en raison de la précision de l'arithmétique à virgule flottante. Vous pouvez les minimiser en vous assurant que votre origine est proche de vos ancres AR. Les distances supérieures à 20 km peuvent entraîner des inexactitudes. Si votre expérience de RA s'étend sur de longues distances, nous vous recommandons d'utiliser plusieurs scènes, avec une ancre unique dans chacune d'elles.