Dela via

Inledande installation av World Locking Tools

  • Artikel

Slimmest möjlig installation

Självstudien här går igenom den minimala konfigurationen för att komma igång med allt i ditt program världslåst, utan ytterligare åtgärder (till exempel spatiala fästpunkter) som krävs. Den finns på lagringsplatsen Samples till den här lagringsplatsen.

Snabbstartsguide

En mindre konceptuellt detaljerad och mer pragmatisk metod för att integrera WLT i ett projekt finns här. I förekommande fall refererar den tillbaka till dessa mer grundliga sidor. Även om det verkligen är en fråga om personlig preferens vilken metod som är lämpligare, kan en snabb läsning av sidan Innan du kommer igång vara en tidssparare om var du ska ägna energi i den här dokumentationen.

Miljöer som stöds

World Locking Tools för Unity riktar sig för närvarande till UWP-program för HoloLens-serien med enheter. Både de ursprungliga HoloLens (x86) och HoloLens 2 (ARM64) stöds.

Experimentellt stöd för andra plattformar är tillgängligt via Unitys AR-undersystem.

Bygget av World Locking Tools (CI) verifieras med Unity2018.4.6f1 med Visual Studio 2017. Men omfattande WLT-utveckling har också gjorts med hjälp av omfånget unity2018-versioner och en rad Unity2019. Både Visual Studio 2017 och Visual Studio 2019 har använts i utvecklingen av verktygen.

Om du upplever några kompatibilitetsproblem med andra versioner av Unity och/eller Visual Studio skulle vi gärna vilja höra om det! Det bästa sättet att rapportera eventuella problem är via problemportalen på GitHub.

Antagen bakgrund

Det antas att personer som vill integrera lösningen World Locking Tools i sina projekt redan är bekanta med grunderna i att skapa och distribuera program för HoloLens-serien med enheter. Annars finns det några bra referenser i slutet av den här artikeln.

World Locking Tools-lagren

World Locking Tools är indelat i fyra lager. Med pilarna som pekar mot lagret är beroende av ser det enkla beroendediagrammet ut så här:

Lagerdiagram

De streckade linjerna anger valfria beroenden.

Medan exempellagret använder MixedRealityToolkit (MRTK), har inget av de andra lagren några externa beroenden, och de fullständiga funktionerna är tillgängliga som är kompatibla med men oberoende av MRTK.

Mer information om programberoenden finns nedan.

Lagren kan sammanfattas på följande sätt:

Plugin-program

Ett imperativt gränssnitt som möjliggör direkt kommunikation med motorns DLL. Vanliga problem som argumentmarshantering utförs här och vissa består av flera funktioner som ofta används i kombination till sammansatta direktiv. Det är fortfarande ett C#-gränssnitt på låg nivå till den underliggande C++ DLL-filen. Dess direkta användning är tillgänglig, men behövs inte eller rekommenderas inte.

Kärna

Core är en inkapsling av alla steg som krävs för att få fördelarna med World Locking Tools stabila världlåst utrymme, paketerat i ett deklarativt gränssnitt. Ett fungerande program förväntas skickas med endast funktioner från Core.

Verktyg

Verktygen är till stor del diagnostiska. Visualiseringar av Processer för World Locking Tools ingår i formulär som är enkla att lägga till i alla projekt som använder World Locking Tools.

Andra praktiska verktyg ingår, men förväntas vara till hjälp för att komma igång med att koda anpassade lösningar i stället för att vara slutgiltiga lösningar som Core erbjuder.

Exempel

Exempellagret försöker presentera exempel på hur du konfigurerar vanliga scenarier när du använder World Locking Tools och metodtips för integrering av World Locking Tools i olika scenarier.

Alla nödvändiga MRTK-beroenden för UX- och objektmanipulering är begränsade till skript och prefabs på exempelskiktet. Detta lämnar de nedre lagren fria från eventuella externa beroenden.

Skript och tillgångar i skiktet Exempel förväntas inte integreras direkt i leveransprodukter, även om det inte finns något förbud mot det. Snarare gynnar deras konstruktion enkelhet och klarhet framför återanvändning och effektivitet.

Programmet

I allmänhet behöver programmet bara ha ett beroende av World Locking Tools Core.

Under utvecklingen finns det många visualiseringar och andra hjälpare för att förstå oväntat beteende i verktygsskiktet. De här hjälparna skulle helst tas bort från ett färdigt program, eller åtminstone inaktiveras. Naturligtvis är de gratis för andra användningsområden också, antingen i sin nuvarande form eller ändras. Mer information finns i licensen.

För avancerad användning och experimentering av World Locking Tools fullständiga funktioner erbjuder plugin-lagret imperativ åtkomst på låg nivå till motor-DLL.

Om åtkomst till plugin-lagret blir nödvändigt kan det peka på en brist på API-ytan som erbjuds i Core-lagret. World Locking Tools-teamet vill alltid fylla sådana luckor. Överväg att bidra med sådana insikter till teamet. Se bidra.

En varning om längden på installationssökvägen

Vissa versioner av MRTK har problem med långa installationssökvägar. Den fullständiga sökvägslängden för djupa undermappar i MRTK-installationen kan överskrida sökvägsgränsen för Windows (260 tecken). Om ett byggfel i följande formulär visas:

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"

men filen finns faktiskt där på enheten, då problemet är sannolikt sökvägen längd. MRTK-teamet är medvetet om detta och arbetar för att förbättra det (obs! Jag tror att de har gjort stora förbättringar här och det är inte längre ett problem). Under tiden är lösningen att förkorta sökvägsprefixet med en kombination av följande:

  1. Installera Unity-projektet i en rot för kortare sökväg, till exempel "D:\Proj"
  2. Om du klonar lagringsplatsen klonar du roten för World Locking Tools till något kortare än standardvärdet "\MixedReality-WorldLockingTools-Unity", till exempel:
git clone https://github.com/microsoft/MixedReality-WorldLockingTools-Unity.git d:\MyGit\wlt

Den här sökvägsgränsen är vanligtvis inte ett problem med Själva låsningsverktygen i världen, eftersom de inte använder en mappstruktur som är lika djup.

Lägga till World Locking Tools i ett Unity-projekt

Kommentar

Följande beskriver manuell installation av World Locking Tools och beroenden. En mycket mer effektiv installationsprocess är tillgänglig via funktionsverktyget för Mixed Reality. Installation via funktionsverktyget beskrivs här. Om funktionsverktyget installerar WLT kan du hoppa över följande och fortsätta med att lägga till WLT i din scen

World Locking Tools förlitar sig på nuget för att installera den underliggande Frozen World Engine.

Om du lägger till World Locking Tools i ett befintligt projekt bör du börja med ett projekt som har verifierats för att skapa och distribuera till en HoloLens-enhet. Detta hjälper dig att separera problem med att få en app att köras på HoloLens i första hand, vilket kan vara komplicerat, från problem med World Locking Tools. Gå sedan vidare till avsnitten FrozenWorld Engine installation och World Locking Tools Assets nedan.

Installation av FrozenWorld Engine

DLL:n Frozen World Engine kan hämtas från NuGet antingen med hjälp av det utmärkta NuGet For Unity-verktyget eller manuellt.

Använda NuGet för Unity

Kontrollera att nuget.org feed finns i källor. Kontrollera detta i NuGet > för Unity-redigeringsinställningar >> för Unity. Om inte, antingen:

Använd användargränssnittet Lägg till ny källa i Unity > Edit > Preferences > NuGet for Unity för att lägga till samma resurs.

  • Ersätt "Ny källa" med ett valfritt namn (till exempel "NuGet").
  • Ersätt "source_path" med "http://www.nuget.org/api/v2/".

När du har bekräftat nuget.org feed går du till Unity > NuGet > Manage NuGet Packages och letar upp och installerar den senaste versionen av Microsoft.MixedReality.FrozenWorld.Engine. (Sök efter "FrozenWorld".)

Om du vill uppdatera till en senare version öppnar du Unity > NuGet > Manage NuGet Packages igen och letar reda på paketet FrozenWorld.Engine och väljer Uppdatera. Obs! Du kan behöva fliken Uppdateringar för att hitta den version du letar efter.

Manuell DLL-installation för Frozen World Engine

Använd en textredigerare för att lägga till en packageSources rad i Assets/NuGet.config, till exempel:

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

Om du inte redan har en fil Assets/NuGet.config kan du kopiera den från github-lagringsplatsen World Locking Tools.

Med hjälp av en textredigerare lägger du till DLL-paketet Frozen World Engine i Assets/packages.config, till exempel:

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

Om du inte redan har en fil Assets/packages.config kan du hämta filen från github-lagringsplatsen World Locking Tools eller helt enkelt kopiera ovanstående till en textfil med namnet "Assets/packages.config".

Installera efter att ha konfigurerat NuGet.config och packages.config:

  1. Hämta de senaste nuget.exe från NuGet-nedladdningar.
  2. Kontrollera att nuget.exe finns i din sökväg (här antar jag att den kopierades till Tillgångar).
  3. Öppna ett PowerShell-kommandofönster och ändra katalogen till mappen Tillgångar.
  4. Kör följande kommando:
.\nuget.exe restore

Så här uppgraderar du till en senare version:

  1. Uppdatera versionsnumret för FrozenWorld.Engine i filen packages.config ovan till önskad version (till exempel version="1.0.0" blir version="1.0.1").
  2. Ta bort allt i mappen Assets/Packages som börjar med "Microsoft.MixedReality.Unity.FrozenWorld.Engine".
  3. Kör om nuget.exe enligt ovan.

Tillgångar för World Locking Tools

Importera antingen nödvändiga World Locking Tools-filer .unitypackage till projektet (önskad metod) eller kopiera dem. De kan flyttas till en undermapp i Tillgångar för att få dem ur vägen för programutveckling.

De senaste stabila .unitypackage filerna finns i World Locking Tools för Unity-versioner.

WorldLocking.Core- och Engine-lagret kommer definitivt att krävas, så ett minimalt installationspaket skulle vara WorldLockingCoreEngine.unitypackage.

Information om vilka andra skikt som kan krävas finns i diskussionen om World Locking Tools-lager och deras beroenden ovan. Varje lager finns i ett enda Unity-paket.

Eftersom vissa av exemplen på World Locking Tools använder funktioner från MRTK ingår en kompatibel MRTK-ögonblicksbild i Exemplen unitypackage. För den senaste MRTK-versionen, titta här.

Lägga till World Locking Tools i en Unity-scen

Kommentar

Stegen nedan är alla automatiserade i scenverktyget WLT Configure, som finns på menyn Mixed Reality Toolkit > Utilities > World Locking Tools. Configuraton-menyn

I ett Unity-projekt som innehåller FrozenWorld-motorn (från nuget.org) importerar du alla önskade World Locking Tools-lager (men åtminstone WorldLocking.Core) och eventuellt MRTK. Skapa sedan en ny scen (eller öppna en befintlig scen).

Kommentar

Lägg till en extra nod i roten i kamerahierarkin. Den här noden kommer att användas för att justera den huvudspårade kameran till världslåst utrymme. (Om du använder MRTK skulle den här nya GameObject vara överordnad till MixedRealityPlayspace.)

Kärnupplevelsen

Dra en WorldLockingManager-prefab från Assets/WorldLocking.Core/Prefabs till din scen. Dess plats i scenen spelar ingen roll, men det bör inte vara i kameraträdet. En föreslagen konfiguration finns i en exempelscen .

Det finns inställningar som är tillgängliga på WorldLockingManager-prefab, men att lämna dem till standardvärdena rekommenderas för att komma igång.

Se World Locking Tools Context (World Locking Tools Context ) för att få en förklaring av de alternativ som visas.

[Valfritt] MRTK

World Locking Tools kompletterar men ortoggonal till MRTK. Användning av MRTK tillsammans med World Locking Tools är helt valfritt.

Med detta sagt är World Locking Tools-exemplen byggda med MRTK, och MRTK är i allmänhet mycket värdefullt för att utveckla de typer av MR-program som drar mest nytta av World Locking Tools.

Om du använder MRTK i stället för att använda ögonblicksbilden som ingår i exemplen rekommenderar vi att du lägger till de senaste versionerna av minst följande paket:

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

[Valfritt] Visualisera svampiga och världslåst fästpunkter

Detta kräver att WorldLocking.Tools läggs till i projektets tillgångar.

Om du vill visualisera dina fästpunkter drar du AnchorGraphVisual prefab från Assets/WorldLocking.Tools/Prefabs till din scen. Kryssrutor för att växla aspekter av visualiseringen i inspektören finns i WorldLockingManager.

Som diagnostik är visualiseringarna WorldLocking.Tools inte kraftigt optimerade och minskar prestanda långt innan bearbetningstiden för Kärnverktyg för låsning av världen blir relevant.

[Valfritt] En enkel instrumentpanel för parameterkontroll i Mixed Reality

En enkel HUD är tillgänglig, som kan användas för att styra WorldLockingManager vid körning inifrån MR. Dessa anges i exempelpaketet. Även om de kan användas som de är, är de avsedda som mönster när liknande funktioner skapas i ett program eget visningssystem och UX.

Dra i prefab för WorldLocking.Examples/Prefabs/Dashboard och peka dess Anchor Visualizer-fält på Visualiseraren i föregående avsnitt.

Migrera en befintlig scen till World Locking Tools

Den största förändringen när du flyttar till World Locking Tools är att det inte längre finns något krav på att använda rumsliga fästpunkter för att låsa virtuella objekt i världen.

Rumsliga fästpunkter har traditionellt varit det enda verktyget som är tillgängligt för världslåsande enskilda objekt. Men när du använder World Locking Tools är koordinatutrymmet som dessa virtuella objekt finns i redan världslåst. Ingen ytterligare låsning krävs.

Rumsliga fästpunkter är inte bara onödiga, de fungerar inte korrekt, eftersom de inte tar hänsyn till ytterligare transformeringar i kamerahierarkin (till exempel MRTK-transformeringen "Playspace").

Därför bör alla rumsliga fästpunkter tas bort från scenen, och alla skript som lägger till spatiala fästpunkter bör sluta göra det. De rumsliga fästpunkterna behöver inte ersättas av någonting. World Locking Tools kommer att förankra sina mål i den verkliga världen.

Om det är önskvärt att jämföra världslåsning med och utan World Locking Tools kan de i stället för att ta bort WorldAnchors ersättas med ToggleWorldAnchor som tillhandahålls i WorldLocking.Tools.

ToggleWorldAnchor fungerar exakt på samma sätt som en WorldAnchor, med den viktiga skillnaden att när World Locking Tools Manager är aktiv inaktiverar den sig bekvämt och kommer ur vägen. När World Locking Tools Manager är inaktiverat fungerar det som en vanlig WorldAnchor.

Om WorldAnchors av någon annan anledning fortfarande krävs i scenen (till exempel för nätverksdelning) kan de användas med ett adapter som levereras som WorldAnchorAdapter.

WorldAnchorAdapter omvandlar den råa positionen för en GameObject placerad av en WorldAnchor, till världens låsta globala Unity-utrymme och tillämpar sedan omvandlingen på ett målobjekt. Om du vill använda den, i stället för att lägga till en WorldAnchor direkt till ett objekt, bör WorldAnchor tillämpas på ett proxyobjekt (vanligtvis ett annars tomt GameObject) och sedan på Update() läser WorldAnchorAdapter WorldAnchors pose, transformerar den korrekt och tillämpar den på målet.

Installationen är klar

Efter att ha följt stegen ovan körs projektet som distribueras till enheten justerat av World Locking Tools för att upprätthålla ett optimalt stabilt världlåst utrymme. Alla fasta objekt som placeras i scenen förblir visuellt konsekventa både i förhållande till varandra och med den fysiska världen.

Tillgängliga exempelprogram

Exempelscener, inklusive både skript och tillgångar, tillhandahålls för att demonstrera mer komplex användning av Funktionerna i World Locking Tools.

Till exempel ger WorldLockedPhysicsSample en enkel miljö där fysiskt simulerade objekt kan skapas och tas bort, interagera med varandra och med miljön (den rumsliga mappningen).

För en mer fokuserad titt på funktionen Fäst utrymme ger SpacePin ett mycket förenklat exempel på hur du justerar ett storskaligt virtuellt objekt till verkliga funktioner.

RayPins utökar de funktioner som introducerades i SpacePin-exemplet, vilket gör det möjligt att fästa den virtuella världen i den fysiska världen med stråltester mot det rumsliga nätet.

Referenser för att komma igång

Om du inte känner till grunderna för att skapa, skapa och distribuera AR-appar till HoloLens-serien med enheter, finns här några referenser som kan hjälpa dig att komma igång.

Översikt över Unity Development – Unity för MR/AR-utveckling.

MR Basics 100 – Gå igenom att komma igång med att utveckla för HoloLens

Självstudier för HoloLens 2 – Gå igenom att komma igång med att utveckla för HoloLens 2.

Koordinatsystem Samordna utrymmeskonsekvenser i AR-utveckling.

  • Observera att World Locking Tools löser de problem som beskrivs här.

Har du problem?

Se felsökningsguiden.