Configuración inicial de World Locking Tools

  • Artículo

Configuración más sencilla posible

Este tutorial muestra cómo realizar la configuración mínima para empezar a trabajar con todo lo que hay en una aplicación bloqueada en el mundo, sin necesidad de realizar ninguna otra acción (por ejemplo, poner anclajes espaciales). Se encuentra en el repositorio de ejemplos que está en el mismo nivel que este repositorio.

Guía de inicio rápido

Aquí encontrará un enfoque menos detallado conceptualmente y más pragmático para integrar WLT en un proyecto. Cuando es necesario, hace referencia a estas páginas más exhaustivas. Aunque decir qué enfoque es el más adecuado es realmente una cuestión de preferencias personales, una lectura rápida de la página Antes de empezar puede ayudar a ahorrar tiempo a la hora de decidir en qué parte de la documentación invertir energía.

Entornos admitidos

World Locking Tools para Unity está dirigido actualmente a las aplicaciones para UWP para la familia de dispositivos HoloLens. Se admiten los modelos HoloLens original (x86) y HoloLens 2 (ARM64).

Hay disponible compatibilidad experimental con otras plataformas a través de los subsistemas AR de Unity.

La compilación de integración continua (CI) de World Locking Tools se valida con Unity2018.4.6f1 con Visual Studio 2017. Sin embargo, gran parte del desarrollo de WLT se ha realizado también con el espectro de versiones de Unity2018 y una gama de Unity2019. Tanto Visual Studio 2017 como Visual Studio 2019 se han usado en el desarrollo de las herramientas.

Si experimenta problemas de compatibilidad con otras versiones de Unity y/o Visual Studio, nos gustaría saberlo. La mejor manera de notificar cualquier problema es a través del portal de incidencias en GitHub.

Antecedentes supuestos

Se supone que las personas que buscan integrar la solución World Locking Tools en sus proyectos ya están familiarizadas con los conceptos básicos de la creación e implementación de aplicaciones para la familia de dispositivos HoloLens. Si no es así, al final de este artículo se indican algunos recursos de referencia excelentes.

Capas de World Locking Tools

World Locking Tools está dividido en cuatro capas. Con las flechas apuntando hacia la capa de la que se depende, el gráfico de dependencias sencillo tiene el siguiente aspecto:

Diagrama de capas

Las líneas discontinuas indican dependencias opcionales.

Aunque la capa Examples usa Mixed Reality Toolkit (MRTK), ninguna de las demás capas tiene dependencias externas y la funcionalidad completa está disponible compatible con MRTK, pero independiente de él.

A continuación se indican algunas notas más sobre las dependencias de las aplicaciones.

Las capas se pueden resumir de la siguiente manera:

Complemento

Interfaz imperativa que permite la comunicación directa con el archivo DLL del motor. Aquí se abordan problemas comunes, como la serialización de argumentos, y se componen varias funciones que se usan con frecuencia en combinación con directivas compuestas. Sigue siendo una interfaz de C# de bajo nivel para el archivo DLL de C++ subyacente. Se puede usar directamente, pero no es necesario ni aconsejable.

Core

La capa Core es una encapsulación de todos los pasos necesarios para obtener las ventajas del espacio estable bloqueado en el mundo que proporciona World Locking Tools, empaquetado en una interfaz declarativa. Una aplicación funcional se distribuiría solo con la funcionalidad de la capa Core.

Herramientas

Las herramientas de la capa Tools son en gran medida de diagnóstico por naturaleza. Se incluyen visualizaciones de los procesos de World Locking Tools en formas fáciles de agregar a cualquier proyecto que use World Locking Tools.

También se incluyen otras utilidades prácticas, pero están pensadas como ayuda para empezar a programar soluciones personalizadas, en lugar de ser soluciones finales como las que ofrece la capa Core.

Ejemplos

La capa Examples intenta mostrar ejemplos de configuración de escenarios comunes cuando se usa World Locking Tools, así como procedimientos recomendados para la integración de World Locking Tools en varios escenarios.

Las dependencias de MRTK necesarias para la experiencia del usuario y la manipulación de objetos están restringidas a los scripts y objetos prefabricados de la capa Examples. Esto deja las capas inferiores libres de dependencias externas.

No está previsto que los scripts y recursos de la capa Examples se integren directamente en los productos que se distribuyen, aunque no hay ninguna prohibición al respecto. Más bien, su construcción favorece la simplicidad y la claridad en torno a la reusabilidad y la eficacia.

La aplicación

En general, la aplicación solo necesitará una dependencia de la capa Core de World Locking Tools.

Durante el desarrollo, en la capa Tools hay disponibles muchas visualizaciones y otras aplicaciones auxiliares para comprender el comportamiento inesperado. Lo ideal es que estas aplicaciones auxiliares se quiten, o al menos se deshabiliten, en una aplicación final. Por supuesto, son gratuitas para otros usos también, ya sea en su forma actual o modificadas. Consulte la licencia para obtener más información.

Para un uso avanzado y la experimentación de la funcionalidad completa de World Locking Tools, la capa Plugin ofrece acceso imperativo de bajo nivel al archivo DLL del motor.

Si es necesario acceder a la capa Plugin, puede indicar una deficiencia en la superficie de la API que se ofrece en la capa Core. El equipo de World Locking Tools siempre busca cerrar esas brechas. Considere la posibilidad de aportar esta información al equipo. Vea Contribución.

Una nota de advertencia sobre la longitud de la ruta de instalación

Algunas versiones de MRTK tienen un problema con las rutas de instalación largas. La longitud de la ruta de acceso completa de las subcarpetas profundas en la instalación de MRTK puede superar el límite de Windows para rutas de acceso (260 caracteres). Si aparece un error de compilación como el siguiente:

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"

pero el archivo está realmente en la unidad, es probable que el problema se deba a la longitud de la ruta de acceso. El equipo de MRTK es consciente de esto y está trabajando para mejorarlo. Nota: Creo que han conseguido grandes mejoras en esto y ya no es un problema. Mientras tanto, la solución alternativa consiste en acortar el prefijo de la ruta de acceso mediante una combinación de lo siguiente:

  1. Instalar el proyecto de Unity en la raíz de una ruta de acceso más corta, por ejemplo, "D:\Proj".
  2. Si se clona el repositorio, clonar la raíz de World Locking Tools en una ruta más corta que el valor predeterminado "\MixedReality-WorldLockingTools-Unity", por ejemplo:
git clone https://github.com/microsoft/MixedReality-WorldLockingTools-Unity.git d:\MyGit\wlt

Este límite de la ruta de acceso no suele ser un problema con el propio World Locking Tools, ya que no usa una estructura de carpetas tan profunda.

Adición de World Locking Tools a un proyecto de Unity

Nota

A continuación, se explica la instalación manual de World Locking Tools y las dependencias. Hay disponible un proceso de instalación mucho más simplificado a través de la herramienta de características de Mixed Reality. La instalación a través de esta herramienta se describe aquí. Si la herramienta de características instala WLT, puede omitir lo siguiente y continuar en Adición de World Locking Tools a una escena de Unity.

World Locking Tools se basa en NuGet para instalar el motor Frozen World Engine subyacente.

Si agrega World Locking Tools a un proyecto que ya existe, es aconsejable empezar con un proyecto que se haya comprobado que se compila e implementa en un dispositivo HoloLens. Esto ayudará a separar primero los problemas relacionados con la ejecución de una aplicación en HoloLens, que puede ser complicado, de los problemas con World Locking Tools. Después, continúe en las secciones Instalación de Frozen World Engine y Recursos de World Locking Tools.

Instalación de Frozen World Engine

El archivo DLL de Frozen World Engine se puede obtener de NuGet, ya sea con la excelente utilidad NuGet For Unity o manualmente.

Uso de NuGet for Unity

Asegúrese de que la fuente nuget.org está en los orígenes. Para comprobarlo, vaya a Unity > Edit (Editar) > Preferences (Preferencias) > NuGet for Unity. Si no está, realice una de las siguientes acciones:

Use la GUI Add New Source (Agregar nuevo origen) en Unity > Edit (Editar) > Preferences (Preferencias) > NuGet for Unity, para agregar el mismo recurso compartido.

  • Reemplace "New Source" por el nombre que prefiera (por ejemplo, "NuGet").
  • Reemplace "source_path" por "http://www.nuget.org/api/v2/".

Después de confirmar la fuente nuget.org, en Unity > NuGet > Manage NuGet Packages (Administrar paquetes de NuGet), busque e instale la versión más reciente de Microsoft.MixedReality.FrozenWorld.Engine. Busque "FrozenWorld".

Para actualizar a una versión posterior, vuelva a abrir Unity > NuGet > Manage NuGet Packages (Administrar paquetes de NuGet), busque el paquete FrozenWorld.Engine y seleccione Update (Actualizar). Nota: Es posible que tenga que ir a la pestaña Updates (Actualizaciones) para encontrar la versión que está buscando.

Instalación manual del archivo DLL de Frozen World Engine

Use un editor de texto para agregar la línea packageSources al archivo Assets/NuGet.config, por ejemplo:

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

Si aún no tiene un archivo Assets/NuGet.config, puede copiarlo del repositorio de World Locking Tools en GitHub.

En un editor de texto, agregue el paquete DLL Frozen World Engine al archivo Assets/packages.config, por ejemplo:

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

De nuevo, si aún no tiene un archivo Assets/packages.config, puede obtenerlo del repositorio de World Locking Tools en GitHub, o bien simplemente puede copiar lo anterior en un archivo de texto denominado "Assets/packages.config".

Una vez que tenga los archivos NuGet.config y packages.config, lleve a cabo la instalación como se indica a continuación:

  1. Obtenga la versión más reciente de nuget.exe de las descargas de NuGet.
  2. Asegúrese de que nuget.exe está en la ruta de acceso (aquí daré por supuesto que se copió en Assets).
  3. Abra una ventana de comandos de PowerShell y cambie el directorio a la carpeta Assets.
  4. Ejecute el siguiente comando:
.\nuget.exe restore

Para actualizar a una versión posterior:

  1. Actualice el número de versión de FrozenWorld.Engine del archivo packages.config anterior a la versión deseada (por ejemplo, version="1.0.0" pasa a ser version="1.0.1").
  2. Elimine cualquier cosa de la carpeta Assets/Packages que empiece por "Microsoft.MixedReality.Unity.FrozenWorld.Engine".
  3. Vuelva a ejecutar nuget.exe como antes.

Recursos de World Locking Tools

Importe los archivos .unitypackage de World Locking Tools necesarios en el proyecto (método de preferencia) o cópielos. Se pueden mover a una subcarpeta dentro de Assets para que no molesten en el desarrollo de aplicaciones.

Los archivos .unitypackage estables más recientes se pueden encontrar en World Locking Tools para Unity.

Las capas WorldLocking.Core y Engine serán definitivamente necesarias, por lo que un paquete de instalación mínimo sería WorldLockingCoreEngine.unitypackage.

Para determinar qué otras capas podrían ser necesarias, consulte la explicación de las capas de World Locking Tools y sus dependencias más arriba. Cada capa está contenida en un único paquete de Unity.

Dado que algunos de los ejemplos de World Locking Tools usan características de MRTK, se incluye una instantánea de MRTK compatible en el unitypackage Examples. Aquí puede obtener la versión más reciente de MRTK.

Adición de World Locking Tools a una escena de Unity

Nota

Los pasos que se indican a continuación están automatizados en la utilidad de configuración de escenas de WLT, que se encuentra en el menú Mixed Reality Toolkit > Utilities (Utilidades) > World Locking Tools. Menú Configuración

En un proyecto de Unity que contenga Frozen World Engine (de nuget.org), importe las capas de recursos de World Locking Tools que desee (al menos WorldLocking.Core) y, opcionalmente, MRTK. A continuación, cree una escena nueva o abra una que ya esté creada.

Nota

Agregue un nodo adicional en la raíz de la jerarquía de la cámara. Este nodo se usará para ajustar la cámara con el seguimiento de la cabeza en un espacio bloqueado en el mundo. Si usa MRTK, este nuevo GameObject sería el elemento primario de MixedRealityPlayspace.

La experiencia Core

Arrastre un objeto prefabricado WorldLockingManager de Assets/WorldLocking.Core/Prefabs a la escena. Su lugar en la escena no importa, pero no debe estar en el árbol de la cámara. Consulte una escena de ejemplo para ver una sugerencia de configuración.

Hay opciones disponibles en el objeto prefabricado WorldLockingManager, pero se recomienda dejarlas con los valores predeterminados para empezar.

Vea Contexto de World Locking Tools para obtener una explicación de las opciones disponibles.

[Opcional] MRTK

World Locking Tools es complementario, pero independiente de MRTK. El uso de MRTK junto con World Locking Tools es totalmente opcional.

Dicho esto, los ejemplos de World Locking Tools se han creado con MRTK, que suele ser muy útil para desarrollar los tipos de aplicaciones de MR que más se benefician de World Locking Tools.

Si usa MRTK, en lugar de usar la instantánea que se incluye con los ejemplos, se recomienda agregar las versiones más recientes de, al menos, los siguientes paquetes:

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

[Opcional] Visualización de anclajes elásticos y bloqueados en el mundo

Esto requiere agregar WorldLocking.Tools a los recursos del proyecto.

Si desea visualizar los anclajes, arrastre el objeto prefabricado AnchorGraphVisual de Assets/WorldLocking.Tools/Prefabs a la escena. Las casillas para alternar aspectos de la visualización en el inspector se encuentran en WorldLockingManager.

Como diagnóstico, las visualizaciones de WorldLocking.Tools no están muy optimizadas y reducirán el rendimiento mucho antes de que el tiempo de procesamiento de la capa Core de World Locking Tools sea relevante.

[Opcional] Un sencillo panel para el control de los parámetros en Mixed Reality

Hay disponible una sencilla pantalla que se puede usar para controlar WorldLockingManager en tiempo de ejecución desde MR. Se proporciona en el paquete Examples. Aunque estos ejemplos se pueden usar tal cual, están pensados para usarlos como patrones para crear características similares en el propio sistema de visualización y la experiencia de usuario de una aplicación.

Arrastre el objeto prefabricado WorldLocking.Examples/Prefabs/Dashboard y, en su campo Anchor Visualizer (Visualizador de anclajes), indique el visualizador de la sección anterior.

Migración de una escena a World Locking Tools

El cambio más importante al migrar a World Locking Tools es que ya no es necesario usar anclajes espaciales para objetos virtuales bloqueados en el mundo.

Tradicionalmente, los anclajes espaciales han sido la única herramienta disponible para los objetos individuales bloqueados en el mundo. Pero, cuando se usa World Locking Tools, el espacio de coordenadas donde se encuentran esos objetos virtuales ya está bloqueado en el mundo. No se necesita ningún bloqueo más.

Los anclajes espaciales no solo no son necesarios, sino que no funcionarán correctamente, ya que no tienen en cuenta las transformaciones adicionales en niveles superiores de la jerarquía de la cámara (como la transformación "Playspace" de MRTK).

Por tanto, deben quitarse de la escena todos los anclajes espaciales, y los scripts que agreguen anclajes espaciales deben dejar de hacerlo. No es necesario reemplazar los anclajes espaciales por nada; World Locking Tools ancla los destinos al mundo real.

Si es conveniente comparar el bloqueo en el mundo con y sin World Locking Tools, en lugar de quitar los anclajes WorldAnchors, se pueden reemplazar por ToggleWorldAnchor, que se proporciona en WorldLocking.Tools.

ToggleWorldAnchor funciona exactamente igual que un WorldAnchor, con la importante diferencia de que, cuando World Locking Tools Manager está activo, se deshabilita oportunamente y se quita de en medio. Cuando World Locking Tools Manager está deshabilitado, se comporta como un WorldAnchor normal.

Si, por alguna otra razón, se siguen necesitando anclajes WorldAnchor en la escena (por ejemplo, para el uso compartido de la red), se pueden usar con un adaptador, que se proporciona como WorldAnchorAdapter.

WorldAnchorAdapter transforma la posición sin procesar de un GameObject posicionado por un WorldAnchor en el espacio global de Unity bloqueado en el mundo y, a continuación, aplica la transformación a un objeto de destino. Para usarlo, en lugar de agregar un WorldAnchor directamente a un objeto, el WorldAnchor debe aplicarse a un objeto proxy (normalmente, un GameObject vacío) y, después, al ejecutar Update(), WorldAnchorAdapter lee la posición del WorldAnchor, lo transforma correctamente y lo aplica al destino.

Instalación finalizada

Después de haber seguido los pasos anteriores, el proyecto implementado en el dispositivo se ejecuta ajustado por World Locking Tools para mantener un espacio bloqueado en el mundo estable de forma óptima. Los objetos fijos colocados en la escena seguirán siendo visualmente coherentes entre sí y con el mundo físico.

Aplicaciones de ejemplo disponibles

Se proporcionan escenas de ejemplo, incluidos scripts y recursos, para mostrar un uso más complejo de la funcionalidad de World Locking Tools.

Por ejemplo, WorldLockedPhysicsSample proporciona un entorno sencillo en el que se pueden crear y quitar objetos simulados físicamente, interactuando entre sí y con el entorno (la asignación espacial).

Para obtener un visión más específica de la característica de marcadores espaciales, el ejemplo de marcador espacial (SpacePin) es una muestra muy simplificada de alineación de un objeto virtual a gran escala con características del mundo real.

El ejemplo de marcadores de rayos (RayPin) amplía la funcionalidad que introduce el ejemplo de marcador espacial y permite fijar el mundo virtual al mundo físico con pruebas de rayos respecto a la malla espacial.

Referencias iniciales

Si no está familiarizado con los conceptos básicos de creación, compilación e implementación de aplicaciones de realidad aumentada (AR) en la familia de dispositivos HoloLens, los siguientes recursos de referencia pueden ayudarlo a empezar.

Desarrollo de Unity para HoloLens: Unity para el desarrollo de MR/AR.

HoloLens (1.ª generación) Conceptos básicos 100: Introducción a Unity: vea cómo empezar a desarrollar soluciones para HoloLens.

Tutoriales de HoloLens 2: vea cómo empezar a desarrollar soluciones para HoloLens 2.

Sistemas de coordenadas: implicaciones del espacio de coordenadas en el desarrollo de AR.

  • Tenga en cuenta que World Locking Tools resuelve los problemas que se comentan aquí.

¿Ha encontrado algún problema?

Consulte la guía de solución de problemas.