Share via

Configuration initiale de World Locking Tools

  • Article

Configuration la plus simple possible

Ce tutoriel décrit en détail la configuration minimale permettant d’être opérationnel avec tous les éléments de votre application verrouillés, sans qu’aucune action supplémentaire (par exemple, l’utilisation d’ancres spatiales) ne soit nécessaire. Il se trouve dans le référentiel Samples de ce référentiel.

Guide de démarrage rapide

Une approche moins détaillée et plus pragmatique de l’intégration de WLT dans un projet est disponible ici. Quand cela est nécessaire, ce guide fait référence à ces pages plus approfondies. Bien qu’il s’agisse d’une préférence personnelle en ce qui concerne l’approche la plus appropriée, une lecture rapide de la page Avant de démarrer peut être vous faire gagner du temps dans l’étude de cette documentation.

Environnements pris en charge

World Locking Tools pour Unity cible actuellement les applications UWP pour la famille d’appareils HoloLens. Le HoloLens original (x86) et le HoloLens 2 (ARM64) sont tous deux pris en charge.

Une prise en charge expérimentale pour d’autres plateformes est disponible par le biais des sous-systèmes de réalité augmentée d’Unity.

L’intégration continue de World Locking Tools (CI) est validée avec Unity 2018.4.6f1 avec Visual Studio 2017. Cependant, un développement important de WLT a également été réalisé en utilisant toute la gamme des versions d’Unity2018, ainsi qu’un certain nombre de versions d’Unity2019. Visual Studio 2017 et Visual Studio 2019 ont tous deux été utilisés pour le développement des outils.

Si vous rencontrez des problèmes de compatibilité avec d’autres versions d’Unity et/ou de Visual Studio, nous aimerions en être informés ! La meilleure façon de signaler tout problème est de passer par le portail consacré aux problèmes sur GitHub.

Contexte supposé

Nous partons du principe que les gens qui cherchent à intégrer la solution World Locking Tools dans leurs projets sont déjà familiarisés avec les principes fondamentaux de la création et du déploiement d’applications pour la famille d’appareils HoloLens. Si ce n’est pas le cas, vous trouverez des références intéressantes à la fin de cet article.

Couches de World Locking Tools

World Locking Tools est divisé en quatre couches. Avec les flèches pointant vers la couche dont on dépend, le graphique de dépendance simple ressemble à ceci :

Diagramme de couche

Les lignes en pointillés indiquent des dépendances facultatives.

Alors que la couche Exemples utilise MixedRealityToolkit (MRTK), aucune des autres couches n’a de dépendances externes, et la fonctionnalité complète est disponible de manière compatible mais indépendante de MRTK.

Des notes supplémentaires sur les dépendances des applications suivent ci-dessous.

Les couches peuvent être résumées comme suit :

Plug-in

Interface impérative permettant une communication directe avec la DLL du moteur. Des problèmes courants tels que la gestion des arguments sont traités ici, ainsi que la composition de plusieurs fonctions fréquemment utilisées en combinaison dans des directives composites. Cela reste une interface C# de bas niveau pour la DLL C++ sous-jacente. Son utilisation directe est disponible, mais elle n’est pas nécessaire ni recommandée.

Core

Le cœur est une encapsulation de toutes les étapes nécessaires pour tirer parti des avantages de l’espace verrouillé stable de World Locking Tools, empaquetés dans une interface déclarative. Une application fonctionnelle devrait être livrée en utilisant uniquement les fonctionnalités du noyau.

Outils

Les outils servent principalement au diagnostic par nature. Les visualisations des processus de World Locking Tools sont incluses dans des formes faciles à ajouter à n’importe quel projet qui utilise World Locking Tools.

D’autres outils pratiques sont inclus, mais ils sont censés être utiles pour commencer à coder des solutions personnalisées, plutôt que d’être des solutions finales comme le propose le noyau.

Exemples

La couche d’exemples tente de présenter des exemples de configuration de scénarios courants lors de l’utilisation de World Locking Tools, et les meilleures pratiques en matière d’intégration de World Locking Tools dans différents scénarios.

Toutes les dépendances MRTK nécessaires à l’expérience utilisateur et à la manipulation des objets sont limitées aux scripts et aux prefabs de la couche d’exemples. Cela laisse les couches inférieures libres de dépendances externes.

Les scripts et les actifs de la couche d’exemples ne sont pas censés être intégrés directement dans les produits livrés, bien que rien ne l’interdise. Leur construction privilégie plutôt la simplicité et la clarté au détriment de la réutilisation et de l’efficacité.

L'application

En général, l’application n’a besoin que d’une dépendance sur le noyau de World Locking Tools.

Pendant le développement, de nombreuses visualisations et autres aides à la compréhension des comportements inattendus sont disponibles dans la couche d’ols. Ces aides devraient idéalement être supprimées d’une application finie, ou au moins désactivées. Bien entendu, elles sont également libres pour d’autres utilisations, que ce soit sous leur forme actuelle ou modifiée. Pour plus d’informations, consultez la licence.

Pour une utilisation avancée et l’expérimentation des fonctionnalités complètes de World Locking Tools, la couche de plug-in offre un accès impératif de bas niveau à la DLL du moteur.

Si l’accès à la couche de plug-in devient nécessaire, cela peut indiquer une déficience dans la surface de l’API offerte dans la couche du noyau. L’équipe World Locking Tools cherche toujours à combler ces lacunes. Envisagez de faire profiter l’équipe de ces connaissances. Voir contribution.

Une note d’avertissement sur la longueur du chemin d’installation

Certaines versions de MRTK ont un problème avec les chemins d’installation longs. La longueur totale du chemin d’accès des sous-dossiers profonds d’installation de MRTK peut dépasser la limite de chemin d’accès de Windows (260 caractères). Si une erreur de génération de la forme suivante apparaît :

DirectoryNotFoundException: Could not find a part of the path "D:\MyOverTwentyEightCharacterLongLengthInstallPath\MixedReality-WorldLockingTools-Unity\Assets\MRTK\MixedRealityToolkit.Providers\WindowsMixedReality\DotNetAdapter\Plugins\net46\Microsoft.Windows.MixedReality.DotNetWinRT\Editor\Microsoft.Windows.MixedReality.DotNetWinRT.Editor.asmdef"

mais que le fichier est bien présent sur le disque, alors le problème est probablement la longueur du chemin. L’équipe MRTK est consciente de cela et s’efforce de l’améliorer (remarque : je pense qu’ils ont apporté des améliorations importantes ici et qu’il ne s’agit plus d’un problème). En attendant, la solution de contournement consiste à raccourcir le préfixe de chemin d’accès en combinant les éléments suivants :

  1. Installez le projet Unity dans une racine de chemin d’accès de longueur plus petite, par exemple « D:\Proj ».
  2. Si vous clonez le référentiel, clonez la racine World Locking Tools dans un nom plus petit que le « \MixedReality-WorldLockingTools-Unity » par défaut, par exemple :
git clone https://github.com/microsoft/MixedReality-WorldLockingTools-Unity.git d:\MyGit\wlt

Cette limite de chemin n’est généralement pas un problème avec World Locking Tools lui-même, car il n’utilise pas une structure de dossiers aussi longue.

Ajout de World Locking Tools à un projet Unity

Notes

La rubrique suivante décrit l’installation manuelle des dépendances de World Locking Tools. Un processus d’installation bien plus simple est disponible via Mixed Reality Feature Tool. L’installation via Feature Tool est décrite ici. Si Feature Tool installe WLT, vous pouvez ignorer ce qui suit et poursuivre l’ajout de WLT à votre scène

World Locking Tools s’appuie sur NuGet pour installer le moteur Frozen World sous-jacent.

Si vous ajoutez World Locking Tools à un projet existant, il est recommandé de commencer avec un projet qui a été vérifié pour la génération et le déploiement sur un appareil HoloLens. Cela permet de séparer les problèmes liés à l’exécution d’une application sur HoloLens en premier lieu, ce qui peut être compliqué, des problèmes avec World Locking Tools. Accédez ensuite à la section Installation du moteur FrozenWorld et Ressources World Locking Tools ci-dessous.

Installation du moteur FrozenWorld

La DLL du moteur de FrozenWorld peut être obtenue à partir de NuGet à l’aide de l’excellent utilitaire NuGet For Unity, ou manuellement.

Utilisation de NuGet For Unity

Assurez-vous que le flux nuget.org est dans les sources. Vérifiez cela dans Unity > Modifier > Préférences > NuGet For Unity. Si ce n’est pas le cas, effectuez l’une des deux opérations suivantes :

Utilisez l’interface Ajouter une source dans Unity > Modifier > Préférences > NuGet For Unity pour ajouter le même partage.

  • Remplacez « Nouvelle source » par le nom de votre choix (par exemple, « NuGet »).
  • Remplacez "source_path" par "http://www.nuget.org/api/v2/".

Après avoir confirmé le flux nuget.org, dans Unity > NuGet > Gérer les packages NuGet, trouvez et installez la dernière version de Microsoft.MixedReality.FrozenWorld.Engine. (Recherchez « FrozenWorld ».)

Pour mettre à jour vers une version ultérieure, ouvrez à nouveau Unity > NuGet > Gérer les packages NuGet, et trouvez le paquet FrozenWorld.Engine et sélectionnez Mettre à jour. Remarque : vous devrez peut-être accéder à l’onglet Mises à jour pour trouver la version que vous recherchez.

Installation manuelle de la DLL du moteur de Frozen World

Utilisez un éditeur de texte pour ajouter une ligne packageSources à Assets/NuGet.config, par exemple :

  <packageSources>
    <add key="NuGet" value="http://www.nuget.org/api/v2/" />
  </packageSources>

Si vous n’avez pas encore de fichier Assets/NuGet.config, vous pouvez le copier à partir du référentiel GitHub de World Locking Tools.

À l’aide d’un éditeur de texte, ajoutez le package de la DLL du moteur de Frozen World à Assets/packages.config, par exemple :

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="Microsoft.MixedReality.Unity.FrozenWorld.Engine" version="1.0.0" />
</packages>

À nouveau, si vous n’avez pas encore de fichier Assets/packages.config, vous pouvez l’obtenir à partir du référentiel GitHub de World Locking Tools, ou simplement copier ce qui précède dans un fichier texte appelé « Assets/packages.config ».

Pour installer NuGet.config et packages.config, procédez comme suit :

  1. Obtenez la dernière version de nuget.exe depuis les téléchargements de NuGet.
  2. Assurez-vous que nuget.exe se trouve dans votre chemin d’accès (ici, on suppose qu’il a été copié dans Assets).
  3. Ouvrez une fenêtre de commande PowerShell et accédez au dossier Assets.
  4. Exécutez la commande suivante :
.\nuget.exe restore

Pour effectuer une mise à niveau vers une version ultérieure :

  1. Mettez à jour le numéro de version de FrozenWorld.Engine dans le fichier packages.config ci-dessus avec la version souhaitée (par exemple, version="1.0.0" devient version="1.0.1").
  2. Supprimez tout ce qui se trouve dans le dossier Assets/Packages commençant par « Microsoft.MixedReality.Unity.FrozenWorld.Engine ».
  3. Réexécutez nuget.exe comme indiqué ci-dessus.

Ressources World Locking Tools

Importez les fichiers .unitypackage nécessaires de World Locking Tools dans le projet (méthode recommandée) ou copiez-les. Ils peuvent être déplacés dans un sous-dossier au sein d’Assets afin de ne pas gêner le développement de l’application.

Les derniers fichiers .unitypackage stables se trouvent dans les Publications de World Locking Tools pour Unity.

La couche WorldLocking.Core et Engine sera absolument nécessaire, aussi un package d’installation minimal serait WorldLockingCoreEngine.unitypackage.

Pour déterminer quelles autres couches peuvent être nécessaires, consultez la discussion sur les couches World Locking Tools et leurs dépendances ci-dessus. Chaque couche est contenue dans un seul package Unity.

Étant donné que certains exemples de World Locking Tools utilisent des fonctionnalités de MRTK, un instantané MRTK compatible est inclus dans les exemples unitypackage. Pour obtenir la dernière version de MRTK, rendez-vous ici.

Ajout de World Locking Tools à une scène Unity

Notes

Les étapes répertoriées ci-dessous sont toutes automatisées dans l’utilitaire de configuration de scène de WLT, qui se trouve dans le menu Mixed Reality Computer Toolkit > Utilities > World Locking Tools. Menu Configuration

Dans un projet Unity contenant le moteur FrozenWorld (à partir de nuget.org), importez les couches de ressources World Locking Tools souhaitées (mais au minimum WorldLocking.Core) et éventuellement MRTK. Créez ensuite une nouvelle scène (ou ouvrez une scène existante).

Notes

Ajoutez un nœud supplémentaire à la racine de la hiérarchie de la caméra. Ce nœud sera utilisé pour ajuster la caméra de suivi de la tête dans l’espace universel verrouillé. (Si vous utilisez MRTK, ce nouveau GameObject sera le parent de MixedRealityPlayspace.)

Expérience principale

Faites glisser un prefab WorldLockingManager d’Assets/WorldLocking.Core/Prefabs dans votre scène. Sa place dans la scène n’a pas d’importance, mais elle ne doit pas se trouver dans l’arbre de la caméra. Consultez un exemple de scène pour une configuration suggérée.

Des paramètres sont disponibles sur le prefab WorldLockingManager, mais il est recommandé de les laisser à leurs valeurs par défaut pour commencer.

Consultez Contexte de World Locking Tools pour obtenir des explications sur les options présentées.

[Facultatif] MRTK

World Locking Tools est complémentaire mais orthogonal avec MRTK. L’utilisation de MRTK avec World Locking Tools est entièrement facultative.

Cela dit, les exemples World Locking Tools sont générés à l’aide de MRTK, et MRTK est généralement extrêmement utile pour développer les types d’applications de réalité mixte qui tirent le meilleur parti de World Locking Tools.

Si vous utilisez MRTK, au lieu d’utiliser l’instantané inclus dans les exemples, il est recommandé d’ajouter les versions les plus récentes des packages suivants au minimum :

  • MixedReality.Toolkit
  • MixedReality.Toolkit.Providers
  • MixedReality.Toolkit.Services
  • MixedReality.Toolkit.SDK

[Facultatif] Visualisation des ancres Spongy à verrouillage universel

Cela nécessite l’ajout de WorldLocking.Tools aux ressources du projet.

Si vous souhaitez visualiser vos ancres, faites glisser le prefab AnchorGraphVisual d’Assets/WorldLocking.Tools/Prefabs vers votre scène. Les cases à cocher permettant de basculer entre les aspects de la visualisation dans l’inspecteur se trouvent sur WorldLockingManager.

En tant que diagnostics, les visualisations WorldLocking.Tools ne sont pas fortement optimisées et réduisent les performances bien avant que le temps de traitement de World Locking Tools ne devienne pertinent.

[Facultatif] Tableau de bord simple pour le contrôle des paramètres dans la réalité mixte

Un affichage tête haute simple est disponible, et peut être utilisé pour contrôler WorldLockingManager au moment de l’exécution à partir de la réalité mixte. Vous le trouverez dans le package Examples. Bien que ces fonctions puissent être utilisées telles quelles, elles sont conçues comme des modèles permettant d’intégrer des fonctionnalités similaires dans un système d’affichage et une interface utilisateur propres à une application.

Faites glisser le prefab WorldLocking.Examples/Prefabs/Dashboard et faites pointer son champ Anchor Visualizer vers le Visualizer de la section précédente.

Migration d’une scène existante vers World Locking Tools

Le plus grand changement quand vous passez à World Locking Tools est qu’il n’y a plus d’obligation d’utiliser des ancres spatiales sur des objets virtuels de verrouillage universel.

Les ancres spatiales ont traditionnellement été le seul outil disponible pour verrouiller des objets individuels. Toutefois, lorsque vous utilisez World Locking Tools, l’espace de coordonnées dans lequel se trouvent ces objets virtuels est déjà verrouillé. Aucun verrouillage supplémentaire n’est nécessaire.

Non seulement les ancres spatiales sont inutiles, mais elles ne fonctionnent pas correctement, car elles ne tiennent pas compte des transformations supplémentaires de la hiérarchie de la caméra (comme la transformation MRTK « PlaySpace »).

Par conséquent, toutes les ancres spatiales doivent être supprimées de la scène, et tous les scripts qui ajoutent des ancres spatiales doivent cesser de le faire. Les ancres spatiales n’ont pas besoin d’être remplacées par quoi que ce soit ; World Locking Tools ancre ses cibles dans le monde réel.

S’il est souhaitable de comparer le verrouillage universel avec et sans World Locking Tools, au lieu de supprimer les WorldAnchors, vous pouvez les remplacer par le ToggleWorldAnchor fourni dans WorldLocking.Tools.

ToggleWorldAnchor fonctionne exactement de la même manière qu’un WorldAnchor, à la seule mais importante différence que lorsque le gestionnaire de World Locking Tools est actif, il se désactive de lui-même. Quand le gestionnaire de World Locking Tools est désactivé, il se comporte comme un WorldAnchor normal.

Si, pour une raison quelconque, les WorldAnchors sont toujours nécessaires dans la scène (par exemple, pour le partage réseau), ils peuvent être utilisés avec un adaptateur, fourni en tant que WorldAnchorAdapter.

WorldAnchorAdapter transforme la position brute d’un GameObject positionné par un WorldAnchor dans l’espace universel Unity verrouillé, puis applique la transformation à un objet cible. Pour l’utiliser, plutôt que d’ajouter un WorldAnchor directement à un objet, WorldAnchor doit être appliqué à un objet proxy (généralement un GameObject vide), puis lors d’Update(), WorldAnchorAdapter lit la pose du WorldAnchor, la transforme correctement et l’applique à la cible.

Installation terminée

Après avoir suivi les étapes ci-dessus, le projet déployé sur l’appareil s’exécutera avec World Locking Tools afin de conserver un espace universellement stable. Les objets fixes placés dans la scène restent cohérents les uns par rapport aux autres et avec le monde physique.

Exemples d’applications disponibles

Des exemples de scènes, y compris des scripts et des ressources, sont fournis pour illustrer une utilisation plus complexe des fonctionnalités de World Locking Tools.

Par exemple, WorldLockedPhysicsSample fournit un environnement simple dans lequel des objets simulés physiquement peuvent être créés et supprimés, en interagissant entre eux et avec l’environnement (mappage spatial).

Pour une vue plus ciblée de la fonctionnalité de repères spatiaux, SpacePin fournit un exemple beaucoup plus simple d’alignement d’un objet virtuel à grande échelle sur des fonctionnalités réelles.

RayPins développe les fonctionnalités introduites par l’exemple SpacePin, et permet d’épingler le monde virtuel au monde physique avec des tests de rayon sur le maillage spatial.

Références pour la prise en main

Si vous n’êtes pas familier avec les bases de la création, du développement et du déploiement d’applications de réalité augmentée sur la famille de dispositifs HoloLens, voici quelques références qui pourraient vous aider à démarrer.

Vue d’ensemble du développement Unity : Unity pour le développement MR/AR.

Base de MR 100 : découvrez comment commencer à développer pour HoloLens

Tutoriels HoloLens 2 : découvrez comment commencer à développer pour HoloLens 2.

Systèmes de coordonnées Implications de l’espace de coordonnées dans le développement en réalité augmentée.

  • Notez que World Locking Tools résout les problèmes abordés ici.

Vous avez une difficulté ?

Consultez le guide de dépannage.