ARCore Geospatial Creator pour Unity vous permet de prévisualiser le contenu géospatial dans l'éditeur Unity en affichant les données Google Maps dans un nouveau format de tuiles 3D. Cela vous permet de visualiser où le contenu sera placé dans le monde réel, pendant que vous créez votre application.
Geospatial Creator est disponible dans le cadre de la base ARCore Extensions pour la RA. Ce guide de démarrage rapide explique comment utiliser Geospatial Creator dans Unity pour ajouter du contenu de RA géospatiale à l'application exemple ARCore Geospatial.
Si vous souhaitez utiliser une application existante à la place de l'exemple Geospatial, vous devez d'abord suivre le guide du développeur Geospatial pour Unity. Une fois votre application configurée pour l'API Geospatial, passez à l'étape Ajouter les dépendances requises ci-dessous, puis continuez à partir de là.
Prérequis
Suivez le guide Premiers pas avec les extensions ARCore pour la RA Foundation pour configurer votre environnement Unity afin de créer des expériences de RA.
Bien que les extensions ARCore soient compatibles avec les versions antérieures d'Unity, Geospatial Creator a besoin d'Unity 2021.3 ou version ultérieure.
Autorisation de l'API
Pour utiliser les API ARCore Geospatial et Google Map Tiles, vous devez configurer l'accès aux API.
API Google Map Tiles
L'API Map Tiles fournit une représentation 3D photoréaliste des lieux acceptés. Nous utiliserons ces tuiles dans l'éditeur Unity pour prévisualiser la zone autour de votre scène de RA.
Consultez la page de l'API Map Tiles pour activer l'API et en savoir plus sur les tuiles de carte.
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 les clés API.
Étendre l'application exemple Geospatial
Dans ce guide, vous allez découvrir comment utiliser Geospatial Creator pour ajouter du contenu géospatial à l'application exemple ARCore Geospatial.
Configurer l'exemple Geospatial
Tout d'abord, familiarisez-vous avec l'application exemple ARCore Geospatial. Dans un nouveau projet Unity, ouvrez le gestionnaire de packages Unity et sélectionnez le package d'extensions ARCore. Dans le panneau de détails du gestionnaire de packages, développez Samples (Exemples) et importez l'échantillon 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-ins ARCore pour Android et/ou le fournisseur de plug-ins ARKit pour iOS.
Accédez ensuite à Modifier > Paramètres du projet... > XR Plug-in Management (Gestion des plug-ins XR), puis ouvrez le panneau ARCore Extensions (Extensions ARCore). Assurez-vous que l'option "Geospatial" est cochée (vous n'avez pas besoin d'activer Geospatial Creator pour le moment), puis saisissez vos identifiants pour l'API. Pour en savoir plus, consultez la documentation "Activer l'API Geospatial Unity" pour Android et iOS.
D'autres paramètres de joueur spécifiques à la plate-forme sont requis pour toute application Unity qui utilise ARCore. Consultez la section Configurer les paramètres du joueur de notre documentation pour connaître les modifications requises.
À ce stade, votre scène ne contient aucun objet de jeu autre que ce qui est nécessaire pour exécuter l'exemple Geospatial. C'est le bon moment pour compiler et exécuter l'application. Si elle est configurée correctement, l'application affichera la vue de la caméra de votre appareil au moment de l'exécution. À mesure que vous vous déplacez, la précision géospatiale affichée en haut de l'écran commence à s'améliorer. En appuyant sur l'écran, vous créez des ancres géospatiales qui seront conservées à leur emplacement d'origine lorsque vous vous déplacez.
Nous verrons ensuite comment utiliser Geospatial Creator pour créer et visualiser du contenu de RA sophistiqué depuis l'éditeur Unity. Ce contenu apparaîtra dans votre application à des emplacements de latitude / 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:
- Téléchargez la version la plus récente du
.tgzprécompilé de Cesium pour Unity sur la page des versions GitHub. La version actuelle recommandée du package Cesium pour Unity est la version 1.1.0. - Ouvrez le gestionnaire de packages Unity en cliquant sur le menu "Window " (Fenêtre) d'Unity, puis en sélectionnant "Package Manager" (Gestionnaire de packages).
- Cliquez sur l'icône "+" et choisissez "Ajouter un package depuis tarball".
- Sélectionnez le fichier .tgz Cesium pour Unity téléchargé à l'étape 1.
- Vous serez peut-être invité à installer des dépendances supplémentaires, comme Text Mesh Pro.
Activer Geospatial Creator
Vous êtes maintenant prêt à activer Geospatial Creator:
- 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.
- Accédez à Project Settings > XR Plug-in Management > ARCore Extensions (Paramètres du projet > Gestion des plug-ins XR > Extensions ARCore).
- Si vous n'avez pas défini vos clés d'API ARCore pour Android et/ou iOS lors d'une étape précédente, assurez-vous de le faire maintenant.
- Activez les options "Geospatial" et "Geospatial Creator". Une fois que vous avez cliqué pour activer l'option Geospatial Creator, un assistant non modal s'affiche pour confirmer que votre projet est compatible avec Geospatial Creator.
- 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 vous n'avez pas sélectionné "Android" ou "iOS", passez à l'une des plates-formes sélectionnées.
Ajouter une origine Geospatial Creator avec des tuiles de carte
Votre scène doit contenir exactement un objet "Geospatial Creator Origin". Cet objet est utilisé comme point de référence pour convertir des 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). Le nouvel objet nécessite une géoréférence, qui associe une latitude, une longitude et une altitude spécifiques à la position du point de départ dans les coordonnées du jeu. Dans le volet Inspector (Inspecteur) de Geospatial Creator Origin, ajoutez une géoréférence en cliquant sur le bouton Add Cesium Georeference Component (Ajouter un composant de géoréférencement Cesium).
En plus d'être le point de référence de vos objets de RA, la géoréférence Cesium ajoute un objet Tileset 3D Cesium à la scène. Cet objet affiche les tuiles Google Maps dans la vue de la scène de l'éditeur, ce qui vous permet de visualiser exactement à quel endroit du monde votre contenu de RA apparaîtra. L'inspecteur de Geospatial Creator Origin dispose d'un champ permettant d'ajouter la clé API des tuiles de carte que vous avez configurée précédemment. Une fois cette touche définie, les tuiles de carte doivent se charger dans la vue "Scene" (Scène).
Modifiez maintenant les champs de latitude, de longitude et de hauteur pour qu'ils se trouvent à proximité de l'endroit où vous souhaitez que le contenu de RA apparaisse dans votre application.
La vue de la scène dans l'éditeur devrait maintenant afficher les tuiles de carte à la latitude et à la longitude spécifiées de votre point de départ. Au moment de l'exécution, nous supposons que votre application utilisera l'appareil photo en réalité augmentée. Geospatial Creator a donc déjà configuré l'objet Tileset de carte 3D Cesium avec la balise "EditorOnly". De ce fait, les cartes ne seront ni téléchargées ni affichées au moment de l'exécution dans votre jeu. Ce paramètre peut être modifié à partir de l'inspecteur de l'objet Cesium3DTileset. Pour en savoir plus sur la géolocalisation de Cesium et les GameObjects 3D Tileset, consultez la documentation de Cesium pour Unity.
Ajouter et placer un élément Geospatial Creator Anchor
Vous êtes maintenant prêt à placer du contenu RA dans votre scène. Cliquez sur GameObject > XR > Geospatial Creator Anchor (Ancre Geospatial Creator) pour ajouter une ancre à votre hiérarchie de scènes. À partir de l'inspecteur de l'ancre, vous pouvez spécifier une latitude, une longitude et une hauteur exactes. La transformation de l'objet est immédiatement mise à jour vers la position correcte dans votre scène, et vous pouvez voir exactement où l'objet apparaîtra.
Lorsque vous ajustez la latitude et la longitude de l'ancre, choisissez un lieu à proximité afin de pouvoir vérifier qu'il se trouve au bon endroit au moment de l'exécution. Lorsque vous définissez l'altitude d'un élément Geospatial Creator Anchor, vous avez trois options:
- L'option Relief place l'ancre 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 Visual Positioning System. Si vous ne connaissez pas les API Geospatial d'ARCore, nous vous recommandons d'utiliser l'option "Relief", car l'ancre sera résolue directement au sol avec un haut degré de précision verticale. Le champ "Altitude Offset" vous permet de positionner l'ancre au-dessus ou en dessous du niveau du sol selon une distance déterminée, en mètres. Par exemple, si vous spécifiez un décalage de "1,0", l'ancre "flottant" un mètre au-dessus du relief.
- Rooftop place l'ancre par rapport au sommet d'une structure à la latitude et à la longitude données. Tout comme l'ancre du relief, le champ "Décalage de l'altitude" vous permet de la déplacer vers le haut ou vers le bas par rapport à la position du toit, en mètres.
- WGS84 place l'ancre à une altitude absolue spécifique, en mètres, en fonction du système de coordonnées WGS84. Placer l'objet de cette manière peut nécessiter quelques essais et erreurs, car une hauteur de "0" dans WSG84 n'indique pas nécessairement le niveau de la mer moyen et peut ne pas correspondre à l'altitude d'un GPS. De plus, bien que la latitude et la longitude des tuiles 3D rendues soient très précises, essayer de placer l'objet au niveau du sol en utilisant les tuiles 3D comme référence peut entraîner une erreur de hauteur allant jusqu'à plusieurs mètres.
Pour en savoir plus sur les différents types d'ancres géospatiales ARCore, consultez le guide du développeur géospatial.
Les ancres de relief et de toit disposent d'un champ WGS84 Altitude. Cette valeur est uniquement utilisée en mode Éditeur pour définir la hauteur de l'objet dans la vue de la scène. Le relief et la hauteur des toits ne sont déterminés qu'au moment de l'exécution. Le champ WGS84 Altitude vous permet donc de visualiser l'ancre à une hauteur spécifique pendant le développement de l'application. Le champ WGS84 Altitude est ignoré au moment de l'exécution pour les ancres de terrain et de toit.
Ajouter la géométrie à l'ancre
Si vous compilez et exécutez l'application maintenant, vous ne verrez pas l'ancre dans votre application compatible avec la RA, car aucune géométrie n'y est associée. Ajoutons une primitive 3D simple à l'ancre: dans la hiérarchie de la scène, effectuez un clic droit sur l'objet Geospatial Creator Anchor de RA. Dans le menu contextuel, sélectionnez 3D Object > Cube (Objet 3D > Cube). Vous devriez voir un cube gris dans la vue de la scène en tant qu'enfant de votre ancre. Si vous décidez de déplacer la position ou la rotation de l'objet dans l'éditeur, nous vous recommandons de déplacer l'objet d'ancrage racine au lieu de la primitive du cube enfant. Cela permet de réduire les erreurs de traduction de la latitude / longitude en coordonnées de jeu.
Bien entendu, vous pouvez également ajouter à l'ancre une géométrie plus complexe, ainsi que des composants et des enfants arbitraires.
Compiler et exécuter votre application
Il est temps de découvrir votre point d'ancrage dans le monde réel ! Essayez de créer et d'exécuter votre application, puis accédez à l'emplacement où vous vous attendez à voir le cube. Est-ce 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 géospatiales de créateur de RA avec différentes géométries. Essayez plusieurs ancrages de toit et de relief, ainsi que leurs décalages. Ajoutez des scripts pour animer ou activer des interactions avec les objets.
Comprendre Geospatial Creator Anchors et la classe ARGeospatialAnchor
Lorsque vous créez des expériences de RA complexes et interactives, il est utile de comprendre la relation entre Geospatial Creator Anchors 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. Elles ne peuvent être créées qu'une fois la session de RA stabilisée. Un élément Geospatial Creator Anchor peut être considéré comme un espace réservé existant 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, l'espace réservé appelle automatiquement ARAnchorManager pour créer et résoudre l'ARGeospatialAnchor.
Immédiatement après la résolution de l'ancre de l'environnement d'exécution, l'ancre Geospatial Creator dans votre hiérarchie de scènes s'associe en tant qu'enfant au nouveau GameObject.
Cela signifie que tous les composants ou enfants de Geospatial Creator Anchor deviendront des sous-composants ou des petits-enfants du nouveau GameObject ARGeospatialAnchor. Par exemple, le transform d'une primitive de géométrie associée à Geospatial Creator Anchor héritera de l'transform de ARGeospatialAnchor et sera donc placé à l'emplacement attendu dans la session de RA de l'environnement d'exécution.
Si vous devez identifier des GameObjects ARGeospatialAnchor spécifiques au moment de l'exécution, vous pouvez rechercher dans la scène des objets dont la propriété name correspond à l'ancre créée à l'aide de Geospatial Creator. Si la session de RA est initialisée, le parent de cet objet sera l'objet ARGeospatialAnchor correspondant.
Dépannage
Pourquoi mon ancre se déplace-t-elle ?
Vous remarquerez peut-être, en particulier lors du premier lancement de l'application, que l'ancre peut sembler "dériver", ou même sauter brusquement de plusieurs mètres. Cela se produit lorsque la session VPS est toujours 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 sur plusieurs images, l'ancre est redessinée à un emplacement plus précis, ce qui donne l'illusion de mouvement. Vous pouvez souhaiter afficher l'objet différemment (voire pas du tout) jusqu'à ce que la précision de la localisation 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 de frames en cours.
Pourquoi mon ancre apparaît-elle à la mauvaise altitude ?
Lorsque vous utilisez le type d'altitude "Manuel" pour les ancres Geospatial Creator, l'altitude de l'ancre est définie (en mètres) conformément à WGS84. Pour un point géographique donné, il peut y avoir un écart de plusieurs mètres entre le niveau visible du sol affiché sur les tuiles de la carte et le niveau réel du sol tel qu'indiqué par le système de positionnement visuel de Google (VPS). Si une ancre géospatiale ne semble pas être correctement positionnée au moment de l'exécution, nous vous recommandons de valider en personne la hauteur du VPS à l'aide de la superposition de débogage de l'application exemple. Vous pouvez ensuite modifier l'altitude dans l'éditeur Unity pour qu'elle corresponde à la hauteur connue du VPS à cet emplacement.
Les tuiles de carte ne s'affichent pas correctement dans la vue de la scène de l'éditeur
Si Cesium3DTileset semble charger des tuiles, mais qu'elles sont affichées en magenta uni dans la vue de la scène, ajoutez le package Shader Graph d'Unity à votre projet. Ce package est requis par Cesium, bien que 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: Unity Registry" 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 doivent se recharger et s'afficher correctement dans la vue de la scène.
L'appli affiche un écran noir au moment de l'exécution au lieu de la vue de la caméra
Par défaut, le pipeline de rendu universel (URP) d'Unity n'est pas configuré pour la caméra RA. Si un écran noir s'affiche au moment de l'exécution au lieu de la sortie de la caméra, vous devez ajouter AR Background Renderer Feature à chaque moteur de rendu URP de votre scène.
Pour ajouter cette fonctionnalité, recherchez "moteur de rendu" dans votre projet. Pour chaque objet de moteur de rendu URP, cliquez sur le bouton "Add Renderer Feature" (Ajouter une fonctionnalité de moteur de rendu) dans l'inspecteur et ajoutez le moteur de rendu d'arrière-plan de la RA.
Pourquoi les ancres positionnées loin de l'origine semblent-elles mal placées ?
La conversion des coordonnées WGS84 en coordonnées de jeu Unity est sujette à une erreur en raison de la précision arithmétique à virgule flottante, qui peut être réduite en veillant à ce que votre point de départ se trouve à proximité de vos ancres de RA. Les distances supérieures à 20 km peuvent entraîner des imprécisions. Si votre expérience de RA couvre de longues distances, nous vous recommandons d'utiliser plusieurs scènes, avec un ancrage unique dans chacune d'elles.