World Locking Tools 的初始设置

  • 项目

最精简的可能设置

此处的教程将分步指导如何完成最基础的设置，以启动并运行世界锁定的应用程序中的所有内容，无需任何进一步操作（例如空间定位点）。 它位于与此存储库同级的示例存储库中。

快速入门指南

此处提供了一种概念上不太详细但更实用的方法来将 WLT 集成到项目中。 适当情况下，它会回头参考这些更详尽的页面。 虽然哪种方法更合适确实取决于个人偏好，但快速阅读入门准备页面可节省时间，有助于了解应重点查阅本文档中的哪些部分。

支持的环境

World Locking Tools for Unity 目前面向 HoloLens 系列设备的 UWP 应用程序。 原始 HoloLens (x86) 和 HoloLens 2 (ARM64) 均受支持。

对其他平台的实验性支持通过 Unity 的 AR 子系统提供。

World Locking Tools 持续集成 (CI) 版本通过 Visual Studio 2017 与 Unity2018.4.6f1 进行验证。 但是，另外也使用 Unity2018 版本和一系列 Unity2019 进行了广泛的 WLT 开发。 Visual Studio 2017 和 Visual Studio 2019 均已用于工具的开发。

如果遇到与其他版本的 Unity 和/或 Visual Studio 的任何兼容性问题，我们很乐意了解！ 报告任何问题的最佳方式都是通过 GitHub 门户上的问题门户。

假定背景

假定希望将 World Locking Tools 解决方案集成到项目中的人员已掌握为 HoloLens 系列设备生成和部署应用程序的基础知识。 如果未掌握，本文末尾提供了实用的参考。

World Locking Tools 层

World Locking Tools 分为四个层。 箭头指向所依赖的层，简单明了的依赖项关系图如下所示：

Layer Diagram

虚线指示可选依赖项。

虽然示例层使用 MixedRealityToolkit (MRTK)，但其他层没有任何外部依赖项，并且完整功能可与 MRTK 兼容，但独立于 MRTK。

下面进一步说明应用程序依赖项。

这些层可以总结如下：

插件

一个可实现与引擎 DLL 直接通信的命令性接口。 参数封送等常见问题会在此处完成，并经常将多个函数组合成复合指令。 这仍然是基础 C++ DLL 的低级别 C# 接口。 可直接使用，但无需也不建议这样做。

核心

核心封装了获取 World Locking Tools 的稳定世界锁定空间（打包到声明性接口中）的好处所需的所有步骤。 预计要发布的正常运行的应用程序将仅使用核心中的功能。

工具

本质上讲，Tools 主要为诊断工具。 World Locking Tools 流程的可视化效果包含在表单中，这些表单可轻松添加到任何使用 World Locking Tools 的项目中。

包含其他方便的实用程序，预计将有助于开始编写自定义解决方案，而不是核心提供的最终解决方案。

示例

示例层尝试展示使用 World Locking Tools 设置常见场景的示例，以及 World Locking Tools 集成到各种场景中的最佳做法。

UX 和对象操作所需的任何 MRTK 依赖项都仅限于示例层的脚本和预制件。 这使得更低级别的层没有任何外部依赖项。

示例层中的脚本和资产不应直接集成到发布产品中，虽然这未明确禁止。 相反，其构造更侧重简单清晰，而非可重用性和效率。

该应用程序

一般而言，应用程序只需要依赖 World Locking Tools 核心。

开发过程中，工具层中提供了许多用于理解意外行为的可视化效果和其他帮助程序。 理想情况下，应用程序完成后，这些帮助程序将从中删除或者至少被禁用。 当然，它们还可以免费用于其他用途（以当前或修改后的形式）。 有关详细信息，请参阅许可证。

为进一步使用和试验 World Locking Tools 的全部功能，插件层提供了对引擎 DLL 的低级命令式访问。

如果需要访问插件层，则可能表明核心层提供的 API 表面存在缺陷。 World Locking Tools 团队一直都期望填补这些空白。 请考虑向团队提供相关见解。 请参阅供稿。

有关安装路径长度的警告说明

某些版本的 MRTK 存在安装路径过长的问题。 MRTK 安装中深层子文件夹的完整路径长度可能超过 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 和依赖项。 混合现实功能工具中提供了更简化的安装过程。 此处介绍了如何通过功能工具进行安装。 如果功能工具已安装 WLT，则可以跳过以下内容，转到将 WLT 添加到场景中

World Locking Tools 依赖于 NuGet 来安装基础 Frozen World 引擎。

如果要将 World Locking Tools 添加到现有项目，则建议从经过验证的项目开始，生成并部署到 HoloLens 设备。 这将有助于区分从一开始就让应用在 HoloLens 上运行的问题（这可能很复杂）与 World Locking Tools 的问题。 然后，继续执行下面的“FrozenWorld 引擎安装”和“World Locking Tools 资产”部分。

FrozenWorld 引擎安装

Frozen World 引擎 DLL 可使用出色的 NuGet For Unity 实用工具从 NuGet 获取，也可以通过手动获取。

使用 NuGet For Unity

请确保 nuget.org 源位于源中。 在“Unity”>“编辑”>“首选项”>“NuGet for Unity”中，对此进行检查。 如果不在源中，则：

使用“Unity”>“编辑”>“首选项”>“NuGet For Unity”中的“添加新建源 GUI”来添加同一共享。

  • 将“新建源”替换为所选名称（例如“NuGet”）。
  • 将“source_path”替换为 http://www.nuget.org/api/v2/"；

确认 nuget.org 源后，在“Unity”>“NuGet”>“管理 NuGet 包”中，找到并安装最新版本的 Microsoft.MixedReality.FrozenWorld.Engine。 （搜索“FrozenWorld”。）

若要更新到更高版本，请再次打开“Unity”>“NuGet”>“管理 NuGet 包”，找到 FrozenWorld.Engine 包并选择“更新”。 注意：可能需要在“更新”选项卡上查找所需版本。

手动安装 Frozen World 引擎 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 引擎 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 下载处获取最新版本的 nuget.exe。
  2. 确保 nuget.exe 在路径中（这里假定已将其复制到资产中）。
  3. 打开 PowerShell 命令窗口，将目录更改为“Assets”文件夹。
  4. 运行以下命令：
.\nuget.exe restore

若要升级到更高版本：

  1. 将上述 packages.config 文件中的 FrozenWorld.Engine 版本号更新为所需版本（例如，version="1.0.0" 变为 version="1.0.1"）。
  2. 删除“Assets/Packages”文件夹中以“Microsoft.MixedReality.Unity.FrozenWorld.Engine”开始的内容。
  3. 再次运行 nuget.exe，如上文所示。

World Locking Tools 资产

将所需的 World Locking Tools .unitypackage 文件导入项目（首选方法），或将其复制进去。 这些文件可能会移动到 Assets 中的子文件夹中，以使其不妨碍应用程序开发。

最新的稳定 .unitypackage 文件可在 World Locking Tools for Unity Releases 中找到。

WorldLocking.Core 和引擎层肯定都需要，因此最小的安装包是 WorldLockingCoreEngine.unitypackage。

若要确定可能需要哪些其他层，请参阅上面对 World Locking Tools 层及其依赖项的讨论。 每个层都包含在单个 Unity 包中。

由于某些 World Locking Tools 示例使用 MRTK 中的功能，因此示例 unitypackage 中包含兼容的 MRTK 快照。 有关最新 MRTK 版本，请查看此处。

将 World Locking Tools 添加到 Unity 场景

注意

下面所列的步骤在 WLT 配置场景实用工具中自动执行，可在菜单“混合现实工具包”>“实用工具”>“World Locking Tools”中找到。 Configuraton menu

在包含 FrozenWorld 引擎（来自 nuget.org）的 Unity 项目中，导入任何所需的 World Locking Tools 资产层（但至少是 WorldLocking.Core）和 MRTK（可选）。 然后创建新的场景（或打开现有场景）。

注意

在相机层次结构的根目录下添加一个额外的节点。 此节点将用于将头部跟踪相机调整为世界锁定空间。 （如果使用 MRTK，则这个新的 GameObject 将是 MixedRealityPlayspace 的父级。）

核心体验

将 WorldLockingManager 预制块从 Assets/WorldLocking.Core/Prefabs 拖动到场景中。 它在场景中的位置并不重要，但不应位于相机树中。 有关建议的配置，请参阅示例场景。

WorldLockingManager 预制件上提供了一些设置，但建议将其保留为默认值，以便开始使用。

有关所提供选项的说明，请参阅 World Locking Tools 上下文。

[可选] MRTK

World Locking Tools 与 MRTK 互补，但为正交关系。 将 MRTK 与 World Locking Tools 结合使用完全是可选操作。

也就是说，World Locking Tools 示例使用 MRTK 生成，而 MRTK 通常在开发从 World Locking Tools 中受益最多的 MR 应用程序类型方面非常具有价值。

如果使用 MRTK，而不是使用示例中包含的快照，则建议至少添加以下包的最新版本：

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

[可选] 直观呈现 spongy 和世界锁定的定位点

这需要向项目的资产添加 WorldLocking.Tools。

如果要直观呈现定位点，请将 AnchorGraphVisual 预制件从 Assets/WorldLocking.Tools/Prefabs 拖动到场景中。 用于在检查器中切换可视化效果的复选框位于 WorldLockingManager 上。

作为诊断，WorldLocking.Tools 的可视化效果并未进行大量优化，并且会在核心 World Locking Tools 处理时间变得相关之前很久就降低性能。

[可选] 混合现实中参数控制的简单仪表板

提供了简单的 HUD，可用于在运行时从 MR 内部控制 WorldLockingManager。 这些在示例包中提供。 虽然它们可以按原样使用，但在将类似功能生成到应用程序自己的显示系统和 UX 中时，其目的在于作为模式。

拖动 WorldLocking.Examples/Prefabs/Dashboard 预制件，并将其定位点可视化工具字段指向上一部分中的可视化工具。

将现有场景迁移到 World Locking Tools

迁移到 World Locking Tools 时，最大的变化是不再需要使用空间定位点对虚拟对象进行世界锁定。

传统意义上，空间定位点是唯一可用于对单个对象进行世界锁定的工具。 但是，在使用 World Locking Tools，这些虚拟对象所处的坐标空间已进行世界锁定。 无需进一步锁定。

空间定位点不仅不必要，而且无法正常工作，因为它们无法考虑相机层次结构上的其他转换（例如 MRTK“Playspace”转换）。

因此，应从场景中删除所有空间定位点，添加空间定位点的任何脚本都应终止添加操作。 无需将空间定位点替换为任何内容；World Locking Tools 会将其目标定位到现实世界。

如果要比较使用和不使用 World Locking Tools 的世界锁定，则可以用 WorldLocking.Tools 中提供的 ToggleWorldAnchor 替换它们，而不是删除 WorldAnchor。

ToggleWorldAnchor 的工作方式与 WorldAnchor 完全相同，其重要区别是，World Locking Tools 管理器处于活动状态时，能够很方便地自行禁用并不产生妨碍。 禁用 World Locking Tools 管理器后，其行为与普通的 WorldAnchor 一样。

如果出于其他某种原因，场景（例如对于网络共享）中仍然需要 WorldAnchor，可将其与适配器一起使用，该适配器作为 WorldAnchorAdapter 提供。

WorldAnchorAdapter 将由 WorldAnchor 定位的 GameObject 的原始位置转换为世界锁定的 Unity 全局空间，然后将转换应用于目标对象。 若要使用 WorldAnchor，而不是直接将 WorldAnchor 添加到对象，则 WorldAnchor 应应用于代理对象（通常是其他的空 GameObject），然后在 Update () 中，WorldAnchorAdapter 会读取 WorldAnchor 的姿势，将其正确转换，并应用于目标。

设置完成

遵循上述步骤操作后，部署到设备的项目将按 World Locking Tools 调整运行，以保持稳定状态最佳的世界锁定空间。 放置在场景中的任何固定对象在视觉上相对于彼此都保持一致，相对于物理世界也保持一致。

可用示例应用程序

示例场景，包括脚本和资产，供演示 World Locking Tools 功能的更复杂使用情况。

例如，WorldLockedPhysicsSample 提供了一个简单的环境，可以在其中创建和删除物理模拟对象，并与彼此以及与环境（空间映射）进行交互。

为了更集中地了解空间固定功能，SpacePin 提供了一个将大型虚拟对象与实际功能对齐的简化示例。

RayPin 扩展了 SpacePin 示例引入的功能，便于通过针对空间网格的光线测试将虚拟世界固定到物理世界。

入门参考

如果不熟悉创建、生成 AR 应用以及将其部署到 HoloLens 系列设备的基础知识，以下是一些可帮助入门的参考。

Unity 开发概述 - 用于 MR/AR 开发的 Unity。

MR 基础知识 100 - 开始针对 HoloLens 开发演练

HoloLens 2 教程 - 开始针对 HoloLens 2 开发演练。

Coordinate 系统协调 AR 开发中的空间影响。

  • 请注意，World Locking Tools 解决了此处讨论的问题。

遇到问题？

请参阅故障排除指南。