Configurazione iniziale degli strumenti di blocco mondiale
Configurazione più sottile possibile
L'esercitazione seguente illustra come eseguire la configurazione minima per ottenere e usare tutto ciò che si trova nel mondo dell'applicazione, senza alcuna ulteriore azione (ad esempio, ancoraggi spaziali) necessari. Si trova nel repository Samples pari a questo repository.
Guida introduttiva
Un approccio meno dettagliato e più pragmatico per l'integrazione di WLT in un progetto è disponibile qui. Se appropriato, fa riferimento a queste pagine più approfondite. Anche se è davvero una questione di preferenza personale che approccio è più appropriato, una rapida lettura della pagina Prima di iniziare può essere un risparmio di tempo su dove dedicare energie in questa documentazione.
Ambienti supportati
Gli strumenti di blocco mondiale per Unity sono attualmente destinati alle applicazioni UWP per la famiglia di dispositivi HoloLens. Sono supportati sia HoloLens (x86) che HoloLens 2 (ARM64) originali.
Il supporto sperimentale per altre piattaforme è disponibile tramite i sottosistemi AR di Unity.
La compilazione di World Locking Tools continua integration (CI) convalida con Unity2018.4.6f1 con Visual Studio 2017. Tuttavia, lo sviluppo WLT completo è stato fatto anche usando il gamut delle versioni di Unity2018 e una gamma di Unity2019. Sia Visual Studio 2017 che Visual Studio 2019 sono stati usati nello sviluppo degli strumenti.
Se si verificano problemi di compatibilità con altre versioni di Unity e/o Visual Studio, è consigliabile ascoltarlo. Il modo migliore per segnalare eventuali problemi è il portale dei problemi in GitHub.
Sfondo assunto
Si presuppone che le persone che cercano di integrare la soluzione World Locking Tools nei loro progetti hanno già familiarità con le nozioni di base di compilazione e distribuzione di applicazioni per la famiglia di dispositivi HoloLens. In caso contrario, sono disponibili alcuni riferimenti eccezionali alla fine di questo articolo.
Livelli degli strumenti di blocco mondiale
Gli strumenti di blocco mondiale sono suddivisi in quattro livelli. Con le frecce che puntano verso il livello a seconda del livello, il grafico di dipendenza semplice è simile al seguente:
Le righe tratteggiate indicano dipendenze facoltative.
Mentre il livello Esempi usa MixedRealityToolkit (MRTK), nessuno degli altri livelli ha dipendenze esterne e la funzionalità completa è disponibile compatibile con ma indipendentemente da MRTK.
Altre note sulle dipendenze delle applicazioni seguono di seguito.
I livelli possono essere riepilogati come segue:
Plug-in
Un'interfaccia imperativa che consente la comunicazione diretta con la DLL del motore. I problemi comuni, ad esempio il marshalling degli argomenti, vengono eseguiti qui e alcuni componenti di più funzioni spesso usati in combinazione con direttive composte. Rimane un'interfaccia C# di basso livello alla DLL C++ sottostante. Il suo uso diretto è disponibile, ma non è necessario né consigliabile.
Core
Core è un'incapsulazione di tutti i passaggi necessari per ottenere i vantaggi dello spazio stabile di World Locking Tools, racchiuso in un'interfaccia dichiarativa. Si prevede che un'applicazione funzionante venga fornita usando solo le funzionalità di Core.
Strumenti
Gli strumenti sono in gran parte diagnostici in natura. Le visualizzazioni dei processi degli strumenti di blocco mondiale sono incluse nei moduli facili da aggiungere a qualsiasi progetto che usa Gli strumenti di blocco mondiale.
Altre utilità pratiche sono incluse, ma si prevede che siano utili per iniziare a scrivere soluzioni personalizzate, anziché essere soluzioni finali come offerte di base.
Esempio
Il livello Esempi tenta di presentare esempi di configurazione di scenari comuni quando si usano gli strumenti di blocco mondiale e le procedure consigliate nell'integrazione degli strumenti di blocco mondiale in vari scenari.
Le dipendenze MRTK necessarie per l'esperienza utente e la manipolazione degli oggetti sono limitate agli script e ai prefab al livello Esempi. Ciò lascia i livelli inferiori liberi di tutte le dipendenze esterne.
Gli script e gli asset nel livello Esempi non devono essere integrati direttamente nei prodotti di spedizione, anche se non vi è alcun divieto contro di esso. Piuttosto, la loro costruzione favorisce semplicità e chiarezza rispetto alla riutilizzabilità e all'efficienza.
Applicazione
In generale, l'applicazione richiederà solo una dipendenza da World Locking Tools Core.
Durante lo sviluppo, molte visualizzazioni e altri helper per comprendere il comportamento imprevisto sono disponibili nel livello Strumenti. Questi helper sarebbero idealmente rimossi da un'applicazione completata o almeno disabilitata. Naturalmente, sono gratuiti anche per altri usi, nel loro formato corrente o modificato. Per informazioni dettagliate, vedere la licenza.
Per l'uso avanzato e la sperimentazione delle funzionalità complete di World Locking Tools, il livello plug-in offre l'accesso imperativo di basso livello alla DLL del motore.
Se l'accesso al livello plug-in diventa necessario, può puntare a una carenza nell'area api offerta nel livello Core. Il team degli strumenti di blocco mondiale sta sempre cercando di riempire tali lacune. Valutare la possibilità di contribuire a tali informazioni dettagliate al team. Vedere contribuire.
Nota di avviso sulla lunghezza del percorso di installazione
Alcune versioni di MRTK presentano un problema con percorsi di installazione lunghi. La lunghezza completa del percorso delle sottocartelle profonde nell'installazione di MRTK può superare il limite di percorso di Windows (260 caratteri). Se viene visualizzato un errore di compilazione del modulo seguente:
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"
ma il file è effettivamente presente nell'unità, quindi il problema è probabile che la lunghezza del percorso. Il team MRTK è consapevole di questo e sta lavorando per migliorarlo (nota: credo che abbiano apportato grandi miglioramenti qui e non è più un problema). Nel frattempo, la soluzione alternativa consiste nell'abbreviare il prefisso del percorso in base a una combinazione dei seguenti elementi:
- Installare il progetto Unity in una radice del percorso di lunghezza più breve, ad esempio "D:\Proj"
- Se si clona il repository, clonare la radice di World Locking Tools in un valore più breve rispetto al valore predefinito "\MixedReality-WorldLockingTools-Unity", ad esempio:
git clone https://github.com/microsoft/MixedReality-WorldLockingTools-Unity.git d:\MyGit\wlt
Questo limite di percorso non è in genere un problema con gli strumenti di blocco mondiale, poiché non usano una struttura di cartelle che è più profonda.
Aggiunta di strumenti di blocco del mondo a un progetto Unity
Nota
Di seguito viene descritta l'installazione manuale degli strumenti di blocco mondiale e delle dipendenze. Un processo di installazione molto più semplificato è disponibile tramite lo strumento di funzionalità Realtà mista. L'installazione tramite lo strumento di funzionalità è descritta qui. Se lo strumento di funzionalità installa WLT, è possibile ignorare le operazioni seguenti e procedere con l'aggiunta di WLT alla scena
World Locking Tools si basa sul nuget per installare il motore Frozen World sottostante.
Se si aggiunge World Locking Tools a un progetto esistente, è consigliabile iniziare con un progetto verificato per compilare e distribuire in un dispositivo HoloLens. Ciò consente di separare i problemi relativi all'esecuzione di un'app in HoloLens al primo posto, che può essere complicata, dai problemi relativi agli strumenti di blocco mondiale. Passare quindi alle sezioni Asset asset del motore FrozenWorld e World Locking Tools .
Installazione del motore FrozenWorld
La DLL del motore del mondo congelato può essere ottenuta da NuGet usando l'eccellente utilità NuGet for Unity o manualmente.
Uso di NuGet per Unity
Assicurarsi che il feed nuget.org sia in origini. Controllare questa opzione in Unity Modifica > preferenze > NuGet per Unity>. In caso contrario, entrambi:
Usare l'interfaccia utente aggiungi nuova interfaccia utente di origine in Unity Modifica > preferenze > NuGet per Unity > per aggiungere la stessa condivisione.
- Sostituire "Nuova origine" con un nome della scelta , ad esempio "NuGet".
- Sostituire "source_path" con "http://www.nuget.org/api/v2/".
Dopo aver confermato il feed di nuget.org, in Unity > NuGet Gestisci pacchetti NuGet > trovare e installare la versione più recente di Microsoft.MixedReality.FrozenWorld.Engine. (Cercare "FrozenWorld".)
Per eseguire nuovamente l'aggiornamento a una versione successiva, aprire Unity > NuGet Gestisci pacchetti NuGet > e trovare di nuovo il pacchetto FrozenWorld.Engine e selezionare Aggiorna. Nota: potrebbe essere necessario visualizzare la scheda Aggiornamenti per trovare la versione che si sta cercando.
Installazione manuale della DLL del motore del mondo congelata
Usare un editor di testo per aggiungere una packageSources riga a Asset/NuGet.config, ad esempio:
<packageSources>
<add key="NuGet" value="http://www.nuget.org/api/v2/" />
</packageSources>
Se non si dispone già di un file Asset/NuGet.config, è possibile copiarlo dal repository github Strumenti di blocco mondiale.
Usando un editor di testo, aggiungere il pacchetto DLL del motore congelato ad Asset/packages.config, ad esempio:
<?xml version="1.0" encoding="utf-8"?>
<packages>
<package id="Microsoft.MixedReality.Unity.FrozenWorld.Engine" version="1.0.0" />
</packages>
Anche in questo caso, se non si dispone già di un file Asset/packages.config, è possibile ottenere il file dal repository gitHub strumenti di blocco mondiale o copiare semplicemente il file precedente in un file di testo denominato "Asset/packages.config".
Dopo aver configurato NuGet.config e packages.config, installare per:
- Ottenere la nuget.exe più recente dai download nuGet.
- Assicurarsi che nuget.exe sia nel percorso (qui si presuppone che sia stato copiato in Asset).
- Aprire una finestra dei comandi di PowerShell e modificare la directory nella cartella Asset.
- Eseguire il comando seguente:
.\nuget.exe restore
Per eseguire l'aggiornamento a una versione successiva:
- Aggiornare il numero di versione FrozenWorld.Engine nel file packages.config precedente alla versione desiderata (ad esempio, version="1.0.0" diventa versione="1.0.1").
- Eliminare qualsiasi elemento nella cartella Asset/Pacchetti a partire da "Microsoft.MixedReality.Unity.FrozenWorld.Engine".
- Eseguire di nuovo nuget.exe come indicato in precedenza.
Asset degli strumenti di blocco mondiale
Importare i file di Strumenti .unitypackage di blocco del mondo necessari nel progetto (metodo preferito) o copiarli in. Possono essere spostati in una sottocartella all'interno di Asset per uscire dal modo per lo sviluppo di applicazioni.
I file stabili .unitypackage più recenti sono disponibili in Strumenti di blocco mondiale per le versioni di Unity.
Il livello WorldLocking.Core e Engine sarà sicuramente necessario, quindi un pacchetto di installazione minimo sarebbe WorldLockingCoreEngine.unitypackage.
Per determinare quali altri livelli potrebbero essere necessari, vedere la discussione sui livelli degli strumenti di blocco mondiale e sulle relative dipendenze sopra. Ogni livello è contenuto in un singolo pacchetto Unity.
Poiché alcuni degli esempi di strumenti di blocco mondiale usano funzionalità di MRTK, uno snapshot MRTK compatibile è incluso con gli esempi unitypackage. Per la versione più recente di MRTK, vedere qui.
Aggiunta di strumenti di blocco mondiale a una scena unity
Nota
I passaggi elencati di seguito sono tutti automatizzati nell'utilità Configurazione scena WLT, che è possibile trovare nel menu Realtà mista Toolkit > Utilities > World Locking Tools.
All'interno di un progetto Unity contenente il motore FrozenWorld (da nuget.org), importare qualsiasi livello di asset degli strumenti di blocco mondiale desiderato (ma almeno WorldLocking.Core) e facoltativamente MRTK. Creare quindi una nuova scena (o aprire una scena esistente).
Nota
Aggiungere un nodo aggiuntivo nella radice della gerarchia della fotocamera. Questo nodo verrà usato per regolare la fotocamera testata nello spazio bloccato al mondo. Se si usa MRTK, questo nuovo GameObject sarà l'elemento padre dello spazio MixedRealityPlayspace.
Esperienza di base
Trascinare un prefab WorldLockingManager da Assets/WorldLocking.Core/Prefabs nella scena. Il suo posto nella scena non importa, ma non dovrebbe essere nell'albero della fotocamera. Per una configurazione suggerita, vedere una scena di esempio .
Sono disponibili impostazioni nel prefab WorldLockingManager, ma lasciandole ai valori predefiniti è consigliabile iniziare.
Per spiegazioni delle opzioni presentate, vedere Contesto degli strumenti di blocco mondiale .
[Facoltativo] MRTK
Gli strumenti di blocco mondiale sono complementari con ma ortogonali a MRTK. L'uso di MRTK insieme a World Locking Tools è completamente facoltativo.
Detto questo, gli esempi degli strumenti di blocco mondiale vengono creati usando MRTK e MRTK è generalmente estremamente utile per sviluppare i tipi di applicazioni MR che traggono vantaggio dalla maggior parte degli strumenti di blocco mondiale.
Se si usa MRTK, anziché usare lo snapshot incluso negli esempi, è consigliabile aggiungere le versioni più recenti di almeno i pacchetti seguenti:
- MixedReality.Toolkit
- MixedReality.Toolkit.Providers
- MixedReality.Toolkit.Services
- MixedReality.Toolkit.SDK
[Facoltativo] Visualizzazione di ancoraggi bloccati a spongy e mondo
Ciò richiede l'aggiunta di WorldLocking.Tools agli asset del progetto.
Per visualizzare gli ancoraggi, trascinare AnchorGraphVisual prefab da Assets/WorldLocking.Tools/Prefabs nella scena. Le caselle di controllo per attivare gli aspetti della visualizzazione nel controllo si trovano in WorldLockingManager.
Come diagnostica, le visualizzazioni WorldLocking.Tools non sono fortemente ottimizzate e ridurranno le prestazioni molto prima che il tempo di elaborazione degli strumenti di blocco globale principale diventi rilevante.
[Facoltativo] Un dashboard semplice per il controllo dei parametri all'interno di Realtà mista
Un semplice HUD è disponibile, che può essere usato per controllare WorldLockingManager in fase di esecuzione dall'interno di MR. Questi vengono forniti nel pacchetto Esempi. Anche se possono essere usati come è, sono destinati a modelli durante la creazione di funzionalità simili in un sistema di visualizzazione e un'esperienza utente personalizzate delle applicazioni.
Trascinare nel prefab WorldLocking.Examples/Prefabs/Dashboard e puntare il relativo campo Visualizzatore di ancoraggio al visualizzatore nella sezione precedente.
Migrazione di una scena esistente a Strumenti di blocco mondiale
Il cambiamento più importante quando si passa a World Locking Tools è che non esiste più un requisito per l'uso di ancoraggi spaziali agli oggetti virtuali di blocco mondiale.
Gli ancoraggi spaziali sono stati tradizionalmente l'unico strumento disponibile per singoli oggetti di blocco mondiale. Tuttavia, quando si usano gli strumenti di blocco mondiale, lo spazio di coordinate in cui sono presenti gli oggetti virtuali è già bloccato al mondo. Non è necessario alcun blocco aggiuntivo.
Non solo gli ancoraggi spaziali non necessari, non funzionano correttamente, poiché non riescono a prendere in considerazione ulteriori trasformazioni della gerarchia della fotocamera (ad esempio la trasformazione MRTK "Playspace").
Pertanto, tutti gli ancoraggi spaziali devono essere rimossi dalla scena e tutti gli script che aggiungono ancoraggi spaziali devono interrompere l'operazione. Gli ancoraggi spaziali non devono essere sostituiti da nulla; Gli strumenti di blocco mondiale ancoraranno i loro obiettivi al mondo reale.
Se è consigliabile confrontare il blocco del mondo con e senza Strumenti di blocco mondiale, invece di rimuovere WorldAnchors, possono essere sostituiti con ToggleWorldAnchor fornito in WorldLocking.Tools.
ToggleWorldAnchor funziona esattamente come un WorldAnchor, con la differenza importante che quando Il World Locking Tools Manager è attivo, si disabilita facilmente e diventa fuori strada. Quando World Locking Tools Manager è disabilitato, si comporta come normale WorldAnchor.
Se per un altro motivo WorldAnchors è ancora necessario nella scena (ad esempio, per la condivisione di rete), possono essere usati con un adattatore, fornito come WorldAnchorAdapter.
WorldAnchorAdapter trasforma la posizione non elaborata di un GameObject posizionato da un WorldAnchor, nello spazio globale Unity bloccato al mondo e quindi applica la trasformazione a un oggetto di destinazione. Per usarlo, anziché aggiungere un WorldAnchor direttamente a un oggetto, il WorldAnchor deve essere applicato a un oggetto proxy (in genere un GameObject vuoto altrimenti vuoto) e quindi su Update() il WorldAnchorAdapter legge la posizione del WorldAnchorAdapter, lo trasforma correttamente e lo applica alla destinazione.
Installazione completata
Dopo aver seguito i passaggi precedenti, il progetto distribuito nel dispositivo verrà modificato da World Locking Tools per mantenere uno spazio bloccato a livello mondiale ottimale. Tutti gli oggetti fissi posizionati nella scena rimarranno visivamente coerenti tra loro e con il mondo fisico.
Applicazioni di esempio disponibili
Le scene di esempio, inclusi gli script e gli asset, vengono fornite per illustrare l'uso più complesso delle funzionalità di World Locking Tools.
Ad esempio, WorldLockedPhysicsSample fornisce un ambiente semplice in cui è possibile creare e rimuovere oggetti simulati fisicamente, interagire tra loro e con l'ambiente (mapping spaziale).
Per un'occhiata più focalizzata alla funzionalità di aggiunta dello spazio, SpacePin offre un esempio molto semplificato di allineamento di un oggetto virtuale su larga scala alle funzionalità reali.
RayPins si espande sulle funzionalità introdotte dall'esempio SpacePin, consentendo l'aggiunta del mondo virtuale al mondo fisico con test di raggio sulla mesh spaziale.
Riferimenti per l'introduzione
Se non si ha familiarità con le nozioni di base di creazione, compilazione e distribuzione di app AR nella famiglia di dispositivi HoloLens, ecco alcuni riferimenti che potrebbero aiutare a iniziare.
Panoramica dello sviluppo di Unity : Unity per lo sviluppo MR/AR.
Nozioni di base su MR 100 - Introduzione allo sviluppo per HoloLens
esercitazioni HoloLens 2 - Introduzione allo sviluppo per HoloLens 2.
Sistemi di coordinate Coordinare le implicazioni dello spazio nello sviluppo ar.
- Si noti che gli strumenti di blocco mondiale risolveranno i problemi illustrati qui.