Freigeben über

Ersteinrichtung von World Locking Tools

  • Artikel

Minimales Setup

In diesem Tutorial werden Sie durch das minimale Setup geführt, damit alle Komponenten Ihrer Anwendung weltgebunden und ohne weitere Maßnahmen (z. B. Raumanker) in Betrieb genommen werden können. Das Tutorial ist im Repository mit Beispielen enthalten, das diesem Repository gleichgeordnet ist.

Kurzanleitung

Der Leitfaden für die ersten Schritte bietet einen konzeptionell weniger detaillierten und pragmatischeren Ansatz zur Integration von WLT in ein Projekt. Wo es angebracht ist, wird auf diese ausführlicheren Seiten verwiesen. Auch wenn der am besten geeignete Ansatz eine Frage der persönlichen Vorlieben ist, kann eine kurze Lektüre der Seite Bevor Sie beginnen wertvolle Informationen dazu liefern, worauf Sie sich in dieser Dokumentation konzentrieren sollten.

Unterstützte Umgebungen

World Locking Tools for Unity ist derzeit auf UWP-Anwendungen für die HoloLens-Gerätefamilie ausgerichtet. Es wird sowohl die ursprünglichen HoloLens-Version (x86) als auch HoloLens 2 (ARM64) unterstützt.

Experimentelle Unterstützung für weitere Plattformen steht über die AR-Subsysteme von Unity zur Verfügung.

Der World Locking Tools-CI-Build (Continuous Integration) ist mit Unity2018.4.6f1 und Visual Studio 2017 validiert. Es wurde jedoch auch eine umfangreiche WLT-Entwicklung unter Verwendung der verschiedenen Unity2018-Versionen und einer Reihe von Unity2019-Versionen durchgeführt. Für die Entwicklung der Tools wurden sowohl Visual Studio 2017 als auch Visual Studio 2019 verwendet.

Wenn Sie auf Kompatibilitätsprobleme mit anderen Versionen von Unity und/oder Visual Studio stoßen, freuen wir uns, wenn Sie uns dies mitteilen! Der beste Weg zum Melden von Problemen ist das Portal für Issues auf GitHub.

Vorausgesetzter Hintergrund

Es wird davon ausgegangen, dass Benutzer, die die World Locking Tools-Lösung in ihre Projekte integrieren möchten, bereits mit den Grundlagen der Erstellung und Bereitstellung von Anwendungen für die HoloLens-Gerätefamilie vertraut sind. Falls nicht, finden Sie am Ende dieses Artikels einige hervorragende Referenzen.

Die World Locking Tools-Ebenen

World Locking Tools ist in vier Ebenen unterteilt. Mit Pfeilen, die auf die abhängige Ebene zeigen, sieht ein einfaches Abhängigkeitsdiagramm wie folgt aus:

Ebenendiagramm

Die gestrichelten Linien zeigen optionale Abhängigkeiten an.

Während die Beispielebene das MixedRealityToolkit (MRTK) verwendet, weist keine der anderen Schichten irgendwelche externen Abhängigkeiten auf, und die gesamte Funktionalität ist kompatibel mit, aber unabhängig von MRTK verfügbar.

Weitere Hinweise zu den Anwendungsabhängigkeiten finden Sie weiter unten.

Die Ebenen können wie folgt zusammengefasst werden:

Plugin

Eine zwingend erforderliche Schnittstelle, die eine direkte Kommunikation mit der Engine-DLL ermöglicht. Hier werden gängige Probleme gelöst, z. B. das Marshalling von Argumenten und das Zusammenstellen von häufig in Kombination verwendeten Funktionen in Verbundanweisungen. Es handelt sich aber weiterhin um eine Low-Level-C#-Schnittstelle zur zugrunde liegenden C++-DLL. Ihre direkte Verwendung ist möglich, aber weder notwendig noch ratsam.

Core

Der Core kapselt alle Schritte, die notwendig sind, um die Vorteile des stabilen weltgebundenen Raums von World Locking Tools zu nutzen, paketiert in einer deklarativen Schnittstelle. Von einer funktionierenden Anwendung wird erwartet, dass sie nur die Funktionalität der Core-Ebene verwendet.

Extras

Die Tools sind hauptsächlich für die Diagnose gedacht. Visualisierungen der World Locking Tools-Prozesse sind in Formularen enthalten, die sich leicht in jedes Projekt einfügen lassen, das World Locking Tools verwendet.

Außerdem sind weitere praktische Hilfsprogramme enthalten. Diese sind jedoch eher für den Einstieg in die Programmierung benutzerdefinierter Lösungen gedacht als für endgültige Lösungen, wie sie der Core bietet.

Beispiele

Diese Ebene bietet Beispiele für die Einrichtung gängiger Szenarien bei der Verwendung von World Locking Tools sowie Best Practices für die Integration von World Locking Tools in verschiedene Szenarien.

Alle notwendigen MRTK-Abhängigkeiten für UX und Objektmanipulation sind auf die Skripts und Prefabs der Beispielebene beschränkt. Dadurch bestehen für die niedrigeren Ebenen keinerlei externe Abhängigkeiten.

Es wird nicht davon ausgegangen, dass Skripts und Ressourcen der Beispielebene direkt in Auslieferungsprodukte integriert werden, auch wenn dies nicht untersagt ist. Vielmehr stehen bei ihrem Aufbau Einfachheit und Klarheit gegenüber Wiederverwendbarkeit und Effizienz im Vordergrund.

Die Anwendung

Im Allgemeinen ist für die Anwendung nur eine Abhängigkeit von World Locking Tools Core erforderlich.

Während der Entwicklung stehen viele Visualisierungen und andere Hilfsprogramme in der Tools-Ebene zur Verfügung, um ein unerwartetes Verhalten zu verstehen. Diese Hilfsprogramme sollten idealerweise aus der fertigen Anwendung entfernt oder zumindest deaktiviert werden. Selbstverständlich können sie auch für andere Zwecke genutzt werden, entweder unverändert oder in abgewandelter Form. Weitere Informationen finden Sie in der Lizenz.

Für die erweiterte Nutzung und das Experimentieren mit dem vollen Funktionsumfang von World Locking Tools bietet die Plugin-Ebene notwendigen Low-Level-Zugriff auf die Engine-DLL.

Wenn ein Zugriff auf die Plugin-Ebene notwendig wird, kann dies auf ein Defizit in der von der Core-Ebene bereitgestellten API-Oberfläche hinweisen. Das World Locking Tools-Team arbeitet fortlaufend daran, solche Lücken zu schließen. Erwägen Sie, dem Team solche Erkenntnisse mitzuteilen. Weitere Informationen finden Sie unter Mitwirkung.

Warnhinweis zur Länge des Installationspfads

Bei einigen MRTK-Versionen gibt es ein Problem mit langen Installationspfaden. Die Gesamtpfadlänge tief geschachtelter Unterordner in der MRTK-Installation kann das Limit für Windows-Pfade (260 Zeichen) überschreiten. Möglicherweise wird ein Buildfehler wie der folgende angezeigt:

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"

Wenn die Datei tatsächlich auf dem Laufwerk vorhanden ist, liegt wahrscheinlich ein Problem mit der Pfadlänge vor. Das MRTK-Team kennt dieses Problem und arbeitet an seiner Lösung (Hinweis: Es wurden viele Verbesserungen vorgenommen, möglicherweise ist das Problem bereits behoben). In der Zwischenzeit können Sie zur Problemumgehung das Pfadpräfix durch eine Kombination der folgenden Maßnahmen verkürzen:

  1. Installieren Sie das Unity-Projekt in einem Stamm mit kürzerem Pfad, z. B. „D:\Proj“.
  2. Verwenden Sie beim Klonen des Repositorys für den World Locking Tools-Stamm einen kürzeren Namen als den Standardwert „\MixedReality-WorldLockingTools-Unity“, zum Beispiel:
git clone https://github.com/microsoft/MixedReality-WorldLockingTools-Unity.git d:\MyGit\wlt

Diese Pfadbegrenzung stellt für World Locking Tools selbst im Allgemeinen kein Problem dar, da keine so tiefe Ordnerstruktur verwendet wird.

Hinzufügen von World Locking Tools zu einem Unity-Projekt

Hinweis

Im Folgenden wird die manuelle Installation von World Locking Tools und der Abhängigkeiten beschrieben. Ein wesentlich schlankerer Installationsprozess steht mit dem Mixed Reality-Featuretool zur Verfügung. Die Installation über das Featuretool wird hier beschrieben. Bei Installation von WLT über das Featuretool können Sie den folgenden Abschnitt überspringen und mit dem Hinzufügen von WLT zu Ihrer Szene fortfahren.

World Locking Tools verwendet NuGet, um die zugrunde liegende Frozen World Engine zu installieren.

Wenn Sie World Locking Tools zu einem bestehenden Projekt hinzufügen, sollten Sie mit einem Projekt beginnen, das für die Erstellung und Bereitstellung auf einem HoloLens-Gerät verifiziert wurde. Auf diese Weise können Probleme bei der erstmaligen Ausführung einer App in HoloLens (was kompliziert sein kann) von Problemen mit World Locking Tools getrennt werden. Fahren Sie dann mit den Abschnitten Installation der Frozen World Engine und World Locking Tools-Ressourcen fort.

Installation der Frozen World Engine

Die Frozen World Engine-DLL kann über NuGet bezogen werden, entweder mit dem exzellenten Hilfsprogramm NuGet for Unity oder manuell.

Verwenden von NuGet for Unity

Stellen Sie sicher, dass der nuget.org-Feed in den Quellen vorhanden ist. Überprüfen Sie dies in „Unity“ > „Bearbeiten“ > „Einstellungen“ > „NuGet for Unity“. Führen Sie andernfalls einen der folgenden Schritte aus:

Verwenden Sie die Option Neue Quelle hinzufügen in „Unity“ > „Bearbeiten“ > „Einstellungen“ > „NuGet for Unity“, um die gleiche Freigabe hinzuzufügen.

  • Ersetzen Sie „Neue Quelle“ durch einen Namen Ihrer Wahl (z. B. „NuGet“).
  • Ersetzen Sie „source_path“ durch " durch "http://www.nuget.org/api/v2/".

Nachdem Sie den nuget.org-Feed bestätigt haben, suchen Sie in „Unity“ > „NuGet“ > „NuGet-Pakete verwalten“ nach der die neueste Version von „Microsoft.MixedReality.FrozenWorld.Engine“ und installieren sie. (Suchen Sie nach „FrozenWorld“.)

Zum Update auf eine neuere Version öffnen Sie „Unity“ > „NuGet“ > „NuGet-Pakete verwalten“ erneut, suchen nach dem Paket „FrozenWorld.Engine“ und klicken auf „Aktualisieren“. Hinweis: Möglicherweise müssen Sie auf der Registerkarte „Updates“ nach der gesuchten Version suchen.

Manuelle Installation der Frozen World Engine-DLL

Verwenden Sie einen Text-Editor, um „Assets/NuGet.config“ eine packageSources-Zeile hinzuzufügen, z. B.:

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

Wenn Sie noch nicht über eine Datei „Assets/NuGet.config“ verfügen, können Sie sie aus dem GitHub-Repository „World Locking Tools“ kopieren.

Fügen Sie mithilfe eines Text-Editors das Frozen World Engine-DLL-Paket zu „Assets/packages.config“ hinzu, z. B.:

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

Auch hier gilt: Wenn Sie noch nicht über eine Datei „Assets/packages.config“ verfügen, können Sie sie aus dem GitHub-Repository „World Locking Tools“ abrufen oder einfach den obigen Ausschnitt in eine Textdatei namens „Assets/packages.config“ kopieren.

Nachdem Sie „NuGet.config“ „und packages.config“ eingerichtet haben, können Sie die Installation durchführen:

  1. Rufen Sie die aktuelle Version von „nuget.exe“ aus den NuGet-Downloads ab.
  2. Stellen Sie sicher, dass sich „nuget.exe“ in Ihrem Pfad befindet (hier wird davon ausgegangen, dass die Datei in „Assets“ kopiert wurde).
  3. Öffnen Sie ein PowerShell-Befehlsfenster, und wechseln Sie zum Ordner „Assets“.
  4. Führen Sie den folgenden Befehl aus:
.\nuget.exe restore

So führen Sie ein Upgrade auf eine höhere Version durch

  1. Aktualisieren Sie die FrozenWorld.Engine-Versionsnummer in der obigen packages.config-Datei auf die gewünschte Version (z. B. wird version="1.0.0" zu version="1.0.1").
  2. Löschen Sie alle Elemente im Ordner „Assets/Packages“, die mit „Microsoft.MixedReality.Unity.FrozenWorld.Engine“ beginnen.
  3. Führen Sie „nuget.exe“ gemäß Beschreibung oben erneut aus.

World Locking Tools-Ressourcen

Importieren Sie entweder die erforderlichen World Locking Tools-Dateien .unitypackage in das Projekt (bevorzugte Methode), oder kopieren Sie sie. Sie können in einen Unterordner von „Assets“ verschoben werden, damit sie bei der Anwendungsentwicklung nicht stören.

Die neuesten stabilen .unitypackage-Dateien finden Sie unter World Locking Tools for Unity-Releases.

Die WorldLocking.Core- und Engine-Ebenen werden in jedem Fall benötigt, daher wäre ein minimales Installationspaket „WorldLockingCoreEngine.unitypackage“.

Informationen dazu, welche zusätzlichen Ebenen erforderlich sein könnten, finden Sie in der obigen Beschreibung der World Locking Tools-Ebenen und ihrer Abhängigkeiten. Jede Ebene ist in einem einzelnen Unity-Paket enthalten.

Da einige der World Locking Tools-Beispiele Funktionen von MRTK verwenden, ist eine kompatible MRTK-Momentaufnahme im Beispiele-unitypackage enthalten. Das neueste MRTK-Release finden Sie hier.

Hinzufügen von World Locking Tools zu einer Unity-Szene

Hinweis

Die unten aufgeführten Schritte sind alle im WLT-Hilfsprogramm „Configure scene“ (Szene konfigurieren) automatisiert, das im Menü „Mixed Reality Toolkit“ > „Hilfsprogramme“ > „World Locking Tools“ enthalten ist. Konfigurationsmenü

Innerhalb eines Unity-Projekts, das die FrozenWorld-Engine (von nuget.org) enthält, importieren Sie alle gewünschten World Locking Tools-Ressourcenebenen (mindestens jedoch „WorldLocking.Core“) und optional MRTK. Erstellen Sie dann eine neue Szene (oder öffnen Sie eine vorhandene Szene).

Hinweis

Fügen Sie dem Stamm der Kamerahierarchie einen zusätzlichen Knoten hinzu. Dieser Knoten wird verwendet, um die Head-Tracking-Kamera im weltgebundenen Raum anzupassen. (Bei Verwendung von MRTK wäre dieses neue GameObject dem MixedRealityPlayspace übergeordnet.)

Die Core-Funktionalität

Ziehen Sie ein WorldLockingManager-Prefab aus „Assets/WorldLocking.Core/Prefabs“ in Ihre Szene. Seine Position in der Szene spielt keine Rolle, es sollte sich jedoch nicht in der Kamerastruktur befinden. Eine vorgeschlagene Konfiguration finden Sie unter Beispielszene.

Im WorldLockingManager-Prefab sind einige Einstellungen verfügbar, aber für den Einstieg wird empfohlen, die Standardwerte beizubehalten.

Erläuterungen zu den dargestellten Optionen finden Sie unter World Locking Tools-Kontext.

[Optional] MRTK

World Locking Tools ist eine Ergänzung zu MRTK, aber unabhängig davon. Die Verwendung von MRTK zusammen mit World Locking Tools ist rein fakultativ.

Die World Locking Tools-Beispiele wurden jedoch mit MRTK erstellt, und MRTK ist im Allgemeinen äußerst nützlich für die Entwicklung der Arten von MR-Anwendungen, die am meisten von World Locking Tools profitieren.

Wenn Sie anstelle der in den Beispielen enthaltenen Momentaufnahme MRTK verwenden, sollten Sie die neuesten Versionen von mindestens diesen Paketen hinzufügen:

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

[Optional] Visualisieren von Spongy-Ankern und weltgebundenen Ankern

Dies erfordert das Hinzufügen von „WorldLocking.Tools“ zum Ordner „Assets“ für das Projekt.

Wenn Sie Ihre Anker visualisieren möchten, ziehen Sie das AnchorGraphVisual-Prefab aus „Assets/WorldLocking.Tools/Prefabs“ in Ihre Szene. Kontrollkästchen zum Umschalten von Aspekten der Visualisierung im Inspector befinden sich im WorldLockingManager.

Zur Diagnose sind die WorldLocking.Tools-Visualisierungen nicht umfassend optimiert und vermindern die Leistung, lange bevor die zentrale World Locking Tools-Verarbeitungszeit relevant wird.

[Optional] Ein einfaches Dashboard für die Parametersteuerung in Mixed Reality

Es steht ein einfaches Head-up-Display (HUD) zur Verfügung, mit dem der WorldLockingManager zur Laufzeit innerhalb von MR gesteuert werden kann. Dieses wird im Beispielpaket bereitgestellt. Obwohl eine Verwendung in unveränderter Form möglich ist, sind sie als Muster für die Entwicklung ähnlicher Funktionen für das Anzeigesystem und die Benutzeroberfläche einer Anwendung gedacht.

Fügen Sie das Prefab „WorldLocking.Examples/Prefabs/Dashboard“ per Drag & Drop ein, und verweisen Sie im zugehörigen Feld „Anchor Visualizer“ (Ankervisualisierung) auf die Visualisierung im vorherigen Abschnitt.

Migrieren einer vorhandenen Szene zu World Locking Tools

Die größte Änderung bei der Umstellung auf World Locking Tools besteht darin, dass die Verwendung von Raumankern für virtuelle weltgebundene Objekte nicht mehr erforderlich ist.

Raumanker waren bisher das einzige Tool, das für weltgebundene Einzelobjekte zur Verfügung stand. Bei der Verwendung von World Locking Tools hingegen ist der Koordinatenraum, in dem sich diese virtuellen Objekte befinden, bereits weltgebunden. Es ist keine weitere Verankerung erforderlich.

Raumanker sind nicht nur unnötig, sondern funktionieren auch nicht korrekt, da sie zusätzliche Transformationen in der Kamerahierarchie nicht berücksichtigen (z. B. die MRTK-Transformation „Playspace“).

Daher sollten alle Raumanker aus der Szene entfernt werden, und alle Skripts, die Raumanker hinzufügen, sollten dies nicht mehr tun. Die Raumanker müssen nicht durch andere Elemente ersetzt werden. World Locking Tools verankert die zugehörigen Ziele in der realen Welt.

Für einen Vergleich der Verankerung mit und ohne World Locking Tools können die Weltanker (WorldAnchors) durch den in „WorldLocking.Tools“ enthaltenen ToggleWorldAnchor ersetzt werden, anstatt sie zu entfernen.

ToggleWorldAnchor funktioniert genauso wie ein WorldAnchor, mit dem wichtigen Unterschied, dass er sich selbst deaktiviert und in den Hintergrund wechselt, wenn der World Locking Tools Manager aktiv ist. Wenn der World Locking Tools Manager deaktiviert ist, verhält er sich wie ein normaler WorldAnchor.

Wenn aus einem bestimmten Grund weiterhin WorldAnchors in der Szene benötigt werden (z. B. für die Netzwerkfreigabe), können sie mit einem Adapter verwendet werden, der als WorldAnchorAdapter bereitgestellt wird.

Der WorldAnchorAdapter transformiert die Originalposition für ein GameObject, das durch einen WorldAnchor positioniert wurde, in den globalen weltgebundenen Raum von Unity und wendet die Transformation dann auf ein Zielobjekt an. Um ihn zu verwenden, sollte der WorldAnchor nicht direkt einem Objekt hinzugefügt, sondern auf ein Proxyobjekt angewendet werden (normalerweise ein ansonsten leeres GameObject). Bei einem Update() liest der WorldAnchorAdapter dann die Position für einen WorldAnchor, transformiert sie entsprechend und wendet sie auf das Ziel an.

Setup abgeschlossen

Wenn Sie die oben genannten Schritte befolgt haben, wird das auf dem Gerät bereitgestellte Projekt durch World Locking Tools angepasst ausgeführt, um einen möglichst stabilen weltgebundenen Raum zu erhalten. Alle festen Objekte in der Szene bleiben visuell konsistent, sowohl im Verhältnis zueinander als auch zur physischen Welt.

Verfügbare Beispielanwendungen

Zur Veranschaulichung komplexerer Anwendungsmöglichkeiten der World Locking Tools-Funktionen werden Beispielszenen bereitgestellt, die sowohl Skripts als auch Ressourcen enthalten.

Zum Beispiel stellt das WorldLockedPhysicsSample eine einfache Umgebung bereit, in der physisch simulierte Objekte erstellt und entfernt werden können, die miteinander und mit der Umgebung interagieren (räumliche Zuordnung).

Für eine genauere Betrachtung des Space Pinning-Features bietet SpacePin ein stark vereinfachtes Beispiel für die Ausrichtung eines großflächigen virtuellen Objekts an realen Merkmalen.

RayPins erweitern die durch das SpacePin-Beispiel eingeführten Möglichkeiten und ermöglichen durch Strahlenabtastung des Raumnetzes eine Verknüpfung der virtuellen Welt mit der physischen Welt.

Referenzen für erste Schritte

Wenn Sie mit den Grundlagen der Erstellung, Entwicklung und Bereitstellung von AR-Apps für die HoloLens-Gerätefamilie nicht vertraut sind, finden Sie hier einige Referenzen, die Ihnen den Einstieg erleichtern könnten.

Übersicht über die Unity-Entwicklung: Unity für die MR/AR-Entwicklung.

MR-Grundlagen 100: Erste Schritte bei der Entwicklung für HoloLens.

HoloLens 2-Tutorials: Erste Schritte bei der Entwicklung für HoloLens 2.

Koordinatensysteme: Auswirkungen auf den Koordinatenraum bei der AR-Entwicklung.

  • Hinweis: Mit World Locking Tools werden die hier beschriebenen Probleme gelöst.

Sie haben Probleme?

Weitere Informationen finden Sie im Leitfaden zur Problembehandlung.