Configuração inicial das Ferramentas de Bloqueio Mundial
Configuração mais fina possível
O tutorial aqui percorre a configuração mínima para começar a funcionar com tudo em seu aplicativo bloqueado mundialmente, sem qualquer ação adicional (por exemplo, âncoras espaciais) necessária. Está no irmão Samples repo para este repo.
Guia de início rápido
Uma abordagem menos conceitualmente detalhada e mais pragmática para integrar o WLT em um projeto pode ser encontrada aqui. Se for caso disso, remete para estas páginas mais completas. Embora seja realmente uma questão de preferência pessoal qual abordagem é mais apropriada, uma leitura rápida da página Antes de começar pode ser uma economia de tempo sobre onde dedicar energias nesta documentação.
Ambientes suportados
O World Locking Tools for Unity atualmente tem como alvo aplicativos UWP para a família de dispositivos HoloLens. Tanto o HoloLens original (x86) como o HoloLens 2 (ARM64) são suportados.
O suporte experimental para outras plataformas está disponível através dos subsistemas de RA da Unity.
A compilação de integração contínua (CI) do World Locking Tools valida com Unity2018.4.6f1 com Visual Studio 2017. No entanto, o desenvolvimento extensivo do WLT também foi feito usando a gama de versões Unity2018 e uma gama de Unity2019. O Visual Studio 2017 e o Visual Studio 2019 foram usados no desenvolvimento das ferramentas.
Se você tiver algum problema de compatibilidade com outras versões do Unity e/ou Visual Studio, adoraríamos saber mais sobre isso! A melhor maneira de relatar quaisquer problemas é através do portal de problemas no GitHub.
Antecedentes assumidos
Supõe-se que as pessoas que procuram integrar a solução World Locking Tools em seus projetos já estão familiarizadas com os conceitos básicos de criação e implantação de aplicativos para a família de dispositivos HoloLens. Se não, há algumas ótimas referências no final deste artigo.
As camadas das Ferramentas de Bloqueio Mundial
World Locking Tools é dividido em quatro camadas. Com as setas apontando para a camada dependida, o gráfico de dependência simples tem esta aparência:
As linhas tracejadas indicam dependências opcionais.
Enquanto a camada Exemplos usa o MixedRealityToolkit (MRTK), nenhuma das outras camadas tem dependências externas e a funcionalidade completa está disponível compatível, mas independente do MRTK.
Seguem-se mais notas sobre as dependências das Aplicações.
As camadas podem ser resumidas da seguinte forma:
Plug-in
Uma interface imperativa que permite a comunicação direta com a DLL do mecanismo. Problemas comuns como marshaling de argumentos são realizados aqui, e alguns compondo de várias funções freqüentemente usadas em combinação em diretivas compostas. Ele permanece uma interface C# de baixo nível para a DLL C++ subjacente. A sua utilização direta está disponível, mas não é necessária nem aconselhável.
Principal
O Core é um encapsulamento de todas as etapas necessárias para obter os benefícios do espaço estável bloqueado pelo mundo da World Locking Tools, empacotado em uma interface declarativa. Espera-se que um aplicativo de trabalho seja enviado usando apenas a funcionalidade do Core.
Ferramentas
As ferramentas são, em grande parte, de natureza diagnóstica. As visualizações dos processos das Ferramentas de Bloqueio Mundial estão incluídas em formulários fáceis de adicionar a qualquer projeto que utilize as Ferramentas de Bloqueio Mundial.
Outros utilitários convenientes estão incluídos, mas espera-se que sejam úteis para começar a codificar soluções personalizadas, em vez de serem soluções finais como o Core oferece.
Exemplos
A camada Exemplos tenta apresentar exemplos de configuração de cenários comuns ao usar as Ferramentas de Bloqueio Mundial e as práticas recomendadas na integração das Ferramentas de Bloqueio Mundial em vários cenários.
Quaisquer dependências MRTK necessárias para UX e manipulação de objetos são restritas aos scripts e pré-fabricados na camada Exemplos. Isso deixa as camadas inferiores livres de quaisquer dependências externas.
Não se espera que scripts e ativos na camada Exemplos sejam integrados diretamente aos produtos de envio, embora não haja proibição contra isso. Pelo contrário, a sua construção privilegia a simplicidade e a clareza em detrimento da reutilização e eficiência.
A Aplicação
Em geral, o aplicativo precisará ter apenas uma dependência do World Locking Tools Core.
Durante o desenvolvimento, muitas visualizações e outros auxiliares para entender o comportamento inesperado estão disponíveis na camada Ferramentas. O ideal seria que esses auxiliares fossem retirados de um aplicativo concluído ou, pelo menos, desativados. Claro, eles são livres para outros usos também, seja em sua forma atual ou modificado. Consulte a licença para obter detalhes.
Para uso avançado e experimentação de todos os recursos do World Locking Tools, a camada de plug-in oferece acesso imperativo de baixo nível à DLL do mecanismo.
Se o acesso à camada Plugin se tornar necessário, isso pode apontar para uma deficiência na superfície da API oferecida na camada Core. A equipe da World Locking Tools está sempre procurando preencher essas lacunas. Considere contribuir com esses insights para a equipe. Veja contribuindo.
Uma nota de aviso sobre o comprimento do caminho de instalação
Algumas versões do MRTK têm um problema com caminhos de instalação longos. O comprimento total do caminho das subpastas profundas na instalação do MRTK pode exceder o limite de caminho do Windows (260 caracteres). Se aparecer um erro de compilação do seguinte formulário:
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"
mas o arquivo está realmente lá na unidade, então o problema é provavelmente o comprimento do caminho. A equipe do MRTK está ciente disso e está trabalhando para melhorá-lo (nota: acredito que eles fizeram grandes melhorias aqui e isso não é mais um problema). Enquanto isso, a solução alternativa é encurtar o prefixo do caminho por uma combinação do seguinte:
- Instale o projeto Unity em uma raiz de caminho de comprimento mais curto, por exemplo, "D:\Proj"
- Se clonar o repositório, clone a raiz das World Locking Tools em algo mais curto do que o padrão "\MixedReality-WorldLockingTools-Unity", por exemplo:
git clone https://github.com/microsoft/MixedReality-WorldLockingTools-Unity.git d:\MyGit\wlt
Esse limite de caminho geralmente não é um problema com as Ferramentas de Bloqueio Mundial em si, pois elas não utilizam uma estrutura de pastas tão profunda.
Adicionando World Locking Tools a um projeto Unity
Nota
A seguir descrevemos a instalação manual de World Locking Tools e dependências. Um processo de instalação muito mais simplificado está disponível através da Mixed Reality Feature Tool. A instalação através da Feature Tool é descrita aqui. Se a Feature Tool instalar o WLT, você poderá ignorar o seguinte e continuar adicionando o WLT à sua cena
O World Locking Tools depende do nuget para instalar o Frozen World Engine subjacente.
Se adicionar World Locking Tools a um projeto existente, é aconselhável começar com um projeto que tenha sido verificado para construir e implantar em um dispositivo HoloLens. Isso ajudará a separar os problemas com a execução de um aplicativo no HoloLens em primeiro lugar, que podem ser complicados, dos problemas com as Ferramentas de Bloqueio Mundial. Em seguida, prossiga para as seções Instalação do FrozenWorld Engine e World Locking Tools Assets abaixo.
Instalação do FrozenWorld Engine
A DLL do Frozen World Engine pode ser obtida do NuGet usando o excelente utilitário NuGet For Unity ou manualmente.
Usando o NuGet For Unity
Certifique-se de que o feed de nuget.org está nas fontes. Verifique isso em Unity > Edit > Preferences > NuGet for Unity. Em caso negativo:
Use a GUI Add New Source no Unity > Edit > Preferences > NuGet For Unity para adicionar o mesmo compartilhamento.
- Substitua "Nova fonte" por um nome de sua escolha (por exemplo, "NuGet").
- Substitua "source_path" por "http://www.nuget.org/api/v2/".
Depois de confirmar o feed de nuget.org, em Unity > NuGet > Manage NuGet Packages, encontre e instale a versão mais recente do Microsoft.MixedReality.FrozenWorld.Engine. (Procure por "FrozenWorld".)
Para atualizar para uma versão posterior, abra o Unity > NuGet > Manage NuGet Packages novamente e localize o pacote FrozenWorld.Engine e selecione Atualizar. Nota: Poderá ter de aceder ao separador Atualizações para encontrar a versão que procura.
Instalação manual da DLL do Frozen World Engine
Use um editor de texto para adicionar uma packageSources linha a Assets/NuGet.config, por exemplo:
<packageSources>
<add key="NuGet" value="http://www.nuget.org/api/v2/" />
</packageSources>
Se você ainda não tiver um arquivo Assets/NuGet.config, poderá copiá-lo do repositório github das Ferramentas de Bloqueio Mundial.
Usando um editor de texto, adicione o pacote DLL do Frozen World Engine a Assets/packages.config, por exemplo:
<?xml version="1.0" encoding="utf-8"?>
<packages>
<package id="Microsoft.MixedReality.Unity.FrozenWorld.Engine" version="1.0.0" />
</packages>
Novamente, se você ainda não tiver um arquivo Assets/packages.config, você pode obter o arquivo do repositório github World Locking Tools ou simplesmente copiar o acima em um arquivo de texto chamado "Assets/packages.config".
Tendo configurado NuGet.config e packages.config, instale por:
- Obtenha os nuget.exe mais recentes dos downloads do NuGet.
- Certifique-se de que nuget.exe está no seu caminho (aqui vou assumir que foi copiado para o Assets).
- Abra uma janela de comando do PowerShell e altere o diretório para a pasta Ativos.
- Execute o seguinte comando:
.\nuget.exe restore
Para atualizar para uma versão posterior:
- Atualize o número da versão do FrozenWorld.Engine no arquivo packages.config acima para a versão desejada (por exemplo, version="1.0.0" torna-se version="1.0.1").
- Exclua qualquer coisa na pasta Ativos/Pacotes começando com "Microsoft.MixedReality.Unity.FrozenWorld.Engine".
- Execute novamente nuget.exe como acima.
World Locking Tools Ativos
Importe os arquivos necessários do World Locking Tools .unitypackage para o projeto (método preferencial) ou copie-os. Eles podem ser movidos para uma subpasta dentro do Assets para tirá-los do caminho para o desenvolvimento de aplicativos.
Os arquivos estáveis .unitypackage mais recentes podem ser encontrados em World Locking Tools for Unity Releases.
A camada WorldLocking.Core e Engine será definitivamente necessária, então um pacote de instalação mínimo seria WorldLockingCoreEngine.unitypackage.
Para determinar quais outras camadas podem ser necessárias, consulte a discussão sobre as camadas das Ferramentas de Bloqueio Mundial e suas dependências acima. Cada camada está contida em um único pacote Unity.
Como alguns dos Exemplos de Ferramentas de Bloqueio Mundial usam recursos do MRTK, um instantâneo MRTK compatível está incluído nos Exemplos unitypackage. Para obter a versão mais recente do MRTK, veja aqui.
Adicionando ferramentas de bloqueio mundial a uma cena Unity
Nota
As etapas listadas abaixo são todas automatizadas no utilitário de cena WLT Configure, que pode ser encontrado no menu Mixed Reality Toolkit > Utilities > World Locking Tools.
Dentro de um projeto Unity contendo o mecanismo FrozenWorld (de nuget.org), importe todas as camadas desejadas de World Locking Tools Assets (mas pelo menos WorldLocking.Core) e, opcionalmente, MRTK. Em seguida, crie uma nova cena (ou abra uma cena existente).
Nota
Adicione um nó extra na raiz da hierarquia da câmera. Este nó será usado para ajustar a câmera de cabeça rastreada em espaço bloqueado mundial. (Se usar MRTK, este novo GameObject seria o pai do MixedRealityPlayspace.)
A experiência principal
Arraste um pré-fabricado WorldLockingManager de Assets/WorldLocking.Core/Prefabs para sua cena. Seu lugar na cena não importa, mas não deve ser na árvore da câmera. Veja uma cena de exemplo para obter uma configuração sugerida.
Há configurações disponíveis no pré-fabricado WorldLockingManager, mas é recomendável deixá-las com seus valores padrão para começar.
Consulte World Locking Tools Context para obter explicações sobre as opções apresentadas.
[Opcional] MRTK
O World Locking Tools é complementar, mas ortogonal ao MRTK. O uso de MRTK juntamente com World Locking Tools é totalmente opcional.
Dito isto, as amostras do World Locking Tools são construídas usando MRTK, e o MRTK é geralmente extremamente valioso no desenvolvimento dos tipos de aplicativos de MR que mais se beneficiam do World Locking Tools.
Se estiver usando MRTK, em vez de usar o instantâneo incluído com os exemplos, é recomendável adicionar as versões mais recentes de pelo menos os seguintes pacotes:
- Kit de ferramentas MixedReality.Toolkit
- MixedReality.Toolkit.Providers
- MixedReality.Toolkit.Services
- MixedReality.Toolkit.SDK
[Opcional] Visualização de âncoras esponjosas e bloqueadas pelo mundo
Isso requer a adição de WorldLocking.Tools aos ativos do projeto.
Se você quiser visualizar suas âncoras, arraste o pré-fabricado AnchorGraphVisual de Assets/WorldLocking.Tools/Prefabs para sua cena. As caixas de seleção para alternar aspetos da visualização no inspetor estão no WorldLockingManager.
Como diagnóstico, as visualizações do WorldLocking.Tools não são altamente otimizadas e reduzirão o desempenho muito antes que o tempo de processamento das Ferramentas de Bloqueio Mundial principal se torne relevante.
[Opcional] Um painel simples para controle de parâmetros dentro da Realidade Mista
Um HUD simples está disponível, que pode ser usado para controlar o WorldLockingManager em tempo de execução de dentro do MR. Estes são fornecidos no pacote de exemplos. Embora possam ser usados como estão, eles são destinados como padrões ao construir recursos semelhantes em um sistema de exibição próprio de aplicativos e UX.
Arraste o pré-fabricado WorldLocking.Examples/Prefabs/Dashboard e aponte seu campo Visualizador de Âncora para o Visualizador na seção anterior.
Migrando uma cena existente para as Ferramentas de Bloqueio Mundial
A maior mudança ao mudar para World Locking Tools é que não há mais um requisito para o uso de âncoras espaciais para objetos virtuais de bloqueio mundial.
As âncoras espaciais têm sido tradicionalmente a única ferramenta disponível para bloquear objetos individuais. Mas ao usar as Ferramentas de Bloqueio Mundial, o espaço de coordenadas em que esses objetos virtuais existem já está bloqueado no mundo. Não é necessário mais bloqueio.
As âncoras espaciais não só são desnecessárias, como também não funcionam corretamente, pois não levam em conta transformações adicionais na hierarquia da câmera (como a transformação MRTK "Playspace").
Portanto, toda e qualquer âncora espacial deve ser removida da cena, e qualquer script que adicione âncoras espaciais deve interromper isso. As âncoras espaciais não precisam ser substituídas por nada; A World Locking Tools irá ancorar os seus alvos no mundo real.
Se for desejável comparar o bloqueio do mundo com e sem World Locking Tools, em vez de remover WorldAnchors, eles podem ser substituídos pelo ToggleWorldAnchor fornecido em WorldLocking.Tools.
ToggleWorldAnchor funciona exatamente da mesma forma que um WorldAnchor, com a importante diferença de que, quando o World Locking Tools Manager está ativo, ele convenientemente se desativa e sai do caminho. Quando o World Locking Tools Manager está desativado, ele se comporta como um WorldAnchor normal.
Se, por algum outro motivo, WorldAnchors ainda forem necessários na cena (por exemplo, para compartilhamento de rede), eles podem ser usados com um adaptador, fornecido como WorldAnchorAdapter.
O WorldAnchorAdapter transforma a posição bruta de um GameObject posicionado por um WorldAnchor no espaço global Unity bloqueado pelo mundo e, em seguida, aplica a transformação a um objeto de destino. Para usá-lo, em vez de adicionar um WorldAnchor diretamente a um objeto, o WorldAnchor deve ser aplicado a um objeto proxy (geralmente um GameObject vazio) e, em seguida, em Update() o WorldAnchorAdapter lê a pose do WorldAnchor, transforma-o corretamente e aplica-o ao destino.
Configuração concluída
Tendo seguido as etapas acima, o projeto implantado no dispositivo será executado ajustado pela World Locking Tools para manter um espaço bloqueado pelo mundo idealmente estável. Quaisquer objetos fixos colocados na cena permanecerão visualmente consistentes tanto em relação uns aos outros quanto com o mundo físico.
Exemplos de aplicações disponíveis
Cenas de exemplo, incluindo scripts e ativos, são fornecidas para demonstrar o uso mais complexo dos recursos do World Locking Tools.
Por exemplo, o WorldLockedPhysicsSample fornece um ambiente simples no qual objetos fisicamente simulados podem ser criados e removidos, interagindo uns com os outros e com o ambiente (o mapeamento espacial).
Para uma visão mais focada do recurso Space Pinning, o SpacePin fornece um exemplo muito simplificado de alinhamento de um objeto virtual em grande escala com recursos do mundo real.
O RayPins expande as capacidades introduzidas pelo exemplo SpacePin, permitindo fixar o mundo virtual ao mundo físico com testes de raios contra a malha espacial.
Referências para começar
Se não estiver familiarizado com os conceitos básicos de criação, criação e implantação de aplicativos de RA na família de dispositivos HoloLens, aqui estão algumas referências que podem ajudar a começar.
Visão geral do desenvolvimento da unidade - Unidade para o desenvolvimento de MR/RA.
MR Basics 100 - Passo a passo como começar a desenvolver para HoloLens
Tutoriais do HoloLens 2 - Passo a passo para começar a desenvolver para o HoloLens 2.
Sistemas de Coordenação Coordene as implicações espaciais no desenvolvimento de RA.
- Observe que as Ferramentas de Bloqueio Mundial resolvem os problemas discutidos aqui.
Está com problemas?
Consulte o guia de solução de problemas.