虚幻引擎5文档已被迁移至 Epic开发者社区

Project Anywhere XR是一项概念验证方案，用于演示如何借助地理空间技术、全局3D地貌和数据流，将现视世间以3D区块的形式显示在虚幻引擎中。此版本的Project Anywhere演示了在HoloLens 2应用中使用大规模数据集是的可能性。

此项目使用了以下插件在AR虚拟棋盘上显示现实世界地理信息：

• Cesium for Unreal

• 微软MR UX工具（Microsoft Mixed Reality UX Tools）

• 地理配准（GeoReferencing）

先决条件和准备工作

开始前，请确保你已准备好以下条件：

• Cesium for Unreal插件 版本1.6.0或更高版本

• 微软MR UX工具（Microsoft Mixed Reality UX Tools）

• 计算机中安装了最新版本Windows 10

• 适用于HoloLens 2的Microsoft工具

• （可选）HoloLens 2设备更新到了最新版本

你可以在 虚幻商城 中找到所需的第三方插件。如果启动项目时没有这些插件，系统将要求你下载并安装。

项目设置

按照以下步骤，使用Project Anywhere XR示例内容设置项目，并将资产连接到你的 Cesium Ion 账号。

1. 在Epic Games启动程序中下载 Project Anywhere XR 示例，并在虚幻编辑器中创建新项目。

2. 登录你的 Cesium Ion 账号。

3. 前往 资产库（Asset Depot） 选项卡，并添加以下 3D图块（3D Tiles） 资产：

   • Aerometrex丹佛摄影测绘（Aerometrex Denver Photogrammetry）(#354307)

   • Bing地图航拍（Bing Maps Aerial）(#2)

   • Cesium OSM建筑（Cesium OSM Buildings）(#96188)

   • Cesium世界地貌（Cesium world terrain）(#1)

   • 墨尔本摄影测绘（Melbourne Photogrammetry）(#69380)

   请仔细阅读条款。某些条款仅用于非商业目的。

4. 前往 访问令牌（Access Tokens） 选项卡。

5. 单击 创建令牌（Create Token） ，打开 创建令牌（Create Token） 面板。

6. 在 创建令牌（Create Token） 面板中：

   • 将 名称（Name） 字段设置为 Project Anywhere XR

   • 在 作用域（Scope） 中，启用以下选项：

     • assets:list

     • assets:read

     • profile:read

     • assets:write

     • geocode

   • 在 资源（Resources） 下，为 已选资产（Selected assets） 选择单选按钮，以显示 可用资产（Available Assets） 列表。更好的做法是，将令牌启用至你在应用程序中所使用的唯一资产集

   • 在 可用资产（Available Assets） 列表中，选择以下资产：

     • Aerometrex丹佛摄影测绘（Aerometrex Denver Photogrammetry）(#354307)

     • Bing地图航拍（Bing Maps Aerial）(#2)

     • Cesium OSM建筑（Cesium OSM Buildings）(#96188)

     • Cesium世界地貌（Cesium world terrain）(#1)

     • 墨尔本摄影测绘（Melbourne Photogrammetry）(#69380)

   • 点击 创建（Create） 以创建令牌。

7. 选择 Project Anywhere XR 并复制 令牌（Token） 下的文本。

8. 在虚幻编辑器的 世界大纲视图（World Outliner） 中，选择以下 Cesium3DTileset Actor：

   • Cesium OSM建筑（Cesium OSM Buildings）

   • Cesium世界地貌（Cesium World Terrain）

   • 丹佛（Denver）

   • 墨尔本摄影测绘（Melbourne Photogrammetry）

9. 细节（Details） 面板会显示以上每个Actor的通用属性。找到 Ion访问令牌（Ion Access Token） 属性，然后将你在Cesium Ion账号中生成的令牌粘贴到其中。

10. 选择 Cesium世界地貌（Cesium World Terrain） Actor，并选择其 Bing地图航拍（Bing Maps Aerial） 组件。

11. 在细节（Details）面板中，将你在Cesium Ion账号中生成的令牌粘贴到 Ion访问令牌（Ion Access Token） 属性。

12. 为四个 Cesium3DTileset Actor和 Bing地图航拍（Bing Maps Aerial） 组件设置了令牌后，地貌数据就会出现在视口中。

13. 在工具栏（Toolbar）中，点击 保存当前（Save Current） ，以保存你在关卡中所做的更改。

查看项目

此应用程序会通过Microsoft的 全息远程播放器 ，将内容从计算机流送到HoloLens 2设备。内容流送是指先在计算机上加载大型数据集，然后创建渲染画面，再通过网络将渲染画面发送到设备上。在将项目打包为应用并部署到设备前，你必须先确保数据集符合设备的内存容量。

如需了解如何使用全息远程播放器将数据从虚幻编辑器流送到设备，请参阅 使用全息远程播放器流送到设备 。

如果你没有可连接计算机的HoloLens 2设备，则可以使用编辑器内置的模拟功能、键鼠输入来查看项目。要启用编辑器内置模拟，需进行以下操作：

1. 在主菜单中，选择 编辑（Edit） > 项目设置（Project Settings） 以打开 项目设置（Project Settings） 窗口。

2. 在 项目设置（Project Settings） 窗口中的 平台（Platforms） 下，选择Windows Mixed Reality。

3. 在 全息远程（Holographic Remoting） 部分，将 启用输入模拟（Enable Input Simulation） 设置为 True 。

如需详细了解编辑器内置模拟的用法，请参阅Microsoft的 输入模拟 文档。

此项目的编辑器内置模拟存在以下限制：

• 编辑器内置模拟不支持校准。要自动放置棋盘，则需要空间网格体来进行校准，应用程序在扫描环境时会创建该网格体。

• 在编辑器中运行时，应用程序不会接收用于选择书签的夹捏交互事件，但你可以使用键盘上的 1 和 2 键模拟这些双手交互。

项目启动时，会出现虚拟棋盘。世界的一部分会作为地图显示于棋盘，其中包含以下信息：

• 在地图的中心，地理坐标格式为：纬度/经度/海拔

• 地图会显示该区域的真实世界长度

使用手动菜单

该项目包含一个菜单，张开你面前的其中一只手即可访问该菜单。该菜单包含一个带图钉的地球模型，标记了可用于更新地图的特定位置、一个用于旋转地球模型的滑块，以及用于移动棋盘或了解显示数据的按钮。该菜单使用HoloLens 2的 用户体验工具手动菜单 在蓝图 BP_HandMenu 中进行了定义。

以下小节描述了如何与菜单交互，以及菜单是如何创建的。

使用书签跳转到特定位置

在地球模型中，有图钉标记了世界中的特定位置，你可以在棋盘上选择和查看这些位置。

要选择其中一个位置，需将手靠近图钉，直至图钉变成红色，并出现带位置名称的提示文本。用手指夹捏，使棋盘在更新时纳入该位置。

要让地球模型绕轴局部旋转，需夹捏并拖动模型下方的滑块，要停止旋转，松开滑块即可。

应用程序启动后，图钉会根据BP_HandMenu Actor中书签数据表 DT_Bookmarks_PAXR 中的条目动态生成。图钉蓝图 BP_Bookmark_Button ，即自定义 UxtPressableButton ，附于球体组件中，因此图钉会自动随地球旋转。

菜单按钮

以下按钮提供了所用数据的信息，以及在你的环境中移动棋盘的能力：

菜单按钮	描述
数据属性（Data Attribution）	单击手动菜单中的 数据属性（Data Attribution） 按钮，可读取所显示地图的数据属性（Data Attribution）。
校准（Calibrate）	首次启动应用程序时，全息棋盘会显示在你房间的默认位置。点击此按钮可自动将棋盘重新定位在你视野的正前方。如需更多细节，请参阅以下小节 在房间中移动虚拟棋盘 。
上移（Move Up）	沿Z轴逐渐向上移动棋盘。
下移（Move Down）	沿Z轴逐渐向下移动棋盘。
向左旋转（Rotate Left）	围绕Z轴逐渐向左旋转棋盘。
向右旋转（Rotate Right）	围绕Z轴逐渐向右旋转棋盘。

探索BP_HandMenu蓝图

该菜单使用HoloLens 2的 用户体验工具手动菜单 在蓝图BP_HandMenu中进行了定义。UxtPalmUpConstraint激活或停用时，会显示或隐藏菜单。按钮交互会重定向至在 BP_AnywhereXRPlayerController 中进行的适当操作。****在BeginPlay中，BP_HandMenu会对以下内容进行初始设定：

• 在变量 MRAnywhere Player Controller 中，对BP_AnywhereXRPlayerController的引用进行存储。

• 创建和隐藏 数据属性（Data Attribution） 控件。

• 将所有菜单事件绑定到相应的事件处理程序。

• 将滑块事件绑定到地球模型的旋转状态中。

• 读取 DT_Bookmarks_PAXR 数据表中的所有条目，并使用这些条目生成相应书签。

在房间中移动虚拟棋盘

首次启动应用程序后，虚拟棋盘会显示在你房间的默认位置。你可以使用菜单中的校准（Calibrate）按钮，或菜单中的移动（Move）和旋转（Rotate）按钮，将位置调整为房间中更好的位置，以黑暗棋盘为佳。放置棋盘时， ARPins 会将棋盘锚定在世界中。

在手动菜单（Hand Menu）中，点击 校准（Calibrate） 按钮开始校准。该操作将隐藏当前棋盘，随后会将其替换为用于校准过程的新虚拟棋盘。新棋盘的形状和大小与先前棋盘相同，且朝向视野方向。头部位置和锚点之间的向量决定了棋盘地图以哪个方向为北向。

要确认棋盘位置及其北向，需进行以下操作：

• 移动头部，将校准棋盘移动到你想要的位置。此操作期间会用到房间中的空间网格体。

• 再次点击，即可释放校准棋盘并设置棋盘位置。

如果要对棋盘位置进行微调，需点击菜单中的移动（Move）和旋转（Rotate）按钮进行增量更改。

蓝图BP_AnywhereXRPlayerController中包含了棋盘校准和移动的逻辑。以下小节对某些用于校准的函数做了说明。

校准函数

StartTable Calibration 函数是通过手动菜单中的校准按钮调用的。调用时，该函数会执行以下操作：

• 生成BP_AnchorGizmo，并按照设备方向自动进入校准模式。

• 将自身绑定到由BP_AnchorGizmo的点击以放置（Tap To Place）所触发的Anchor Placed事件。

• 禁用虚拟棋盘，使棋盘隐藏且不发生碰撞。

用户放置BP_AnchorGizmo时，会调用 OnAnchorPlaced 函数。调用时，该函数会执行以下操作：

• 对已确认位置进行变换，并调用ChangeTableOrigin函数。

• 销毁BP_AnchorGizmo。

• 在新位置启用棋盘，令棋盘不再隐藏并再次发生碰撞。

ChangeTableOrigin 函数是由OnAnchorPlaced调用的。调用时，该函数会执行以下操作：

• 在棋盘上调用特定传送函数，以确保对每个依赖对象都进行了适当地重新定位。

• 将 ARPin 的位置存储于本地。

与虚拟棋盘上的地图交互

虚拟棋盘上的地图支持手动交互，可进行平移和缩放。旋转未实现，因此地图的北向不会改变。地图上出现视觉提示时，即表示你可以开始交互。交互会跟踪棋盘中的平面几何体而非地貌。

要平移地图，需用一只手夹捏，并向所需的地图移动方向移动你的手。松开手，即可释放地图。

双手夹捏可缩放地图，双手拉开会缩小，双手合拢会放大。松开手，即可释放地图。

BP_HolographicTable中有对地图交互逻辑的定义。当团队执行地图交互时，以下考虑因素可为设计选择提供信息：

• HoloLens操作仅适用于单个对象，但Cesium 3D 图块集则由多个Actor构成。应用程序可在保持棋盘固定的同时，拦截HoloLens操作交互，然后将输入转译和缩放操作相应地应用于图块集。

• 由于地球是圆的，所以如果持续平移，水平运动会最终将你带离地球表面。尺度较小时这不是问题，但缩放到最大尺度时，这个问题会很明显。做平移运动时需要考虑到地球曲线，但如将这个曲线应用于每一步，成本可能很高。

  为解决该问题，当运动超过设定阈值时，应用程序就会将图块集Actor的原点重新定位到棋盘中心。这样做的效果并不显眼，却能够确保计算仍正确。

• 由于地图可以显示山脉，因此椭圆体与地面之间的高度值为变量。如果放大，并将椭圆体原点保持于棋盘中心，则地表就会在其上方浮动过远。在地球的每个位置，该偏移量都不尽相同。图块集可以垂直移动，以确保始终适合棋盘，但地球上任何一块土地的最小海拔是不可知的。

  为解决该问题，应用程序会通过线迹追踪来确定离地高度，然后应用控制算法使地表粘在桌子上，不论当前是什么位置或比例。

• HoloLens 2交互可与任何可视几何体发生碰撞。默认情况下，地图所显示的地貌会阻止来自HoloLens 2的光线投射，以防止其击中棋盘。

  为解决该问题，项目设置中设置了名为 TileSets 的自定义碰撞通道。每个Cesium3DTiles的碰撞属性将仅使用TileSets通道阻止碰撞，而忽略可视性通道。

由于这些设计选择，当你与虚拟棋盘交互时，棋盘将获得包含所有3D图块的列表，并对图块进行水平和垂直移动，或缩放图块以应用缩放效果，或通过位移阈值重新定位所有图块，以确保地图保持水平。

已知问题

以下是可能会遇到的已知问题及变通方案：

• 如果你以 发行 模式打包应用，并在启动时收到严重错误消息，有两种方法可以解决此问题：

  • 关闭所有使用 Cesium For Unreal 插件的虚幻编辑器实例，并删除位于 %LOCALAPPDATA%\UnrealEngine\4.27 的 cesium-request 缓存文件

  • 以 开发 模式打包应用。

• 如果你使用编辑器的VR预览功能来预览应用程序，此时手动跟踪可正常工作，但交互尚未注册，请重新启动HoloLens 2设备和虚幻应用程序。