Azure Spatial Anchors dans UnrealAzure Spatial Anchors in 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.Azure Spatial Anchors is a Microsoft Mixed Reality service, allowing augmented reality devices to discover, share, and persist anchor points in the physical world. La documentation ci-dessous fournit des instructions pour l’intégration du service Azure Spatial Anchors à un projet Unreal.Documentation below provides instructions for integrating the Azure Spatial Anchors service into an Unreal project. Si vous souhaitez obtenir plus d’informations, consultez la documentation sur le service Azure Spatial Anchors.If you're looking for more information, check out the Azure Spatial Anchors service.

Notes

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.Unreal Engine 4.26 now has plugins for ARKit and ARCore support if you're targeting iOS or Android.

Important

Les ancres locales sont stockées sur l’appareil, alors que les ancres spatiales Azure sont stockées dans le cloud.Local anchors are stored on device, while Azure Spatial Anchors are stored in the 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.If you're looking to store your anchors locally on a device, we have a Local Spatial Anchors document that can walk you through the process. Notez que vous pouvez avoir des ancres locales et Azure dans le même projet sans conflit.Note that you can have local and Azure anchors in the same project without conflict.

PrérequisPrerequisites

Pour suivre ce guide, vous devez avoir :To complete this guide, make sure you have:

Obtention d’informations sur le compte Azure Spatial AnchorsGetting Azure Spatial Anchors account info

Avant d’utiliser Azure Spatial Anchors dans votre projet, vous devez :Before using Azure Spatial Anchors in your project, you need to:

  • Créer une ressource d’ancres spatiales et copier les champs de compte listés ci-dessous.Create a spatial anchors resource and copy the account fields listed below. Ces valeurs sont utilisées pour authentifier les utilisateurs auprès du compte de votre application :These values are used to authenticate users with your application's account:
    • ID de compteAccount ID
    • Clé de compteAccount Key

Pour plus d’informations, consultez la documentation sur l’authentification Azure Spatial Anchors.Check out the Azure Spatial Anchors authentication docs for more information.

Notes

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.Azure Spatial Anchors in Unreal 4.25 does not support Azure AD authentication tokens, but support for this functionality will be coming in a later release.

Ajout des plug-ins Azure Spatial AnchorsAdding Azure Spatial Anchors plugins

Activez les plug-ins Azure Spatial Anchors dans l’éditeur Unreal en effectuant les étapes suivantes :Enable the Azure Spatial Anchors plugins in the Unreal editor by:

  1. Cliquez sur Edit > Plugins et recherchez AzureSpatialAnchors et AzureSpatialAnchorsForWMR.Clicking Edit > Plugins and searching for AzureSpatialAnchors and AzureSpatialAnchorsForWMR.
  2. 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.Select the Enabled checkbox in both plugins to allow access to the Azure Spatial Anchors blueprint libraries in your application.

Capture d’écran des plugins Spatial Anchors dans l’éditeur Unreal

Une fois cette opération terminée, redémarrez l’éditeur Unreal pour que les modifications apportées aux plug-ins prennent effet.Once that's done, restart the Unreal Editor for the plugin changes to take effect. Le projet est maintenant prêt à utiliser Azure Spatial Anchors.The project is now ready to use Azure Spatial Anchors.

Démarrage d’une session Spatial AnchorsStarting a Spatial Anchors session

Une session Azure Spatial Anchors permet aux applications clientes de communiquer avec le service Azure Spatial Anchors.An Azure Spatial Anchors session allows client applications to communicate with the Azure Spatial Anchors service. Vous devez créer et démarrer une session Azure Spatial Anchors pour créer, conserver et partager des ancres spatiales Azure :You'll need to create and start an Azure Spatial Anchors session to create, persist, and share Azure Spatial Anchors:

  1. Ouvrez le blueprint du Pawn que vous utilisez dans l’application.Open the blueprint for the Pawn you're using in the application.
  2. 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.Add two string variables for the Account ID and Account Key, then assign the corresponding values from your Azure Spatial Anchors account to authenticate the session.

Capture d’écran du volet d’informations avec mise en évidence de l’ID de compte, de la clé et du type de variable Azure Spatial Anchors

Démarrez une session Azure Spatial Anchors en effectuant les étapes suivantes :Start an Azure Spatial Anchors session by:

  1. 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.Checking that an AR Session is running in the HoloLens application, as the Azure Spatial Anchors session can't start until an AR Session is running. Si vous n’en avez pas configuré, créez une ressource de session RA.If you don't have one setup, create an AR Session asset.
  2. Ajoutez l’événement personnalisé Démarrer une session Azure Spatial Anchors et configurez-le comme indiqué dans la capture d’écran ci-dessous.Adding the Start Azure Spatial Anchors Session custom event and configure it as shown in the screenshot below.
    • 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.Creating a session doesn't start the session by default, which allows you to configure the session for authentication with the Azure Spatial Anchors service.

Blueprint de l’événement personnalisé lié au démarrage de la session Azure Spatial Anchors

  1. Configurez la session Azure Spatial Anchors pour fournir l’ID de compte et la clé de compte.Configure the Azure Spatial Anchors session to provide the Account ID and Account Key.

Blueprint de la fonction de configuration de session avec ajout de l’ID de compte et de la clé de compte

  1. Démarrez la session Azure Spatial Anchors afin de permettre à l’application de créer et de localiser les ancres spatiales Azure.Start the Azure Spatial Anchors session, allowing the application to create and locate Azure Spatial Anchors.

Blueprint de la fonction de démarrage de session Azure Spatial Anchors

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 :It's good practice to clean up Azure Spatial Anchors resources in your Event Graph blueprint when you're no longer using the service:

  1. Arrêtez la session Azure Spatial Anchors.Stop the Azure Spatial Anchors session. La session ne sera plus en cours d’exécution, mais ses ressources associées existeront toujours dans le plug-in Azure Spatial Anchors.The session will no longer be running, but its associated resources will still exist in the Azure Spatial Anchors plugin.

Blueprint de l’événement personnalisé lié à l’arrêt de la session Azure Spatial Anchors et de la fonction d’arrêt de session

  1. 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.Destroy the Azure Spatial Anchors session to clean up any Azure Spatial Anchors session resources still known to the Azure Spatial Anchors plugin.

Blueprint de la fonction de destruction de session

Votre blueprint de graphe d’événements doit ressembler à la capture d’écran ci-dessous :Your Event Graph blueprint should look like the screenshot below:

Blueprint du graphe d’événements complet pour la configuration de session Azure Spatial Anchors

Création d’une ancreCreating an anchor

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.An Azure Spatial Anchor represents a physical world pose in the augmented reality application space, which locks augmented reality content to physical locations. Les ancres spatiales Azure peuvent également être partagées par différents utilisateurs.Azure Spatial Anchors can also be shared among different users. Ce partage permet de placer du contenu de réalité augmenté sur différents appareils au même emplacement dans le monde physique.This sharing allows augmented reality content drawn on different devices to be positioned in the same location in the physical world.

Pour créer une ancre spatiale AzureTo create a new Azure Spatial Anchor:

  1. Vérifiez qu’une session Azure Spatial Anchors est en cours d’exécution.Check that an Azure Spatial Anchors session is running. 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.The application can't create or persist an Azure Spatial Anchor when no Azure Spatial Anchors session is running.

Blueprint de l’événement personnalisé lié à la création d’une ancre spatiale Azure

  1. Créez ou obtenez un composant de scène Unreal dont l’emplacement doit être conservé.Create or obtain an Unreal Scene Component that should have its location persisted.
    • Dans l’image ci-dessous, le composant Scene Component Needing Anchor est utilisé comme variable.In the below image, the Scene Component Needing Anchor component is used as a 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.An Unreal Scene Component is needed to establish an application world transform for an AR Pin and Azure Spatial Anchor.

Blueprint de l’événement personnalisé lié à la création d’une ancre spatiale Azure avec un composant de scène

Pour construire et enregistrer une ancre spatiale Azure pour un composant de scène UnrealTo construct and save an Azure Spatial Anchor for an Unreal Scene Component:

  1. 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.Call the Pin Component for the Unreal Scene Component and specify the Scene Component's World Transform as the World Transform used for the AR Pin.
    • 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.Unreal tracks AR points in the application space using AR Pins, which are used to create an Azure Spatial Anchor. Dans Unreal, une épingle RA est analogue à un SpatialAnchor sur HoloLens.In Unreal, an AR Pin is analogous to a SpatialAnchor on HoloLens.

Blueprint du composant de scène connecté à la fonction du composant d’épingle

  1. Appelez Create Cloud Anchor à l’aide de l’épingle RA que vous venez de créer.Call Create Cloud Anchor using the newly created AR Pin.
    • Create Cloud Anchor crée une ancre spatiale Azure localement mais pas dans le service Azure Spatial Anchors.Create Cloud Anchor creates an Azure Spatial Anchor locally but not in the Azure Spatial Anchor service. 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.Parameters for the Azure Spatial Anchor, such as an expiration date, can be set before creating the Azure Spatial Anchor with the service.

Blueprint de la fonction de composant d’épingle connectée à la fonction Create Cloud Anchor, qui retourne l’épingle de réalité augmentée

  1. Définissez l’expiration de l’ancre spatiale Azure.Set the Azure Spatial Anchor expiration. 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.This function's Lifetime parameter allows the developer to specify in seconds how long the anchor should be maintained by the 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.For example, a week long expiration would take a value of 60 seconds x 60 minutes x 24 hours x seven days = 604,800 seconds.

Blueprint de l’ancre cloud connectée à la fonction de définition du délai d’expiration avec une valeur de durée de vie fixée à 604 800 secondes

Après avoir défini les paramètres de l’ancre, déclarez-la comme prête à être enregistrée.After setting anchor parameters, declare the anchor as ready to save. Dans l’exemple ci-dessous, la nouvelle ancre spatiale Azure est ajoutée à un ensemble d’ancres spatiales Azure nécessitant un enregistrement.In the example below, the newly created Azure Spatial Anchor is added to a set of Azure Spatial Anchors needing saving. Cet ensemble est déclaré en tant que variable pour le blueprint de Pawn.This set is declared as a variable for the Pawn blueprint.

Blueprint de l’ancre prête à être enregistrée dans la variable définie

Enregistrement d’une ancreSaving an Anchor

Après avoir configuré l’ancre spatiale Azure avec vos paramètres, appelez Save Cloud Anchor.After configuring the Azure Spatial Anchor with your parameters, call Save Cloud Anchor. Save Cloud Anchor déclare l’ancre auprès du service Azure Spatial Anchors.Save Cloud Anchor declares the anchor to the Azure Spatial Anchors service. Lorsque l’appel à Save Cloud Anchor s’effectue correctement, l’ancre spatiale Azure est disponible pour les autres utilisateurs du service Azure Spatial Anchors.When the call to Save Cloud Anchor succeeds, the Azure Spatial Anchor is available to other users of the Azure Spatial Anchor service.

Blueprint de l’appel de la fonction Save Cloud Anchor

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 is an asynchronous function and can only be called on a game thread event such as EventTick. Save Cloud Anchor peut ne pas apparaître en tant que fonction de blueprint disponible dans les fonctions de blueprint personnalisées.Save Cloud Anchor may not appear as an available blueprint function in custom blueprint Functions. Toutefois, elle devrait être disponible dans l’éditeur de blueprint de graphe d’événements de Pawn.However, it should be available in the Pawn Event Graph blueprint editor.

Dans l’exemple ci-dessous, l’ancre spatiale Azure est stockée dans un ensemble pendant un rappel d’événement d’entrée.In the example below, the Azure Spatial Anchor is stored in a set during an input event callback. Elle est ensuite enregistrée sur l’EventTick.The anchor is then saved on the 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.Saving an Azure Spatial Anchor may take multiple attempts depending on the amount of spatial data that your Azure Spatial Anchors session has created. Il est donc préférable de vérifier si l’appel d’enregistrement a réussi.That's why it's a good idea to check whether the save call succeeded.

Si l’ancre n’est pas enregistrée, rajoutez-la à l’ensemble d’ancres à enregistrer.If the anchor doesn't save, readd it to the set of anchors still needing to be saved. Les prochains EventTicks vont continuer d’essayer d’enregistrer l’ancre jusqu’à ce qu’elle soit correctement stockée.Future EventTicks will keep trying to save the anchor until it's successfully stored.

Blueprint des ancres non enregistrées, qui sont réenregistrées dans la variable définie

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.Once the anchor saves, the AR Pins' transform acts as a reference transform for placing content in your app. D’autres utilisateurs peuvent détecter cette ancre et aligner du contenu RA pour différents appareils dans le monde physique.Other users can detect this anchor and align AR content for different devices in the physical world.

Suppression d’une ancreDeleting an Anchor

Vous pouvez supprimer des ancres du service Azure Spatial Anchors en appelant Delete Cloud Anchor.You can delete anchors from the Azure Spatial Anchor service by calling Delete Cloud Anchor.

Blueprint de l’appel de la fonction 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 is a latent function and can only be called on a game thread event, such as EventTick. Delete Cloud Anchor peut ne pas apparaître en tant que fonction de blueprint disponible dans les fonctions de blueprint personnalisées.Delete Cloud Anchor may not appear as an available blueprint function in custom blueprint Functions. Elle devrait toutefois être disponible dans l’éditeur de blueprint de graphe d’événements de Pawn.It should however be available in the Pawn Event Graph blueprint editor.

Dans l’exemple ci-dessous, l’ancre est marquée pour suppression sur un événement d’entrée personnalisé.In the example below, the anchor is flagged for deletion on a custom input event. La suppression est ensuite tentée sur l’EventTick.The deletion is then attempted on the 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.If the anchor deletion fails, add the Azure Spatial Anchor to the set of anchors flagged for deletion and tries again on later EventTicks.

Votre blueprint de graphe d’événements doit maintenant ressembler à la capture d’écran ci-dessous :Your Event Graph blueprint should now look like the screenshot below:

Blueprint du graphe d’événements complet pour la gestion des ancres cloud

Recherche d’ancres préexistantesLocating pre-existing anchors

Les ancres existantes peuvent être créées par des pairs à partir du service Azure Spatial Anchors :Existing anchors can be created by peers with the Azure Spatial Anchors service:

  1. Obtenez un identificateur Azure Spatial Anchors pour l’ancre que vous souhaitez détecter.Obtain an Azure Spatial Anchor identifier for the anchor that you would like to detect.
    • 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.An anchor identifier can be obtained for an anchor created by the same device in a previous Azure Spatial Anchors session. Il peut également être créé et partagé par des appareils homologues qui interagissent avec le service Azure Spatial Anchors.It can also be created and shared by peer devices interacting with the Azure Spatial Anchors service.

Blueprint de l’événement personnalisé lié au stockage de l’identificateur d’ancre spatiale Azure, et de la fonction d’obtention de l’identificateur de cloud Azure

  1. Ajoutez un composant AzureSpatialAnchorsEvent à votre blueprint de Pawn.Add an AzureSpatialAnchorsEvent component to your Pawn blueprint.
    • 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.This component allows you to subscribe to various Azure Spatial Anchors events, such as events called when Azure Spatial Anchors are located.

Capture d’écran montrant BP_Pawn ouvert dans l’éditeur de blueprint avec les composants et les volets d’informations ouverts également

  1. Abonnez-vous à l’ASAAnchor Located Delegate pour le composant AzureSpatialAnchorsEvent.Subscribe to the ASAAnchor Located Delegate for the AzureSpatialAnchorsEvent component.
    • Le délégué permet à l’application de savoir quand de nouvelles ancres associées au compte Azure Spatial Anchors ont été localisées.The delegate lets the application know when new anchors associated with the Azure Spatial Anchors account have been located.
    • 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.With the event callback, Azure Spatial Anchors created by peers using the Azure Spatial Anchors session won't have AR Pins created by default. 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.To create an AR Pin for the detected Azure Spatial Anchor, developers can call Create ARPin Around Azure Cloud Spatial Anchor.

Blueprint de l’événement de début de lecture connecté à ASAAnchor Located Delegate

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 :To locate Azure Spatial Anchors created by peers using the Azure Spatial Anchor service, the application will have to create an Azure Spatial Anchors Watcher:

  1. Vérifiez qu’une session Azure Spatial Anchors est en cours d’exécution.Check that an Azure Spatial Anchors session is running.
  2. Créez un AzureSpatialAnchorsLocateCriteria.Create an 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.You can specify various location parameters like distance from the user or distance from another anchor.
  3. Déclarez l’identificateur Azure Spatial Anchors recherché dans AzureSpatialAnchorsLocateCritieria.Declare the Azure Spatial Anchor identifier you're looking for in the AzureSpatialAnchorsLocateCritieria.
  4. Appelez Create Watcher.Call Create Watcher.

Blueprint de l’événement personnalisé lié au démarrage de l’observateur Azure Spatial Anchors

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.The application now begins looking for Azure Spatial Anchors known to the Azure Spatial Anchors service, meaning that users can locate Azure Spatial Anchors created by their peers.

Après avoir localisé l’ancre spatiale Azure, appelez Stop Watcher pour arrêter l’observateur Azure Spatial Anchors et nettoyer ses ressources.After locating the Azure Spatial Anchor, call Stop Watcher to stop the Azure Spatial Anchors Watcher and clean up watcher resources.

Blueprint de l’appel de la fonction Stop Watcher

Votre blueprint de graphe d’événements final doit maintenant ressembler à la capture d’écran ci-dessous :Your final Event Graph blueprint should now look like the screenshot below:

Blueprint du graphe d’événements complet pour la gestion des événements liés aux délégués d’ancres

Point de contrôle de développement suivantNext Development Checkpoint

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.If you're following the Unreal development journey we've laid out, you're in the midst of exploring the MRTK core building blocks. À partir de là, vous pouvez passer au module suivant :From here, you can continue to the next building block:

Ou accéder aux API et fonctionnalités de la plateforme Mixed Reality :Or jump to Mixed Reality platform capabilities and APIs:

Vous pouvez revenir aux points de contrôle de développement Unreal à tout moment.You can always go back to the Unreal development checkpoints at any time.

Étapes suivantesNext steps