Configurazione iniziale degli strumenti di blocco globale

Configurazione più sottile possibile

L'esercitazione seguente illustra la configurazione minima per iniziare a usare tutti gli elementi nell'applicazione bloccata, senza ulteriori azioni (ad esempio, ancoraggi nello spazio) necessari. Si trova nel repository Samples di pari livello in questo repository.

Guida introduttiva

Un approccio meno concettualmente 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 l'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 globale per Unity sono attualmente destinati alle applicazioni UWP per la famiglia di dispositivi HoloLens. Sono supportati sia HoloLens (x86) che HoloLens 2 (ARM64).

Il supporto sperimentale per altre piattaforme è disponibile tramite i sottosistemi AR di Unity.

La compilazione integrazione continua degli strumenti di blocco globale convalida con Unity2018.4.6f1 con Visual Studio 2017. Tuttavia, lo sviluppo WLT esteso è stato eseguito anche usando la gamma 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 conoscerlo. Il modo migliore per segnalare eventuali problemi è tramite il portale dei problemi in GitHub.

Sfondo presupposto

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 della compilazione e della distribuzione di applicazioni per la famiglia di dispositivi HoloLens. In caso contrario, alla fine di questo articolo sono disponibili alcuni riferimenti eccezionali.

Livelli degli strumenti di blocco globale

Gli strumenti di blocco globale sono suddivisi in quattro livelli. Con le frecce che puntano verso il livello dipendevano, il grafico delle dipendenze diretto è simile al seguente:

Le linee tratteggiate indicano dipendenze facoltative.

Mentre il livello Examples usa MixedRealityToolkit (MRTK), nessuno degli altri livelli ha dipendenze esterne e la funzionalità completa è disponibile con ma indipendentemente da MRTK.

Di seguito sono riportate altre note sulle dipendenze delle applicazioni.

I livelli possono essere riepilogati nel modo seguente:

Plugin

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 in direttive composite. Rimane un'interfaccia C# di basso livello per la DLL C++ sottostante. Il suo uso diretto è disponibile, ma non è necessario né consigliabile.

Memoria centrale

Core è un incapsulamento di tutti i passaggi necessari per ottenere i vantaggi dello spazio stabile di World Locking Tools, inserito in un'interfaccia dichiarativa. Si prevede che un'applicazione funzionante venga fornita usando solo funzionalità di Core.

Strumenti

Gli strumenti sono in gran parte diagnostici in natura. Le visualizzazioni dei processi degli strumenti di blocco globale sono incluse nei moduli facili da aggiungere a qualsiasi progetto che usa gli strumenti di blocco globale.

Sono incluse altre utilità utili, ma si prevede che siano utili per iniziare a scrivere codice di soluzioni personalizzate, invece di essere soluzioni finali come offerte core.

Esempi

Il livello Esempi tenta di presentare esempi di configurazione di scenari comuni quando si usano gli strumenti di blocco globale e le procedure consigliate per l'integrazione degli strumenti di blocco globale in vari scenari.

Tutte le dipendenze MRTK necessarie per l'esperienza utente e la manipolazione degli oggetti sono limitate agli script e ai prefab a livello di esempi. In questo modo, i livelli inferiori vengono liberati da eventuali dipendenze esterne.

Gli script e gli asset nel livello Examples 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 al riutilizzo e all'efficienza.

Applicazione

In generale, l'applicazione richiederà solo una dipendenza da World Locking Tools Core.

Durante lo sviluppo, nel livello Strumenti sono disponibili molte visualizzazioni e altri helper per comprendere il comportamento imprevisto. Questi helper sarebbero idealmente rimossi da un'applicazione completata o almeno disabilitati. 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 degli strumenti di blocco globale, il livello plug-in offre accesso imperativo di basso livello alla DLL del motore.

Se l'accesso al livello plug-in diventa necessario, può puntare a una carenza nella superficie API offerta nel livello Core. Il team world locking tools sta sempre cercando di colmare tali lacune. Valutare la possibilità di contribuire a tali informazioni al team. Vedere contributi.

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 è probabilmente la lunghezza del percorso. Il team MRTK è a conoscenza 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 tramite una combinazione dei seguenti elementi:

1. Installare il progetto Unity in una radice del percorso di lunghezza più breve, ad esempio "D:\Proj"
2. Se si clona il repository, clonare la radice di World Locking Tools in qualcosa di più breve rispetto all'impostazione predefinita "\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 globale stessi, perché non usano una struttura di cartelle che è così profonda.

Aggiunta di strumenti di blocco del mondo a un progetto Unity

World Locking Tools si basa su nuget per installare il motore Frozen World sottostante.

Se si aggiungono strumenti di blocco globale a un progetto esistente, è consigliabile iniziare con un progetto verificato per la compilazione e la distribuzione in un dispositivo HoloLens. Ciò consentirà di separare i problemi relativi all'esecuzione di un'app in HoloLens in primo luogo, che può essere complicata, dai problemi relativi agli strumenti di blocco globale. Passare quindi alle sezioni Installazione del motore FrozenWorld e Asset degli strumenti di blocco globale di seguito.

Installazione del motore FrozenWorld

La DLL del motore frozen world può essere ottenuta da NuGet usando l'eccellente utilità NuGet per Unity o manualmente.

Uso di NuGet per Unity

Assicurarsi che il feed nuget.org sia presente nelle origini. Controllare questa opzione in Unity > Modifica > preferenze > NuGet per Unity. In caso contrario, uno dei seguenti:

Usare l'interfaccia utente grafica Aggiungi nuova origine in Unity > Modifica > preferenze > NuGet per Unity per aggiungere la stessa condivisione.

• Sostituire "New Source" con il nome scelto (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 l'aggiornamento a una versione successiva, aprire di nuovo Unity > NuGet Manage NuGet Packages (Gestisci pacchetti NuGet NuGet > ) e trovare il pacchetto FrozenWorld.Engine e selezionare Aggiorna. Nota: potrebbe essere necessario usare la scheda Aggiornamenti per trovare la versione che si sta cercando.

Installazione manuale della DLL del motore frozen world

Usare un editor di testo per aggiungere una packageSources riga ad Assets/NuGet.config, ad esempio:

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

Se non si ha già un file Assets/NuGet.config, è possibile copiarlo dal repository GitHub degli strumenti di blocco globale.

Usando un editor di testo, aggiungere il pacchetto DLL Frozen World Engine a Assets/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 ha già un file Assets/packages.config, è possibile ottenere il file dal repository GitHub degli strumenti di blocco globale o semplicemente copiare il file precedente in un file di testo denominato "Assets/packages.config".

Dopo aver configurato NuGet.config e packages.config, installare per:

1. Ottenere i nuget.exe più recenti dai download di NuGet.
2. Assicurati che nuget.exe sia nel tuo percorso (qui presupporrò che sia stato copiato in Asset).
3. Aprire una finestra di comando di PowerShell e passare alla cartella Assets.
4. Esegui questo comando:

.\nuget.exe restore

Per eseguire l'aggiornamento a una versione successiva:

1. Aggiornare il numero di versione di FrozenWorld.Engine nel file packages.config precedente alla versione desiderata (ad esempio, version="1.0.0" diventa version="1.0.1").
2. Eliminare qualsiasi elemento nella cartella Assets/Packages a partire da "Microsoft.MixedReality.Unity.FrozenWorld.Engine".
3. Rieseguire nuget.exe come sopra.

Asset degli strumenti di blocco globale

Importare i file degli strumenti .unitypackage di blocco globale necessari nel progetto (metodo preferito) o copiarli. Possono essere spostati in una sottocartella all'interno di Assets per farli uscire dal modo per lo sviluppo di applicazioni.

I file stabili .unitypackage più recenti sono disponibili in Strumenti di blocco globale 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 globale e sulle relative dipendenze sopra. Ogni livello è contenuto in un singolo pacchetto Unity.

Poiché alcuni esempi di strumenti di blocco globale usano funzionalità di MRTK, uno snapshot MRTK compatibile è incluso negli esempi unitypackage. Per la versione più recente di MRTK, vedere qui.

Aggiunta di strumenti di blocco globale a una scena unity

All'interno di un progetto Unity contenente il motore FrozenWorld (da nuget.org), importare tutti i livelli asset degli strumenti di blocco globale desiderati (ma almeno WorldLocking.Core) e facoltativamente MRTK. Creare quindi una nuova scena (o aprire una scena esistente).

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.

Nel prefab WorldLockingManager sono disponibili impostazioni, ma per iniziare è consigliabile lasciarle sui valori predefiniti.

Vedere World Locking Tools Context (Contesto degli strumenti di blocco globale) per le spiegazioni delle opzioni presentate.

[Facoltativo] MRTK

World Locking Tools è complementare ma ortogonale a MRTK. L'uso di MRTK insieme a World Locking Tools è completamente facoltativo.

Detto questo, gli esempi di World Locking Tools vengono compilati con MRTK e MRTK è in genere estremamente utile nello sviluppo dei tipi di applicazioni MR che traggono vantaggio dalla maggior parte degli strumenti di blocco globale.

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 per spongy e mondo

Ciò richiede l'aggiunta di WorldLocking.Tools agli asset del progetto.

Se vuoi visualizzare gli ancoraggi, trascina il prefab AnchorGraphVisual da Assets/WorldLocking.Tools/Prefabs nella scena. Le caselle di controllo per attivare o disattivare gli aspetti della visualizzazione nel controllo si trovano in WorldLockingManager.

Come diagnostica, le visualizzazioni WorldLocking.Tools non sono altamente ottimizzate e ridurranno le prestazioni a lungo prima che il tempo di elaborazione principale degli strumenti di blocco globale diventi rilevante.

[Facoltativo] Dashboard semplice per il controllo dei parametri all'interno di Realtà mista

È disponibile un semplice HUD, che può essere usato per controllare WorldLockingManager in fase di esecuzione dall'interno di MR. Questi vengono forniti nel pacchetto Examples. Anche se possono essere usati così come sono, sono concepiti come modelli durante la compilazione 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 agli strumenti di blocco globale

Il cambiamento più importante quando si passa a World Locking Tools è che non esiste più un requisito per l'uso di ancoraggi nello spazio agli oggetti virtuali con blocco globale.

Gli ancoraggi nello spazio sono stati tradizionalmente l'unico strumento disponibile per singoli oggetti con blocco globale. Tuttavia, quando si usano gli strumenti di blocco globale, lo spazio di coordinate in cui sono presenti gli oggetti virtuali è già bloccato al mondo. Non è necessario alcun ulteriore blocco.

Non solo gli ancoraggi nello spazio non necessari, non funzioneranno correttamente, perché non tengono conto di trasformazioni aggiuntive nella gerarchia della fotocamera (ad esempio la trasformazione "Playspace" MRTK).

Pertanto, tutti gli ancoraggi nello spazio e tutti gli ancoraggi nello spazio devono essere rimossi dalla scena e tutti gli script che aggiungono ancoraggi nello spazio devono interrompere questa operazione. Gli ancoraggi nello spazio non devono essere sostituiti da nulla; Gli strumenti di blocco del mondo ancorano le loro destinazioni al mondo reale.

Se è consigliabile confrontare il blocco del mondo con e senza Strumenti di blocco globale, 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 si esce dalla strada. Quando World Locking Tools Manager è disabilitato, si comporta come normale WorldAnchor.

Se per qualche altro motivo WorldAnchors è ancora necessario nella scena (ad esempio, per la condivisione di rete), possono essere usati con una scheda, fornita 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, invece di aggiungere un WorldAnchor direttamente a un oggetto , il WorldAnchor deve essere applicato a un oggetto proxy (in genere un GameObject altrimenti vuoto) e quindi in Update() il WorldAnchorAdapter legge la posizione del WorldAnchor, lo trasforma correttamente e lo applica alla destinazione.

Installazione completata

Dopo aver seguito i passaggi precedenti, il progetto distribuito nel dispositivo verrà regolato dagli strumenti di blocco globale per mantenere uno spazio bloccato al mondo 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 dimostrare un uso più complesso delle funzionalità degli strumenti di blocco globale.

Ad esempio, WorldLockedPhysicsSample fornisce un ambiente semplice in cui è possibile creare e rimuovere oggetti fisicamente simulati, interagire tra loro e con l'ambiente (il mapping spaziale).

Per un'analisi più mirata della 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 ray sulla mesh spaziale.

Riferimenti per iniziare

Se non si ha familiarità con le nozioni di base della creazione, della compilazione e della 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 su HoloLens 2- Introduzione allo sviluppo per HoloLens 2.

Implicazioni dello spazio di coordinate dei sistemi di coordinate nello sviluppo ar.

• Si noti che Gli strumenti di blocco globale risolveranno i problemi illustrati qui.

Problemi?

Vedere la guida alla risoluzione dei problemi.