Configuração inicial do World Locking Tools

Configuração mais simples possível

Este tutorial demonstra a configuração mínima para colocar seu aplicativo totalmente bloqueado em funcionamento, sem a necessidade de qualquer ação adicional (por exemplo, âncoras espaciais). Está no repositório de exemplos semelhante a este repositório.

Guia de início rápido

Uma abordagem menos detalhada do ponto de vista conceitual e mais pragmática para a integração do WLT em um projeto pode ser encontrada aqui. Quando apropriado, ela faz referência a essas páginas mais completas. Embora a decisão da abordagem mais apropriada seja uma questão de preferência, uma leitura rápida da página Antes de começar pode ajudar a economizar tempo indicando o que é mais importante nessa documentação.

Ambientes compatíveis

O World Locking Tools para Unity atualmente foca em aplicativos da UWP para a família de HoloLens de dispositivos. Há suporte para o HoloLens original (x86) e para o HoloLens 2 (ARM64).

O suporte experimental para outras plataformas está disponível pelos Subsistemas AR do Unity.

A compilação de CI (integração contínua) do World Locking Tools é validada com o Unity2018.4.6f1 com o Visual Studio 2017. No entanto, o amplo desenvolvimento do WLT também foi feito usando a gama de versões do Unity2018 e uma variedade de Unity2019. Tanto o Visual Studio 2017 quanto o Visual Studio 2019 foram usados no desenvolvimento das ferramentas.

Nos informe caso você enfrente problemas de compatibilidade com outras versões do Unity e/ou Visual Studio. A melhor forma de relatar problemas é através do portal de problemas no GitHub.

Tela de fundo implícita

Supõe-se que as pessoas que buscam integrar a solução do World Locking Tools em seus projetos já estejam familiarizadas com os fundamentos de criação e implantação de aplicativos para a família de dispositivos HoloLens. Caso contrário, algumas referências podem ser encontradas no final deste artigo.

As camadas do World Locking Tools

O World Locking Tools é dividido em quatro camadas. Com as setas apontando para a camada dependente, o grafo de dependência direto tem a seguinte aparência:

As linhas tracejadas indicam dependências opcionais.

Embora a camada de Exemplos use o MRTK (MixedRealityToolkit), as outras camadas não possuem quaisquer dependências externas, e a funcionalidade completa está disponível, sendo compatível mas independente do MRTK.

Anotações adicionais sobre as dependências de Aplicativos podem ser encontradas abaixo.

As camadas podem ser resumidas da seguinte maneira:

Plug-in

Uma interface imperativa que permite a comunicação direta com a DLL do mecanismo. Problemas comuns, como o marshaling de argumento, são resolvidos aqui, bem como uma composição de várias funções frequentemente usadas de forma conjunta em diretivas de composição. Ele continua sendo uma interface C# de nível baixo para a DLL do C++ subjacente. Seu uso direto está disponível, mas não é necessário nem aconselhado.

Core

O Core é um encapsulamento de todas as etapas necessárias para obter os benefícios do espaço de bloqueio estável do World Locking Tool, empacotado em uma interface declarativa. Espera-se que um aplicativo funcional seja enviado usando apenas a funcionalidade do Core.

Ferramentas

As Ferramentas são, em grande parte, diagnósticos por natureza. As visualizações de processos do World Locking Tools estão incluídas em formulários que podem ser facilmente adicionados a qualquer projeto que use o World Locking Tools.

Outros utilitários convenientes estão incluídos, mas devem ser úteis na introdução à codificação de soluções personalizadas, e não como soluções finais como as ofertas do Core.

Exemplos

A camada de Exemplos tenta apresentar exemplos de configuração de cenários comuns ao usar o World Locking Tools e as práticas recomendadas na integração do World Locking Tools em vários cenários.

Todas as dependências de MRTK necessárias para UX e manipulação de objeto são restritas aos scripts e pré-fabricadas na camada de Exemplos. Isso deixa as camadas inferiores livres de dependências externas.

Não se espera que os scripts e ativos na camada de Exemplos sejam integrados diretamente aos produtos de remessa, embora isso não seja proibido. Em vez disso, sua construção favorece a simplicidade e a clareza em relação à capacidade de reutilização e eficiência.

O aplicativo

Em geral, o Aplicativo precisará de 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 de Ferramentas. Esses auxiliares, teoricamente, seriam extraídos de um aplicativo concluído ou, pelo menos, desabilitado. Obviamente, eles também são gratuitos para outros usos, seja na forma atual ou modificada. Consulte a licença para obter mais detalhes.

Para uso avançado e experimento de todos os recursos completos do World Locking Tools, a camada de Plug-in oferece acesso imperativo de baixo nível à DLL do mecanismo.

Se o acesso à camada de Plug-in for necessário, uma deficiência poderá ser indicada na superfície de API oferecida na camada Core. A equipe do World Locking Tools sempre pretende preencher essas lacunas. Considere fornecer essas informações à equipe. Confira contribuição.

Aviso sobre o comprimento do caminho de instalação

Algumas versões do MRTK apresentam problemas com caminhos de instalação longos. O comprimento do caminho completo de subpastas com nomes extensos na instalação do MRTK pode exceder o limite do Windows (260 caracteres). Se o seguinte erro de compilação for exibido:

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 estiver na unidade, em seguida, o problema provavelmente está no comprimento do caminho. A equipe do MRTK está ciente disso e está trabalhando para corrigir o problema (Observação: acredito que eles tenham feito grandes melhorias e isso não seja mais um problema). Enquanto isso, a solução alternativa é reduzir o prefixo de caminho através de uma combinação do seguinte:

1. Instale o projeto do Unity em uma raiz do caminho de comprimento mais curto, por exemplo, "D:\Proj"
2. Se estiver clonando o repositório, clone a raiz do World Locking Tools em algo menor 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 não costuma ser um problema no World Locking Tools, pois ele não utiliza uma estrutura de pastas com nomes tão extensos.

Como adicionar o World Locking Tools a um projeto do Unity

Observação

As informações a seguir descrevem a instalação manual do World Locking Tools e das dependência. Um processo de instalação muito mais simplificado está disponível na Ferramenta de Recursos de Realidade Misturada. A instalação através da Ferramenta de Recursos está descrita aqui. Se a Ferramenta de Recursos instalar o WLT, ignore o seguinte e avance para como adicionar o WLT à sua cena

O World Locking Tools se baseia no NuGet para instalar o Frozen World Engine subjacente.

Para adicionar o World Locking Tools a um projeto existente, é aconselhável iniciar com um projeto que crie e implante em um dispositivo HoloLens. Isso ajudará a separar os problemas na execução de um aplicativo no HoloLens, o que pode ser complicado, dos problemas com o World Locking Tools. Em seguida, prossiga para as seções de instalação do FrozenWorld Engine e Ativos do World Locking Tools abaixo.

Instalação do FrozenWorld Engine

A DLL do Frozen World Engine pode ser obtida do NuGet usando o utilitário NuGet para Unity ou manualmente.

Como usar o NuGet para Unity

Certifique-se de que o feed nuget.org esteja em origens. Isso pode ser verificado em Unity > Editar > Preferências > NuGet para Unity. Caso não esteja, tente o seguinte:

Use Adicionar nova origem GUI no Unity > Editar > Preferências > NuGet para Unity para adicionar o mesmo compartilhamento.

• Substitua "Nova origem" pelo nome de sua escolha (por exemplo, "NuGet").
• Substitua "source_path" por "http://www.nuget.org/api/v2/".

Após confirmar o feed nuget.org, em Unity > NuGet > Gerenciar Pacotes NuGet, localize e instale a versão mais recente de Microsoft.MixedReality.FrozenWorld.Engine. (Pesquise por "FrozenWorld".)

Para atualizar para uma versão mais recente, abra Unity > NuGet > Gerenciar Pacotes NuGet novamente, localize o pacote FrozenWorld.Engine e selecione Atualizar. Observação: pode ser necessário acessar a guia Atualizações para localizar a versão que está procurando.

Instalação manual da DLL Frozen World Engine

Use um editor de texto para adicionar uma linha packageSources 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 de Assets/NuGet.config, é possível copiá-lo do repositório do GitHub do World Locking Tools.

Usando um editor de texto, adicione o pacote de DLL 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 de Assets/packages.config, o arquivo poderá ser obtido do repositório do GitHub do World Locking Tools ou copiando os dados acima para um arquivo de texto denominado "Assets/packages.config".

Após configurar NuGet.config e packages.config, instale:

1. Obtenha o nuget.exe mais recente de downloads do NuGet.
2. Verifique se nuget.exe está no seu caminho (aqui, irei presumir que ele foi copiado em Ativos).
3. Abra uma janela de comando do PowerShell e altere o diretório para a pasta Ativos.
4. Execute o seguinte comando:

.\nuget.exe restore

Para atualizar para uma versão mais recente:

1. Atualize o número da versão do FrozenWorld.Engine no arquivo packages.config acima para a versão desejada (por exemplo, versão="1.0.0" se torna versão="1.0.1").
2. Exclua tod o que estiver na pasta Assets/Packages começando com "Microsoft.MixedReality.Unity.FrozenWorld.Engine".
3. Execute nuget.exe novamente, conforme exibido acima.

Ativos do World Locking Tools

Importe os arquivos .unitypackage necessários do World Locking Tools para o projeto (método preferencial) ou copie-os. Eles podem ser movidos para uma sub-pasta nos Ativos para que o desenvolvimento do aplicativo possa ser feito.

Os arquivos estáveis .unitypackage mais recentes podem ser encontrados em Lançamentos do World Locking Tools para Unity.

As camadas WorldLocking.Core e Engine serão definitivamente necessárias, portanto, um pacote mínimo de instalação seria WorldLockingCoreEngine.unitypackage.

Para determinar quais outras camadas podem ser necessárias, confira a discussão sobre as camadas do World Locking Tools e suas dependências acima. Cada camada está contida em um único pacote do Unity.

Como alguns Exemplos do World Locking Tools usam recursos do MRTK, um instantâneo do MRTK compatível é incluído com os Exemplos unitypackage. Para obter a versão mais recente do MRTK, veja aqui.

Como adicionar o World Locking Tools a uma cena do Unity

Observação

As etapas abaixo são automatizadas no utilitário de cena do WLT Configure, que pode ser encontrado no menu Kit de Ferramentas de Realidade Misturada > Utilitários > World Locking Tools.

Em um projeto do Unity que contém o mecanismo FrozenWorld (do nuget.org), importe as camadas desejadas de Ativos do World Locking Tools (mas pelo menos WorldLocking.Core) e, opcionalmente, o MRTK. Em seguida, crie uma nova cena (ou abra uma cena existente).

Observação

Adicione um nó extra na raiz da hierarquia da câmera. Esse nó será usado para ajustar a câmera de rastreamento de cabeça no espaço bloqueado. (Se estiver usando o MRTK, esse novo GameObject sera o pai do MixedRealityPlayspace.)

A experiência Core

Arraste um WorldLockingManager pré-fabricado de Assets/WorldLocking.Core/Prefabs para sua cena. Sua posição na cena é indiferente, mas não deve estar na árvore da câmera. Consulte uma cena de exemplo para ver uma configuração sugerida.

Há configurações disponíveis no WorldLockingManager pré-fabricado, mas é recomendável deixá-las com seus valores padrão para começar.

Confira Contexto do World Locking Tools para saber mais sobre as opções apresentadas.

[Opcional] MRTK

O World Locking Tools é complementar, mas ortogonal ao MRTK. O uso do MRTK junto com o World Locking Tools é totalmente opcional.

Dito isso, os exemplos do World Locking Tools são desenvolvidos usando o MRTK e o MRTK costuma ser muito valioso no desenvolvimento dos tipos de aplicativos de MR que mais se beneficiam do World Locking Tools.

Se estiver usando o MRTK, em vez de usar o instantâneo incluído nos exemplos, é recomendável adicionar as versões mais recentes pelo menos dos seguintes pacotes:

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

[Opcional] Como visualizar âncoras esponjosas e bloqueadas

Isso requer a inclusão de WorldLocking.Tools aos Ativos do projeto.

Para visualizar suas âncoras, arraste o AnchorGraphVisual pré-fabricado de Assets/WorldLocking.Tools/Prefabs para sua cena. Marque as caixas para alternar os aspectos da visualização no inspetor para WorldLockingManager.

Como diagnóstico, as visualizações do WorldLocking.Tools não são altamente otimizadas e reduzirão o desempenho muito antes do tempo de processamento principal do World Locking Tools se tornar relevante.

[Opcional] Um painel simples para controle de parâmetros da Realidade Misturada

Um HUD simples está disponível e pode ser usado para controlar o WorldLockingManager no runtime de dentro do MR. Ele é fornecido no pacote Exemplos. Embora possam ser usados no estado em que se encontram, eles se destinam a ser padrões ao criar recursos semelhantes em um sistema de exibição e UX próprios de aplicativos.

Arraste o WorldLocking.Examples/Prefabs/Dashboard pré-fabricado e aponte seu campo Visualizador de Âncora para o Visualizador na seção anterior.

Como migrar uma cena existente para o World Locking Tools

A maior alteração ao mudar para o World Locking Tools é que não há mais um requisito para usar as âncoras espaciais para objetos virtuais de bloqueio.

As âncoras espaciais são tradicionalmente a única ferramenta disponível para objetos individuais de bloqueio. Mas, ao usar o World Locking Tools, o espaço de coordenadas no qual esses objetos virtuais existem já está bloqueado. Nenhum bloqueio adicional é necessário.

Além de serem desnecessárias, as âncoras espaciais não funcionarão corretamente, pois elas falham ao considerar as transformações adicionais na hierarquia da câmera (como a transformação "Playspace" do MRTK).

Portanto, todas as âncoras espaciais devem ser removidas da cena e todos os scripts que adicionam âncoras espaciais não devem mais fazer isso. As âncoras espaciais não precisam ser substituídas; O World Locking Tools ancora seus destinos para o mundo real.

Se for desejável comparar o bloqueio com e sem o World Locking Tools, em vez de remover WorldAnchors, substitua pelo ToggleWorldAnchor fornecido em WorldLocking.Tools.

ToggleWorldAnchor funciona exatamente da mesma forma que um WorldAnchor. A diferença é que, quando o World Locking Tools Manager estiver ativo, ele é desabilitado de forma conveniente. Quando o World Locking Tools Manager estiver desabilitado, ele se comportará como um WorldAnchor normal.

Se, por algum outro motivo, o WorldAnchors ainda for necessário na cena (por exemplo, para compartilhamento de rede), ele poderá ser usado com um adaptador, fornecido como WorldAnchorAdapter.

O WorldAnchorAdapter transforma a posição bruta de um GameObject posicionado por um WorldAnchor no espaço global do Unity bloqueado e, em seguida, aplica a transformação em 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 Update(), o WorldAnchorAdapter lê a pose do WorldAnchor, o transforma corretamente e aplica ao destino.

Configuração concluída

Após seguir as etapas acima, o projeto implantado no dispositivo será executado, ajustado pelo World Locking Tools para manter um espaço estável e bloqueado de forma ideal. Todos os objetos fixos posicionados na cena permanecerão visualmente consistentes entre si e em relação ao mundo físico.

Aplicativos de exemplo disponíveis

Cenas de exemplo, incluindo scripts e ativos, são fornecidas para demonstrar o uso mais complexo das funcionalidades do World Locking Tools.

Por exemplo, o WorldLockedPhysicsSample fornece um ambiente simples no qual objetos fisicamente simulados podem ser criados e removidos, interagindo entre si e com o ambiente (mapeamento espacial).

Para obter uma análise mais focada do recurso de Anexação de Espaço, o SpacePin fornece um exemplo muito simplificado de alinhamento de um objeto virtual em grande escala aos recursos do mundo real.

O RayPins expande os recursos introduzidos pelo exemplo do SpacePin, permitindo a anexação do mundo virtual ao mundo físico com testes de raio em relação à malha espacial.

Referências para começar

Se não estiver familiarizado com as noções básicas de criação, compilação e implantação de aplicativos AR na família de dispositivos HoloLens, veja abaixo algumas referências para você começar.

Visão geral de desenvolvimento do Unity – Unity para desenvolvimento de MR/AR.

Noções básicas do MR 100 – Passo a passo introdutório para desenvolvimento no HoloLens

Tutoriais do HoloLens 2 – Passo a passo introdutório para desenvolvimento no HoloLens 2.

Sistemas de coordenadas Implicações de espaço de coordenadas no desenvolvimento de AR.

• Observe que o World Locking Tools resolve os problemas discutidos aqui.

Está tendo problemas?

Consulte o guia de solução de problemas.