Azure Spatial Anchors dans Unreal
Azure Spatial Anchors est un service de Réalité mixte Microsoft qui permet aux appareils de réalité augmentée de découvrir, de partager et de conserver des points d’ancrage dans le monde physique. La documentation ci-dessous fournit des instructions pour l’intégration du service Azure Spatial Anchors à un projet Unreal. Si vous souhaitez obtenir plus d’informations, consultez la documentation sur le service Azure Spatial Anchors.
Remarque
Unreal Engine 4.26 a maintenant des plug-ins pour la prise en charge d’ARKit et d’ARCore quand vous ciblez iOS ou Android.
Important
Les ancres locales sont stockées sur l’appareil, alors que les ancres spatiales Azure sont stockées dans le cloud. Si vous envisagez de stocker vos ancres localement sur un appareil, nous mettons à votre disposition un document sur les ancres spatiales locales qui peut vous guider tout au long du processus. Notez que vous pouvez avoir des ancres locales et Azure dans le même projet sans conflit.
Prérequis
Pour suivre ce guide, vous devez avoir :
- Installé le plug-in Microsoft OpenXR, disponible sur la marketplace Unreal ou GitHub.
- Installé Unreal version 4.25 ou version ultérieure.
- Un projet HoloLens 2 configuré dans Unreal.
- Lu la vue d’ensemble d’Azure Spatial Anchors.
- Une connaissance de base de C++ et Unreal.
Obtention d’informations sur le compte Azure Spatial Anchors
Avant d’utiliser Azure Spatial Anchors dans votre projet, vous devez :
- Créer une ressource d’ancres spatiales et copier les champs de compte listés ci-dessous. Ces valeurs sont utilisées pour authentifier les utilisateurs auprès du compte de votre application :
- ID de compte
- Clé de compte
Pour plus d’informations, consultez la documentation sur l’authentification Azure Spatial Anchors.
Remarque
Azure Spatial Anchors dans Unreal 4.25 ne prend pas en charge les jetons d’authentification Azure AD, mais la prise en charge de cette fonctionnalité sera disponible dans une version ultérieure.
Activer les fonctionnalités et les autorisations
HoloLens
Ouvrez Paramètres du projet HoloLens et activez la fonctionnalité Client Internet :
Android
Pour qu’une application Android affiche une boîte de dialogue d’autorisation et autorise les fonctionnalités d’emplacement, la fonction Request Android Permissions doit être appelée avant de tenter de démarrer la session Azure Spatial Anchor :
Créez une variable locale pour les autorisations d’entrée et définissez-la avec :
- android.permission.ACCESS_WIFI_STATE
- android.permission.CHANGE_WIFI_STATE
- android.permission.INTERNET
- android.permission.BLUETOOTH
- android.permission.BLUETOOTH_ADMIN
- android.permission.ACCESS_COARSE_LOCATION
- android.permission.ACCESS_FINE_LOCATION
- android.permission.CAMERA
Enfin, ouvrez Paramètres du projet Android et définissez les mêmes autorisations dans le champ Autorisations supplémentaires sous Package APK avancé :
iOS
Pour créer une application pour iOS, vous devez utiliser Unreal sur un Mac. Pour créer un package avec un compte de développeur Apple, ouvrez Paramètres du projet iOS, puis faites défiler jusqu’à la section Build. Cochez la case Signature automatique et renseignez l’ID d’équipe iOS avec votre ID d’équipe.
Vous pouvez trouver votre ID d’équipe en vous connectant à developer.apple.com, en accédant à l’onglet Appartenance et en recherchant ID d’équipe.
Pour afficher une boîte de dialogue d’autorisation et autoriser l’appareil iOS à accéder aux informations d’emplacement, les fonctions Init Location Services et Start Location Services doivent être appelées avant la tentative de démarrage de la session Azure Spatial Anchor :
Ajout des plug-ins Azure Spatial Anchors
Conseil
Si vous utilisez Azure Spatial Anchors pour Unreal, notez qu’il existe un plug-in Azure Spatial Anchors et un plug-in spécifique à la plateforme (WMR, ARKit, ARCore, OpenXR). Vous ne devez avoir qu’un seul plug-in spécifique à la plateforme activé à la fois.
HoloLens
Activez les plug-ins Azure Spatial Anchors dans l’éditeur Unreal en effectuant les étapes suivantes :
- Cliquez sur Edit Plugins et recherchez Azure Spatial Anchors et Azure Spatial Anchors For WMR.
- Cochez la case Enabled dans les deux plug-ins pour autoriser l’accès aux bibliothèques de blueprints Azure Spatial Anchors dans votre application.
Une fois cette opération terminée, redémarrez l’éditeur Unreal pour que les modifications apportées aux plug-ins prennent effet. Le projet est maintenant prêt à utiliser Azure Spatial Anchors.
Android
Activez les plug-ins Azure Spatial Anchors dans l’éditeur Unreal en effectuant les étapes suivantes :
- Cliquez sur Edit Plugins et recherchez Azure Spatial Anchors et Azure Spatial Anchors For ARCore.
- Cochez la case Enabled dans les deux plug-ins pour autoriser l’accès aux bibliothèques de blueprints Azure Spatial Anchors dans votre application.
Une fois cette opération terminée, redémarrez l’éditeur Unreal pour que les modifications apportées aux plug-ins prennent effet. Le projet est maintenant prêt à utiliser Azure Spatial Anchors.
iOS
Activez les plug-ins Azure Spatial Anchors dans l’éditeur Unreal en effectuant les étapes suivantes :
- Cliquez sur Edit Plugins et recherchez Azure Spatial Anchors et Azure Spatial Anchors For ARKit.
- Cochez la case Enabled dans les deux plug-ins pour autoriser l’accès aux bibliothèques de blueprints Azure Spatial Anchors dans votre application.
- Rechercher également Services d’emplacement mobile et Services d’emplacement mobile - Implémentation iOS
- Cochez la case Activé dans les deux plug-ins pour permettre à l’appareil iOS d’accéder à l’emplacement actuel.
Une fois cette opération terminée, redémarrez l’éditeur Unreal pour que les modifications apportées aux plug-ins prennent effet. Le projet est maintenant prêt à utiliser Azure Spatial Anchors.
Démarrage d’une session Spatial Anchors
Une session Azure Spatial Anchors permet aux applications clientes de communiquer avec le service Azure Spatial Anchors. Vous devez créer et démarrer une session Azure Spatial Anchors pour créer, conserver et partager des ancres spatiales Azure :
- Ouvrez le blueprint du Pawn que vous utilisez dans l’application.
- Ajoutez deux variables de chaîne pour l’ID de compte et la clé de compte, puis affectez les valeurs correspondantes à partir de votre compte Azure Spatial Anchors pour authentifier la session.
Démarrez une session Azure Spatial Anchors en effectuant les étapes suivantes :
- Vérifiez qu’une session RA est en cours d’exécution dans l’application HoloLens, car la session Azure Spatial Anchors ne peut pas démarrer tant qu’une session RA n’est pas en cours d’exécution. Si vous n’en avez pas configuré, créez une ressource de session RA.
- Ajoutez l’événement personnalisé Démarrer une session Azure Spatial Anchors et configurez-le comme indiqué dans la capture d’écran ci-dessous.
- La création d’une session ne provoque pas son démarrage par défaut, ce qui vous permet de configurer la session pour l’authentification auprès du service Azure Spatial Anchors.
- Configurez la session Azure Spatial Anchors pour fournir l’ID de compte, la Clé de compte, le Domaine du compte et les Paramètres de localisation des cours. Toutes les cases à cocher doivent être activées dans les paramètres de localisation des cours, de sorte que le service Azure Spatial Anchor puisse utiliser les données des capteurs pour localiser les ancres.
- Démarrez la session Azure Spatial Anchors afin de permettre à l’application de créer et de localiser les ancres spatiales Azure.
Nous vous recommandons de nettoyer les ressources Azure Spatial Anchors dans votre blueprint de graphe d’événements lorsque vous n’utilisez plus le service :
- Arrêtez la session Azure Spatial Anchors. La session ne sera plus en cours d’exécution, mais ses ressources associées existeront toujours dans le plug-in Azure Spatial Anchors.
- Détruisez la session Azure Spatial Anchors pour nettoyer toutes les ressources de session Azure Spatial Anchors, toujours connues du plug-in Azure Spatial Anchors.
Votre blueprint de graphe d’événements doit ressembler à la capture d’écran ci-dessous :
Création d’une ancre
Une ancre spatiale Azure représente un environnement physique dans l’espace de l’application de réalité augmentée, qui verrouille le contenu de réalité augmentée à des emplacements physiques. Les ancres spatiales Azure peuvent également être partagées par différents utilisateurs. Ce partage permet de placer du contenu de réalité augmenté sur différents appareils au même emplacement dans le monde physique.
Pour créer une ancre spatiale Azure
- Vérifiez qu’une session Azure Spatial Anchors est en cours d’exécution. L’application ne peut pas créer ou conserver une ancre spatiale Azure quand aucune session Azure Spatial Anchors n’est en cours d’exécution.
- Créez ou obtenez un composant de scène Unreal dont l’emplacement doit être conservé.
- Dans l’image ci-dessous, le composant Scene Component Needing Anchor est utilisé comme variable. Un composant de scène Unreal est nécessaire pour établir une transformation universelle d’application pour une épingle RA et une ancre spatiale Azure.
Pour construire et enregistrer une ancre spatiale Azure pour un composant de scène Unreal
- Appelez le composant d’épingle pour le composant de scène Unreal et spécifiez la transformation universelle du composant de scène comme transformation universelle utilisée pour l’épingle RA.
- Unreal effectue le suivi des points RA dans l’espace de l’application à l’aide d’épingles RA, qui sont utilisées pour créer une ancre spatiale Azure. Dans Unreal, une épingle RA est analogue à un SpatialAnchor sur HoloLens.
- Appelez Create Cloud Anchor à l’aide de l’épingle RA que vous venez de créer.
- Create Cloud Anchor crée une ancre spatiale Azure localement mais pas dans le service Azure Spatial Anchors. Les paramètres de l’ancre spatiale Azure, tels que la date d’expiration, peuvent être définis avant de créer l’ancre spatiale Azure avec le service.
- Définissez l’expiration de l’ancre spatiale Azure. Le paramètre Durée de vie de cette fonction permet au développeur de spécifier, en secondes, la durée pendant laquelle l’ancre doit être tenue à jour par le service.
- Par exemple, un délai d’expiration d’une semaine prendrait une valeur de 60 secondes x 60 minutes x 24 heures x 7 jours = 604 800 secondes.
Après avoir défini les paramètres de l’ancre, déclarez-la comme prête à être enregistrée. Dans l’exemple ci-dessous, la nouvelle ancre spatiale Azure est ajoutée à un ensemble d’ancres spatiales Azure nécessitant un enregistrement. Cet ensemble est déclaré en tant que variable pour le blueprint de Pawn.
Enregistrement d’une ancre
Après avoir configuré l’ancre spatiale Azure avec vos paramètres, appelez Save Cloud Anchor. Save Cloud Anchor déclare l’ancre auprès du service Azure Spatial Anchors. Lorsque l’appel à Save Cloud Anchor s’effectue correctement, l’ancre spatiale Azure est disponible pour les autres utilisateurs du service Azure Spatial Anchors.
Notes
Save Cloud Anchor est une fonction asynchrone qui peut être appelée uniquement sur un événement de thread de jeu, par exemple EventTick. Save Cloud Anchor peut ne pas apparaître en tant que fonction de blueprint disponible dans les fonctions de blueprint personnalisées. Toutefois, elle devrait être disponible dans l’éditeur de blueprint de graphe d’événements de Pawn.
Dans l’exemple ci-dessous, l’ancre spatiale Azure est stockée dans un ensemble pendant un rappel d’événement d’entrée. Elle est ensuite enregistrée sur l’EventTick. L’enregistrement d’une ancre spatiale Azure peut nécessiter plusieurs tentatives, en fonction de la quantité de données spatiales créées par votre session Azure Spatial Anchors. Il est donc préférable de vérifier si l’appel d’enregistrement a réussi.
Si l’ancre n’est pas enregistrée, rajoutez-la à l’ensemble d’ancres à enregistrer. Les prochains EventTicks vont continuer d’essayer d’enregistrer l’ancre jusqu’à ce qu’elle soit correctement stockée.
Une fois l’ancre enregistrée, la transformation d’épingles de réalité augmentée sert de transformation de référence pour le placement du contenu dans votre application. D’autres utilisateurs peuvent détecter cette ancre et aligner du contenu RA pour différents appareils dans le monde physique.
Suppression d’une ancre
Vous pouvez supprimer des ancres du service Azure Spatial Anchors en appelant Delete Cloud Anchor.
Notes
Delete Cloud Anchor est une fonction latente qui peut être appelée uniquement sur un événement de thread de jeu, tel qu’EventTick. Delete Cloud Anchor peut ne pas apparaître en tant que fonction de blueprint disponible dans les fonctions de blueprint personnalisées. Elle devrait toutefois être disponible dans l’éditeur de blueprint de graphe d’événements de Pawn.
Dans l’exemple ci-dessous, l’ancre est marquée pour suppression sur un événement d’entrée personnalisé. La suppression est ensuite tentée sur l’EventTick. En cas d’échec de la suppression de l’ancre spatiale Azure, ajoutez-la à l’ensemble d’ancres marquées pour suppression. La suppression sera retentée lors des EventTicks ultérieurs.
Votre blueprint de graphe d’événements doit maintenant ressembler à la capture d’écran ci-dessous :
Recherche d’ancres préexistantes
Les ancres existantes peuvent être créées par des pairs à partir du service Azure Spatial Anchors :
- Obtenez un identificateur Azure Spatial Anchors pour l’ancre que vous souhaitez détecter.
- Un identificateur d’ancre peut être obtenu pour une ancre créée par le même appareil lors d’une session Azure Spatial Anchors précédente. Il peut également être créé et partagé par des appareils homologues qui interagissent avec le service Azure Spatial Anchors.
- Ajoutez un composant AzureSpatialAnchorsEvent à votre blueprint de Pawn.
- Ce composant vous permet de vous abonner à différents événements Azure Spatial Anchors, tels que des événements appelés quand des ancres spatiales Azure sont localisées.
- Abonnez-vous à l’ASAAnchor Located Delegate pour le composant AzureSpatialAnchorsEvent.
- Le délégué permet à l’application de savoir quand de nouvelles ancres associées au compte Azure Spatial Anchors ont été localisées.
- Avec le rappel d’événement, les ancres spatiales Azure créées par les homologues à l’aide de la session Azure Spatial Anchors n’auront pas d’épingles RA créées par défaut. Pour créer une épingle RA pour l’ancre spatiale Azure détectée, les développeurs peuvent appeler Create ARPin Around Azure Cloud Spatial Anchor.
Pour localiser les ancres spatiales Azure créées par des pairs à l’aide du service Azure Spatial Anchors, l’application doit créer un observateur Azure Spatial Anchors :
- Vérifiez qu’une session Azure Spatial Anchors est en cours d’exécution.
- Créez un AzureSpatialAnchorsLocateCriteria.
- Vous pouvez spécifier différents paramètres d’emplacement tels que la distance par rapport à l’utilisateur ou la distance par rapport à une autre ancre.
- Déclarez l’identificateur Azure Spatial Anchors recherché dans AzureSpatialAnchorsLocateCritieria.
- Appelez Create Watcher.
L’application commence maintenant à rechercher les ancres spatiales Azure connues du service Azure Spatial Anchors, ce qui signifie que les utilisateurs peuvent localiser les ancres spatiales Azure créées par leurs homologues.
Après avoir localisé l’ancre spatiale Azure, appelez Stop Watcher pour arrêter l’observateur Azure Spatial Anchors et nettoyer ses ressources.
Votre blueprint de graphe d’événements final doit maintenant ressembler à la capture d’écran ci-dessous :
Point de contrôle de développement suivant
Si vous suivez le parcours de développement Unreal que nous avons mis en place, vous êtes en train d’explorer les modules de base du MRTK. À partir de là, vous pouvez passer au module suivant :
Ou accéder aux API et fonctionnalités de la plateforme Mixed Reality :
Vous pouvez revenir aux points de contrôle de développement Unreal à tout moment.