Поделиться через

Начальная настройка World Locking Tools

  • Статья

Простейшая настройка

В этом руководстве описана минимальная настройка, которая поможет вам приступить к работе, когда все в вашем приложении будет заблокировано в мире, без каких-либо дополнительных действий (например, использования пространственных привязок). Примеры доступны в связанном репозитории Samples.

Краткое руководство по началу работы

Здесь описан менее концептуально подробный и более прагматичный подход к интеграции WLT в проект. Там, где это уместно, приводятся ссылки на страницы с подробным описанием. Хотя в реальности выбор подходящего подхода зависит от личных предпочтений, быстрое прочтение страницы Перед началом работы поможет вам быстрее принять решение о том, на что следует направить усилия при работе с этой документацией.

Поддерживаемые среды

Решение World Locking Tools для Unity сейчас нацелено на приложения UWP для семейства устройств HoloLens. Поддерживаются как оригинальные устройства HoloLens (x86), так и устройства HoloLens 2 (ARM64).

Экспериментальная поддержка других платформ доступна в подсистемах AR Unity.

Сборка непрерывной интеграции (CI) World Locking Tools проверяется с помощью Unity2018.4.6f1 с Visual Studio 2017. При этом обширная разработка WLT также была выполнена с использованием ряда версий Unity2018 и Unity2019. Решения разрабатывались с помощью Visual Studio 2017 и Visual Studio 2019.

Если у вас возникнут проблемы с совместимостью с другими версиями Unity и (или) Visual Studio, мы будем рады узнать об этом! Лучший способ сообщить о проблемах — использовать раздел проблем в GitHub.

Предполагаемые навыки

Предполагается, что пользователи, которые хотят интегрировать решение World Locking Tools в свои проекты, уже знакомы с основами создания и развертывания приложений для устройств семейства HoloLens. В противном случае они могут перейти в конец этой статьи, где есть некоторые полезные ссылки.

Уровни World Locking Tools

Решение World Locking Tools состоит из четырех уровней. Простая схема зависимостей со стрелками, указывающими на зависимый уровень, выглядит следующим образом:

Схема слоев

Пунктирные линии указывают на необязательные зависимости.

Хотя уровень Examples использует MixedRealityToolkit (MRTK), ни один из других уровней не имеет каких-либо внешних зависимостей. При этом доступна полная функциональность, совместимая с МРТК, но не зависящая от нее.

Дополнительные примечания о зависимостях приложений см. ниже.

Уровни можно описать следующим образом:

Подключаемый модуль

Императивный интерфейс, обеспечивающий прямой обмен данными с библиотекой DLL обработчика. Здесь решаются общие вопросы, такие как маршалирование аргументов, а также некоторая компоновка нескольких функций, часто совместно используемых в составных директивах. Это низкоуровневый интерфейс C# для базовой библиотеки C++ DLL. Его прямое использование доступно, но это не требуется и не рекомендуется.

Основные сведения

Core — это инкапсуляция всех шагов, необходимых для получения преимуществ заблокированного в мире стабильного пространства World Locking Tools, упакованных в декларативный интерфейс. Предполагается, что рабочее приложение будет поставляться с использованием только функций уровня Core.

Инструменты

Уровень Tools в основном используется для диагностики. Визуализации процессов World Locking Tools включены в формы, которые легко добавить в любой проект, использующий World Locking Tools.

Включены и другие удобные служебные программы, но ожидается, что они помогут приступить к написанию пользовательских решений, а не будут окончательными решениями, как предлагается уровнем Core.

Примеры

Уровень Examples пытается представить примеры настройки распространенных сценариев при использовании World Locking Tools, а также предложить лучшие практики интеграции World Locking Tools в различные сценарии.

Любые необходимые зависимости MRTK для взаимодействия с пользователем и манипулирования объектами ограничены скриптами и заготовками на уровне Examples. При этом нижние слои остаются свободными от любых внешних зависимостей.

Не предполагается, что скрипты и ресурсы на уровне Examples будут напрямую интегрированы в поставляемые продукты, хотя это не запрещено. Их конструкция характеризуется скорее простотой и ясностью, а не повторным использованием и эффективностью.

Приложение

Как правило, приложению потребуется только зависимость от World Locking Tools Core.

Во время разработки на уровне Tools доступны многие визуализации и другие вспомогательные средства для анализа неожиданного поведения. Эти вспомогательные средства в идеале должны быть удалены из готового приложения или, по крайней мере, отключены. Конечно, их можно использовать и для других целей, — как измененные, так и нет. Дополнительные сведения см. в лицензии.

Для расширенного использования и экспериментирования со всеми возможностями World Locking Tools уровень Plugin предлагает низкоуровневый императивный доступ к Engine DLL.

Если доступ к уровню Plugin становится необходимым, это может указывать на недостаток поверхности API, предлагаемой на уровне Core. Команда World Locking Tools всегда стремится заполнить такие пробелы. Вы можете поделиться соответствующими сведениями с командой. См. сведения об участии.

Предупреждение о длине пути установки

В некоторых версиях МРТК есть проблема с длинными путями установки. Полная длина пути к глубоким вложенным папкам в установке МРТК может превышать ограничение для пути Windows (260 символов). Если появляется ошибка сборки следующего вида:

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"

но файл на самом деле есть на диске, проблема, скорее всего, в длине пути. Команда MRTK знает об этом и работает над улучшением. (Примечание. Мы считаем, что команда внесла существенные улучшения, и это больше не является проблемой.) В то же время обходной путь заключается в сокращении префикса пути с помощью комбинации следующих действий:

  1. Установите проект Unity в корневую папку с более коротким путем, например, D:\Proj.
  2. При клонировании репозитория клонируйте корень World Locking Tools с использованием более короткого имени, чем имя по умолчанию \MixedReality-WorldLockingTools-Unity, например:
git clone https://github.com/microsoft/MixedReality-WorldLockingTools-Unity.git d:\MyGit\wlt

Это ограничение пути, как правило, не является проблемой для World Locking Tools, так как это решение не использует такую глубокую структуру папок.

Добавление World Locking Tools в проект Unity

Примечание

Далее описывается установка World Locking Tools и зависимостей вручную. Решение Mixed Reality Feature Tool помогает значительно упростить процесс установки. Установка с помощью Feature Tool описана здесь. Если Feature Tool устанавливает WLT, вы можете пропустить следующие шаги и перейти к добавлению WLT в свою сцену.

World Locking Tools использует NuGet для установки базового пакета Frozen World Engine.

При добавлении World Locking Tools в существующий проект рекомендуется начать с проекта, который был проверен для сборки и развертывания на устройстве HoloLens. Это поможет отделить проблемы с запуском приложения на устройстве HoloLens, которые могут быть сложными, от проблем с World Locking Tools. Затем перейдите к разделам Установка Frozen World Engine и Ресурсы World Locking Tools ниже.

Установка Frozen World Engine

Библиотеку Frozen World Engine DLL можно получить из NuGet с помощью удобной служебной программы NuGet For Unity или вручную.

Использование NuGet For Unity

Убедитесь, что веб-канал nuget.org добавлен в источники. Это можно проверить, выбрав Unity > Edit > Preferences > NuGet for Unity ("Unity" > "Изменить" > "Параметры" > "NuGet for Unity"). В противном случае выполните одно из следующих действий:

Используйте графический пользовательский интерфейс Add New Source ("Добавить новый источник"), выбрав Unity > Edit > Preferences > NuGet For Unity ("Unity" > "Изменить" > "Параметры" > "NuGet for Unity"), чтобы добавить ту же общую папку.

  • Измените New Source ("Новый источник") на нужное имя (например, "NuGet").
  • Замените source_path на http://www.nuget.org/api/v2/".

Убедившись в наличии веб-канала nuget.org, выберите Unity > NuGet > Manage NuGet Packages ("Unity" > "NuGet" > "Управление пакетами NuGet"), а затем найдите и установите последнюю версию Microsoft.MixedReality.FrozenWorld.Engine. (Введите FrozenWorld для поиска.)

Чтобы выполнить обновление до более поздней версии, снова выберите Unity > NuGet > Manage NuGet Packages ("Unity" > "NuGet" > "Управление пакетами NuGet"), найдите пакет FrozenWorld.Engine и щелкните Update ("Обновить"). Примечание. Возможно, вам придется перейти на вкладку Updates ("Обновления"), чтобы найти нужную версию.

Установка Frozen World Engine DLL вручную

Используйте текстовый редактор, чтобы добавить строку packageSources в Assets/NuGet.config, например:

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

Если у вас еще нет файла Assets/NuGet.config, вы можете скопировать его в репозитории World Locking Tools в GitHub.

С помощью текстового редактора добавьте пакет Frozen World Engine DLL в Assets/packages.config, например:

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

Снова-таки, если у вас еще нет файла Assets/packages.config, вы можете получить его в репозитории World Locking Tools в GitHub или просто скопировать вышеприведенное в текстовый файл с именем Assets/packages.config.

Настроив NuGet.config и packages.config, выполните установку:

  1. Получите последнюю версию nuget.exe в разделе скачиваемых ресурсов NuGet.
  2. Убедитесь, что файл nuget.exe доступен в вашем пути (предполагается, что он был скопирован в папку Assets).
  3. Откройте командное окно PowerShell и перейдите в папку Assets.
  4. Выполните следующую команду:
.\nuget.exe restore

Чтобы выполнить обновление до более поздней версии:

  1. Обновите номер версии FrozenWorld.Engine в файле packages.config выше до нужной версии (например, version="1.0.0" изменится на version="1.0.1").
  2. Удалите все элементы в папке Assets/Packages, начиная с Microsoft.MixedReality.Unity.FrozenWorld.Engine.
  3. Повторно запустите nuget.exe, как описано выше.

Ресурсы World Locking Tools

Импортируйте необходимые файлы .unitypackage World Locking Tools в проект (предпочтительный метод) или скопируйте их. Их можно переместить во вложенную папку в папке Assets, чтобы они не мешали разработке приложений.

Последние стабильные файлы .unitypackage можно найти в выпусках World Locking Tools для Unity.

Вам определенно потребуются уровни WorldLocking.Core и Engine, поэтому минимальным установочным пакетом будет WorldLockingCoreEngine.unitypackage.

Чтобы определить, какие другие уровни могут потребоваться, см. обсуждение уровней World Locking Tools и их зависимостей выше. Каждый уровень содержится в одном пакете Unity.

Так как в некоторых примерах World Locking Tools используются компоненты MRTK, в пакет unitypackage примеров включен моментальный снимок, совместимый с MRTK. Последний выпуск MRTK доступен здесь.

Добавление World Locking Tools в сцену Unity

Примечание

Все шаги, перечисленные ниже, автоматизированы в служебной программе для настройки сцены WLT, которую можно найти, выбрав Mixed Reality Toolkit > Utilities > World Locking Tools ("Mixed Reality Toolkit"> "Служебные программы" > "World Locking Tools"). Меню конфигурации

В проекте Unity, содержащем Frozen World Engine (с nuget.org), импортируйте любые требуемые уровни ресурсов World Locking Tools (как минимум WorldLocking.Core) и при необходимости MRTK. Затем создайте новую сцену (или откройте существующую).

Примечание

Добавьте дополнительный узел в корень иерархии камеры. Этот узел будет использоваться для настройки камеры с отслеживанием головы в пространстве, заблокированном в мире. (При использовании MRTK этот новый объект GameObject будет родительским для MixedRealityPlayspace.)

Основные возможности

Перетащите заготовку WorldLockingManager из Assets/WorldLocking.Core/Prefabs в сцену. Ее место в сцене не имеет значения, но она не должна находиться в дереве камеры. Предлагаемую конфигурацию см. в примере сцены.

В заготовке WorldLockingManager доступны параметры для настройки, но для начала рекомендуется оставить значения по умолчанию.

Список доступных параметров см. в разделе Контекст World Locking Tools.

[Необязательно.] MRTK

Решение World Locking Tools дополняет МРТК, но является ортогональным. Использовать МРТК вместе с World Locking Tools необязательно.

Тем не менее примеры World Locking Tools созданы с помощью MRTK, а MRTK, как правило, очень удобно использовать при разработке типов приложений смешанной реальности, которые нацелены на World Locking Tools.

Если МРТК используется вместо моментального снимка, включенного в примеры, рекомендуется добавить последние версии как минимум следующих пакетов:

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

[Необязательно.] Визуализация губчатого пространства и привязок блокировки в мире

Для этого необходимо добавить WorldLocking.Tools в папку Assets проекта.

Если вы хотите визуализировать свои привязки, перетащите заготовку AnchorGraphVisual из Assets/WorldLocking.Tools/Prefabs в сцену. Флажки для переключения аспектов визуализации в инспекторе доступны в WorldLockingManager.

В качестве средства диагностики визуализация WorldLocking.Tools не сильно оптимизирована и снизит производительность задолго до того, как станет актуальным время базовой обработки World Locking Tools.

[Необязательно.] Простая панель мониторинга для управления параметрами в смешанной реальности

Доступен простой дисплей HUD, который можно использовать для управления WorldLockingManager во время выполнения в смешанной реальности. Эта возможность предоставляется с пакетом Examples. Хотя ее можно использовать как есть, она предназначена в качестве шаблонов при встраивании аналогичных компонентов в собственную систему отображения приложений и взаимодействия с пользователем.

Перетащите заготовку WorldLocking.Examples/Prefabs/Dashboard и укажите поле Anchor Visualizer в Visualizer (см. предыдущий раздел).

Перенос существующей сцены в World Locking Tools

Самым большим изменением при переносе в World Locking Tools является то, что больше не требуется использовать пространственные привязки для блокировки виртуальных объектов в мире.

Пространственные привязки традиционно были единственным инструментом, доступным для блокировки отдельных объектов в мире. Но при использовании World Locking Tools пространство координат, в котором существуют эти виртуальные объекты, уже заблокировано в мире. Дальнейшая блокировка не требуется.

Пространственные привязки не только не нужны, они не будут работать правильно, так как не учитывают дополнительные преобразования вверх по иерархии камеры (например, преобразование Playspace в МРТК).

Следовательно, все без исключения пространственные привязки должны быть удалены из сцены, а любые скрипты, добавляющие пространственные привязки, должны прекратить это делать. Пространственные привязки не нужно ничем заменять — решение World Locking Tools привяжет свои целевые объекты к реальному миру.

Если вам нужно сравнить блокировку в мире с и без World Locking Tools, вместо удаления WorldAnchors можно выполнить замену на ToggleWorldAnchor (доступно в WorldLocking.Tools).

ToggleWorldAnchor работает точно так же, как и WorldAnchor, с той важной разницей, что, когда диспетчер World Locking Tools Manager активен, он отключается и не мешает работе. Когда диспетчер World Locking Tools отключен, он ведет себя как и любой экземпляр WorldAnchor.

Если по какой-либо другой причине WorldAnchor по-прежнему требуются в сцене (например, для совместного использования сети), можно применить адаптер, поставляемый как WorldAnchorAdapter.

WorldAnchorAdapter преобразует необработанное положение GameObject, расположенного с помощью WorldAnchor, в заблокированное в мире глобальное пространство Unity, а затем применяет преобразование к целевому объекту. Чтобы использовать адаптер, вместо того, чтобы добавлять WorldAnchor непосредственно к объекту, WorldAnchor следует применить к прокси-объекту (обычно это пустой объект GameObject), а затем в Update() WorldAnchorAdapter считывает положение WorldAnchor, корректно преобразует его, и применяет к целевому объекту.

Установка завершена

После выполнения вышеуказанных шагов проект, развернутый на устройстве, будет работать с параметрами World Locking Tools для поддержания оптимально стабильного пространства, заблокированного в мире. Любые фиксированные объекты, помещенные в сцену, останутся визуально согласованными как друг с другом, так и с физическим миром.

Доступные примеры приложений

Примеры сцен, включая скрипты и ресурсы, предназначены для демонстрации более сложного использования возможностей World Locking Tools.

Например, WorldLockedPhysicsSample предоставляет простую среду, в которой можно создавать и удалять физически моделируемые объекты, взаимодействующие друг с другом и с окружающей средой (пространственное сопоставление).

Для более подробного изучения компонента Space Pinning SpacePin предоставляет более упрощенный пример сопоставления крупномасштабного виртуального объекта с компонентами реального мира.

RayPins расширяет возможности, представленные в примере SpacePin, позволяя привязывать виртуальный мир к физическому миру с помощью тестов луча на виртуальной сетке.

Справочные материалы для начала работы

Если вы не знакомы с основами создания, создания и развертывания приложений дополненной реальности на устройствах семейства HoloLens, ниже представлены несколько ссылок, которые могут помочь вам начать работу.

Общие сведения о разработке Unity — разработка Unity для смешанной и дополненной реальностей.

Основы смешанной реальности — руководство по разработке для HoloLens.

Руководства по HoloLens 2 — руководство по разработке для HoloLens 2.

Системы координат — использование пространства координат в разработке для дополненной реальности.

  • Обратите внимание, что решение World Locking Tools решает проблемы, описанные здесь.

Возникла проблема?

См. руководство по устранению неполадок.