Eerste installatie van World Locking Tools

  • Artikel

Slimst mogelijke installatie

De zelfstudie hier doorloopt de minimale installatie om aan de slag te gaan met alles in de wereld vergrendelde toepassing, zonder verdere actie (bijvoorbeeld ruimtelijke ankers) vereist. De opslagplaats bevindt zich in de opslagplaats Samples op hetzelfde niveau als deze opslagplaats.

Snelstartgids

Een minder conceptueel gedetailleerde en meer pragmatische benadering voor het integreren van WLT in een project vindt u hier. Indien van toepassing verwijst het terug naar deze uitgebreidere pagina's. Hoewel het echt een kwestie is van persoonlijke voorkeur welke benadering geschikter is, kan een snelle leesbewerking van de pagina Voordat u aan de slag gaat , tijd besparen op waar u energie kunt besteden in deze documentatie.

Ondersteunde omgevingen

World Locking Tools for Unity is momenteel gericht op UWP-toepassingen voor de HoloLens-familie van apparaten. Zowel de oorspronkelijke HoloLens (x86) als HoloLens 2 (ARM64) worden ondersteund.

Experimentele ondersteuning voor andere platforms is beschikbaar via de AR-subsystemen van Unity.

De CI-build (Continue integratie) van World Locking Tools wordt gevalideerd met Unity2018.4.6f1 met Visual Studio 2017. Uitgebreide WLT-ontwikkeling is echter ook uitgevoerd met behulp van het gamma van Unity2018-versies en een reeks Unity2019. Zowel Visual Studio 2017 als Visual Studio 2019 zijn gebruikt bij de ontwikkeling van de hulpprogramma's.

Als u compatibiliteitsproblemen ondervindt met andere versies van Unity en/of Visual Studio, horen we dit graag. De beste manier om eventuele problemen te melden, is via de problemenportal op GitHub.

Veronderstelde achtergrond

Er wordt vanuit gegaan dat mensen die de oplossing World Locking Tools in hun projecten willen integreren, al bekend zijn met de basisbeginselen van het bouwen en implementeren van toepassingen voor de HoloLens-familie van apparaten. Zo niet, dan vindt u een aantal geweldige verwijzingen aan het einde van dit artikel.

De lagen van World Locking Tools

World Locking Tools is onderverdeeld in vier lagen. Met de pijlen die naar de laag wijzen, afhankelijk van, ziet de eenvoudige afhankelijkheidsgrafiek er als volgt uit:

Laagdiagram

De stippellijnen geven optionele afhankelijkheden aan.

Hoewel de laag Examples gebruikmaakt van de MixedRealityToolkit (MRTK), hebben geen van de andere lagen externe afhankelijkheden en is de volledige functionaliteit compatibel met, maar onafhankelijk van MRTK.

Meer opmerkingen over de toepassingsafhankelijkheden volgen hieronder.

De lagen kunnen als volgt worden samengevat:

Invoegtoepassing

Een imperatieve interface die directe communicatie met de engine-DLL mogelijk maakt. Veelvoorkomende problemen zoals argument marshaling worden hier uitgevoerd, en sommige samenstelling van meerdere functies die vaak in combinatie worden gebruikt in samengestelde instructies. Het blijft een C#-interface op laag niveau met de onderliggende C++-DLL. Het directe gebruik is beschikbaar, maar niet nodig of aan te raden.

Kern

De Core is een inkapseling van alle stappen die nodig zijn om de voordelen te verkrijgen van de stabiele wereld vergrendelde ruimte van World Locking Tools, verpakt in een declaratieve interface. Van een werkende toepassing wordt verwacht dat deze alleen gebruikmaakt van functionaliteit van de Core.

Hulpprogramma's

De hulpprogramma's zijn grotendeels diagnostisch van aard. Visualisaties van World Locking Tools-processen zijn opgenomen in formulieren die eenvoudig kunnen worden toegevoegd aan elk project dat gebruikmaakt van World Locking Tools.

Andere handige hulpprogramma's zijn inbegrepen, maar zijn naar verwachting nuttig om aan de slag te gaan met het coderen van aangepaste oplossingen, in plaats van definitieve oplossingen te zijn, zoals de Core biedt.

Voorbeelden

De laag Voorbeelden probeert voorbeelden te presenteren van het instellen van veelvoorkomende scenario's bij het gebruik van World Locking Tools en aanbevolen procedures voor de integratie van World Locking Tools in verschillende scenario's.

Eventuele benodigde MRTK-afhankelijkheden voor UX en objectmanipulatie zijn beperkt tot de scripts en prefabs op de laag Voorbeelden. Hierdoor blijven de onderste lagen vrij van externe afhankelijkheden.

Scripts en assets in de laag Voorbeelden worden naar verwachting niet rechtstreeks geïntegreerd in verzendproducten, hoewel er geen verbod op is. In plaats daarvan geeft hun constructie de voorkeur aan eenvoud en duidelijkheid boven herbruikbaarheid en efficiëntie.

De toepassing

Over het algemeen hoeft de toepassing alleen afhankelijk te zijn van World Locking Tools Core.

Tijdens de ontwikkeling zijn veel visualisaties en andere helpers voor het begrijpen van onverwacht gedrag beschikbaar in de laag Hulpprogramma's. Deze helpers zouden in het ideale geval uit een voltooide toepassing worden verwijderd of op zijn minst worden uitgeschakeld. Natuurlijk zijn ze ook gratis voor ander gebruik, in hun huidige vorm of aangepast. Zie de licentie voor meer informatie.

Voor geavanceerd gebruik en het experimenteren met de volledige mogelijkheden van World Locking Tools biedt de invoegtoepassingslaag imperatieve toegang op laag niveau tot de engine-DLL.

Als toegang tot de invoegtoepassingslaag nodig is, kan dit wijzen op een tekort in het API-oppervlak dat wordt aangeboden in de Core-laag. Het World Locking Tools-team is altijd op zoek naar het opvullen van dergelijke hiaten. Overweeg dergelijke inzichten aan het team bij te dragen. Zie Bijdragen.

Een waarschuwingsnotitie over de lengte van het installatiepad

Sommige versies van MRTK hebben een probleem met lange installatiepaden. De volledige padlengte van diepe submappen in de MRTK-installatie kan de limiet voor het Windows-pad (260 tekens) overschrijden. Als er een buildfout van het volgende formulier wordt weergegeven:

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"

maar het bestand bevindt zich daadwerkelijk op het station, dan is het probleem waarschijnlijk de padlengte. Het MRTK-team is hiervan op de hoogte en werkt eraan om dit te verbeteren (opmerking: ik denk dat ze hier grote verbeteringen hebben aangebracht en het is niet langer een probleem). In de tussentijd is de tijdelijke oplossing het padvoorvoegsel te verkorten met een combinatie van het volgende:

  1. Installeer het Unity-project in een pad met een kortere lengte, bijvoorbeeld 'D:\Proj'
  2. Als u de opslagplaats kloont, kloont u de hoofdmap van de World Locking Tools in iets korter dan de standaardwaarde '\MixedReality-WorldLockingTools-Unity', bijvoorbeeld:
git clone https://github.com/microsoft/MixedReality-WorldLockingTools-Unity.git d:\MyGit\wlt

Deze padlimiet is over het algemeen geen probleem met de World Locking Tools zelf, omdat ze geen gebruik maken van een mappenstructuur die zo diep is.

World Locking Tools toevoegen aan een Unity-project

Notitie

Hieronder wordt de handmatige installatie van World Locking Tools en afhankelijkheden beschreven. Een veel gestroomlijnder installatieproces is beschikbaar via de Mixed Reality Feature Tool. Installatie via het functieprogramma wordt hier beschreven. Als het functieprogramma WLT installeert, kunt u het volgende overslaan en doorgaan met het toevoegen van WLT aan uw scène

World Locking Tools is afhankelijk van nuget om de onderliggende Frozen World Engine te installeren.

Als u World Locking Tools toevoegt aan een bestaand project, is het raadzaam om te beginnen met een project dat is geverifieerd voor het bouwen en implementeren op een HoloLens-apparaat. Dit helpt in de eerste plaats bij het scheiden van problemen met het uitvoeren van een app op HoloLens, wat ingewikkeld kan zijn, van problemen met de World Locking Tools. Ga vervolgens verder met de secties FrozenWorld Engine installation en World Locking Tools Assets hieronder.

Installatie van FrozenWorld Engine

De Frozen World Engine DLL kan worden verkregen van NuGet met behulp van het uitstekende NuGet For Unity-hulpprogramma , of handmatig.

NuGet gebruiken voor Unity

Zorg ervoor dat de nuget.org feed zich in bronnen bevindt. Controleer dit in Unity > Edit > Preferences > NuGet for Unity. Als dat niet het geval is, kunt u het volgende doen:

Gebruik de NUGet Nieuwe bron-GUI toevoegen in Unity-bewerkingsvoorkeuren >>> voor Unity om dezelfde share toe te voegen.

  • Vervang 'Nieuwe bron' door een naam van uw keuze (bijvoorbeeld 'NuGet').
  • Vervang 'source_path' door 'http://www.nuget.org/api/v2/".

Nadat u de nuget.org feed hebt bevestigd, zoekt en installeert u in Unity > NuGet > NuGet-pakketten beheren de nieuwste versie van Microsoft.MixedReality.FrozenWorld.Engine. (Zoek naar 'FrozenWorld'.)

Als u wilt bijwerken naar een nieuwere versie, opent u de Unity > NuGet > NuGet-pakketten opnieuw beheren, zoekt u het pakket FrozenWorld.Engine en selecteert u Bijwerken. Opmerking: mogelijk moet u naar het tabblad Updates om de versie te vinden die u zoekt.

Handmatige DLL-installatie van Frozen World Engine

Gebruik een teksteditor om een packageSources regel toe te voegen aan Assets/NuGet.config, bijvoorbeeld:

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

Als u nog geen bestand Assets/NuGet.config hebt, kunt u dit kopiëren vanuit de GitHub-opslagplaats World Locking Tools.

Voeg met behulp van een teksteditor het DLL-pakket Frozen World Engine toe aan Assets/packages.config, bijvoorbeeld:

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

Nogmaals, als u nog geen bestand Assets/packages.config hebt, kunt u het bestand ophalen uit de GitHub-opslagplaats World Locking Tools of gewoon het bovenstaande kopiëren naar een tekstbestand met de naam 'Assets/packages.config'.

Nadat u NuGet.config en packages.config hebt ingesteld, installeert u door:

  1. Haal de meest recente nuget.exe op via NuGet-downloads.
  2. Zorg ervoor dat nuget.exe zich in uw pad bevindt (hier ga ik ervan uit dat het is gekopieerd naar Assets).
  3. Open een PowerShell-opdrachtvenster en wijzig de map in de map Assets.
  4. Voer de volgende opdracht uit:
.\nuget.exe restore

Upgraden naar een nieuwere versie:

  1. Werk het versienummer van FrozenWorld.Engine in het bovenstaande packages.config-bestand bij naar de gewenste versie (bijvoorbeeld version="1.0.0" wordt version="1.0.1").
  2. Verwijder iets in de map Assets/Packages te beginnen met 'Microsoft.MixedReality.Unity.FrozenWorld.Engine'.
  3. Voer nuget.exe opnieuw uit zoals hierboven.

World Locking Tools Assets

Importeer de vereiste World Locking Tools-bestanden .unitypackage in het project (voorkeursmethode) of kopieer ze in. Ze kunnen worden verplaatst naar een submap in Assets om ze uit de weg te halen voor het ontwikkelen van toepassingen.

De meest recente stabiele .unitypackage bestanden zijn te vinden in World Locking Tools for Unity Releases.

De WorldLocking.Core- en Engine-laag zijn zeker vereist, dus een minimaal installatiepakket is WorldLockingCoreEngine.unitypackage.

Als u wilt bepalen welke andere lagen mogelijk vereist zijn, raadpleegt u de discussie over World Locking Tools-lagen en hun afhankelijkheden hierboven. Elke laag is opgenomen in één Unity-pakket.

Omdat sommige voorbeelden van World Locking Tools gebruikmaken van functies van MRTK, is een compatibele MRTK-momentopname opgenomen in de voorbeelden unitypackage. Kijk hier voor de nieuwste MRTK-release.

World Locking Tools toevoegen aan een Unity-scène

Notitie

De onderstaande stappen zijn allemaal geautomatiseerd in het WLT-hulpprogramma Scène configureren, dat te vinden is in het menu Mixed Reality Toolkit > Utilities > World Locking Tools. Menu Configureren

Importeer in een Unity-project met de FrozenWorld-engine (van nuget.org) alle gewenste Lagen van World Locking Tools Assets (maar ten minste WorldLocking.Core), en optioneel MRTK. Maak vervolgens een nieuwe scène (of open een bestaande scène).

Notitie

Voeg een extra knooppunt toe aan de hoofdmap van de camerahiërarchie. Dit knooppunt wordt gebruikt om de camera met het hoofd in vergrendelde ruimte aan te passen. (Als u MRTK gebruikt, is dit nieuwe GameObject het bovenliggende element van mixedRealityPlayspace.)

De kernervaring

Sleep een WorldLockingManager-prefab van Assets/WorldLocking.Core/Prefabs naar uw scène. De plaats in de scène maakt niet uit, maar het mag niet in de camerastructuur staan. Bekijk een voorbeeldscène voor een voorgestelde configuratie.

Er zijn instellingen beschikbaar op de WorldLockingManager-prefab, maar het wordt aanbevolen om aan de slag te gaan met de standaardwaarden.

Zie World Locking Tools Context voor uitleg over de opties die worden weergegeven.

[Optioneel] MRTK

World Locking Tools is een aanvulling op maar orthogonaal voor MRTK. Het gebruik van MRTK in combinatie met World Locking Tools is volledig optioneel.

De Voorbeelden van World Locking Tools zijn echter gebouwd met MRTK en MRTK is over het algemeen zeer waardevol bij het ontwikkelen van de typen MR-toepassingen die het meeste profiteren van World Locking Tools.

Als u MRTK gebruikt in plaats van de momentopname in de voorbeelden te gebruiken, is het raadzaam om de nieuwste versies van ten minste de volgende pakketten toe te voegen:

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

[Optioneel] Sponsachtig en wereld vergrendelde ankers visualiseren

Hiervoor moet WorldLocking.Tools worden toegevoegd aan de assets van het project.

Als u uw ankers wilt visualiseren, sleept u AnchorGraphVisual prefab van Assets/WorldLocking.Tools/Prefabs naar uw scène. Selectievakjes voor het in-/uitschakelen van aspecten van de visualisatie in de inspector bevinden zich op de WorldLockingManager.

Als diagnostische gegevens zijn de WorldLocking.Tools-visualisaties niet sterk geoptimaliseerd en verminderen ze de prestaties lang voordat de kernverwerkingstijd van World Locking Tools relevant wordt.

[Optioneel] Een eenvoudig dashboard voor parameterbeheer in Mixed Reality

Er is een eenvoudige HUD beschikbaar, die kan worden gebruikt om de WorldLockingManager tijdens runtime te beheren vanuit MR. Deze worden geleverd in het pakket Voorbeelden. Hoewel ze als zodanig kunnen worden gebruikt, zijn ze bedoeld als patronen bij het bouwen van vergelijkbare functies in een eigen weergavesysteem en UX van een toepassing.

Sleep in de prefab WorldLocking.Examples/Prefabs/Dashboard en wijs het bijbehorende veld Anchor Visualizer aan op de Visualizer in de vorige sectie.

Een bestaande scène migreren naar World Locking Tools

De grootste wijziging bij het overstappen op World Locking Tools is dat er geen vereiste meer is voor het gebruik van ruimtelijke ankers om virtuele objecten te vergrendelen.

Ruimtelijke ankers zijn van oudsher het enige hulpmiddel dat beschikbaar is om afzonderlijke objecten wereldwijd te vergrendelen. Maar wanneer u World Locking Tools gebruikt, is de coördinaatruimte waarin deze virtuele objecten zich bevinden al wereldwijd vergrendeld. Er is geen verdere vergrendeling nodig.

Ruimtelijke ankers zijn niet alleen overbodig, ze werken ook niet goed, omdat ze geen rekening houden met aanvullende transformaties in de camerahiërarchie (zoals de MRTK Playspace-transformatie).

Daarom moeten alle ruimtelijke ankers uit de scène worden verwijderd en moeten scripts die ruimtelijke ankers toevoegen, dit niet meer doen. De ruimtelijke ankers hoeven nergens door te worden vervangen; World Locking Tools verankert hun doelen aan de echte wereld.

Als het wenselijk is om world-locking met en zonder World Locking Tools te vergelijken, kunnen deze in plaats van WorldAnchors te verwijderen worden vervangen door de ToggleWorldAnchor die in WorldLocking.Tools wordt geleverd.

ToggleWorldAnchor werkt precies hetzelfde als een WorldAnchor, met het belangrijke verschil dat wanneer de World Locking Tools Manager actief is, deze zichzelf gemakkelijk uitschakelt en uit de weg loopt. Wanneer World Locking Tools Manager is uitgeschakeld, gedraagt deze zich als een normale WorldAnchor.

Als om een andere reden WorldAnchors nog steeds vereist zijn in de scène (bijvoorbeeld voor het delen van netwerken), kunnen ze worden gebruikt met een adapter, geleverd als WorldAnchorAdapter.

De WorldAnchorAdapter transformeert de onbewerkte positie van een GameObject dat is geplaatst door een WorldAnchor, in de globale ruimte van Unity, en past de transformatie vervolgens toe op een doelobject. Als u het wilt gebruiken, moet worldanchor niet rechtstreeks aan een object worden toegevoegd, maar worden toegepast op een proxyobject (meestal een anderszins leeg GameObject). Vervolgens leest de WorldAnchorAdapter bij Update() de worldanchoradapter de houding van de WorldAnchor, transformeert het op de juiste manier en past deze toe op het doel.

Installatie voltooid

Nadat u de bovenstaande stappen hebt gevolgd, wordt het project dat op het apparaat is geïmplementeerd, aangepast door World Locking Tools uitgevoerd om een optimaal stabiele wereld-vergrendelde ruimte te behouden. Vaste objecten die in de scène worden geplaatst, blijven visueel consistent, zowel ten opzichte van elkaar als met de fysieke wereld.

Beschikbare voorbeeldtoepassingen

Voorbeeldscènes, met inbegrip van zowel scripts als assets, worden geleverd om het complexere gebruik van de mogelijkheden van World Locking Tools te demonstreren.

De WorldLockedPhysicsSample biedt bijvoorbeeld een eenvoudige omgeving waarin fysiek gesimuleerde objecten kunnen worden gemaakt en verwijderd, met elkaar en met de omgeving (de ruimtelijke toewijzing).

Voor een meer gerichte blik op de functie Ruimte vastmaken biedt de SpacePin een veel vereenvoudigd voorbeeld van het afstemmen van een grootschalig virtueel object op echte functies.

De RayPins breidt de mogelijkheden uit die zijn geïntroduceerd door het SpacePin-voorbeeld, waardoor de virtuele wereld kan worden vastgemaakt aan de fysieke wereld met raytests op basis van de ruimtelijke mesh.

Verwijzingen om aan de slag te gaan

Als u niet bekend bent met de basisbeginselen van het maken, bouwen en implementeren van AR-apps in de HoloLens-familie van apparaten, zijn hier enkele verwijzingen die u op weg kunnen helpen.

Overzicht van Unity-ontwikkeling : Unity voor MR/AR-ontwikkeling.

MR Basics 100 - Aan de slag met ontwikkelen voor HoloLens

HoloLens 2 zelfstudies: aan de slag met het ontwikkelen voor HoloLens 2.

Systemen coördineren Coördineer de ruimte-implicaties in AR-ontwikkeling.

  • Houd er rekening mee dat World Locking Tools de problemen oplossen die hier worden besproken.

Hebt u problemen?

Zie gids voor probleemoplossing.