Cesium For Unreal 的绝佳伴侣

点击蓝色

关注我们

2021年3月Cesium For Unreal（本文简称CFU）的发布如同历史上的WorldWind，OsgEarth 和 CesiumJS的开源，再次引起了国内三维地球界的躁动，基于UE的各种球都出现了。这个热点我们也要蹭蹭。从那时候起，我们也开始研究这个，在各种小项目使用开始，不管是不是需要这个，都引入它。用的多了，坑就都踩到了，踩一个填一个，慢慢把他改造的更好用了一些。

这篇文章不是Cesium For Unreal的介绍文章，如果想学习CFU建议大家移步Cesium官方教程，讲的很详细https://cesium.com/learn/unreal/unreal-faq/

我们的改造方法，就是做了我们的一个插件EarthSDK For UE（EarthSDK将是我们可视化端解决方案的统一名称，希望大家看到不陌生）。这个插件和CFU是共生关系，我们也会依赖CFU（Cesium For Unreal），一起使用是绝佳伴侣，我们为CFU提供了类似CesiumJS纯鼠标交互方式，纯平地球显示，XYZ影像加载等。

为了这些功能我们避免不了对官方的CFU会有一些小的改动，改动后的代码我们也开源出来，地址在这里https://gitee.com/cesiumlab/CesiumForUnreal（阅读完全文点击阅读原文可直接跳转），未来我们定期更新这个插件，确保和Cesium官方的插件版本能同步更新。

下来我们详细介绍EarthSDK For UE的各个功能

0****1

和CesiumJS一致的鼠标交互方式

作为玩了16年三维地球的人，第一个接受不了的就是CesiumFor Unreal提供的Dynamic Pawn的键盘+鼠标操作的方式，原本期望着Cesium团队能尽快把这个改进了，可惜两年多了，一点进展都没（https://github.com/orgs/CesiumGS/projects/1#card-64071615），这个原因我有天突然想明白了，对于Cesium官方来说，他们是希望Cesium For Unreal要集成到游戏里，而不是希望大家基于它再做个GIS可视化端。所以他们没有动力去改进这个。

好消息是我们实现了一个ESDynamicPawn，这里的ES是EarthSDK的简称。

把ESDynamicPawn 拖入场景中，Play之后，神奇的事情发生了：

鼠标左键按下可以拖拽

中键按下旋转，滚轮前后场景拉近拉远

鼠标右键位置不动视角旋转

可以看出这些操作和CesiumJS一模一样。

如果没效果，请检查你场景是不是有其他Pawn，或者把下面这个选项给设置上，再试下。

ESDynamicPawn是一个蓝图类，它派生自ESDefaultPawn 底层的处理我们使用c++实现的，这么做的意义是给大家提供了一个自定义的方式，在蓝图上可以修改具体的鼠标按键映射，比如把右键改平移，左键改旋转。这个对于熟悉蓝图的人，一看就懂。

0****2

对Cesium For Unreal上纯平地形的支持

CFU上相对CesiumJS，终于实现了地形和3dtiles数据调度的完美统一，地形也是通过Cesium3DTileset这个Actor来完成的。如果要加载地形数据，实际就需要一个地形服务的地址，Cesium的示例教程里都是连接ION的数据来演示，但是对于国内的开发环境来说，ION的数据服务是不靠谱的，有可能今天能访问，明天就不能访问了。这个地形出不来，导致附加在上面的影像也出不来。当然CesiumLab能帮大家快速的切一个地形服务出来，但是那也是需要一个tif数据做输入。

目前来说国内很多项目，用户对于影像的关注度远大于地形，影像足以反映周边环境了，另外由于地形数据精度比较差，如果我们在某个位置做了手工建模，这个地形的起伏反倒和手工模型有冲突，还需要平整，比较麻烦。那么能不能像CesiumJS一样，如果我没有地形数据，能出现一个纯平的地形呢？

官方CFU自然是没有这个功能的。

如果引用我们修改后的CFU，并且同时使用EarthSDK For UE之后，把ESObjectManager拖入到UE场景里。

然后你去把Cesium3DTileset的url设置为http://inner.earthsdk.com/layer.json ，神奇的事情就产生了，一个纯平地形有了，可以在上面叠加影像了，注意这个地址实际是一个虚拟的地址，我们内部截获了请求处理了相关逻辑，所以并不会真正从网络请求任何数据，或者说它是离线可用的。

还有一个更好玩的，如果你在西藏做项目，那里平均海拔都好几千米，你如果是用的纯平的0海拔的地形，如果你的模型或者倾斜之类的都在高空飘着，我们直接给这个url再增加一个参数，直接可以指定一个纯平高度，能尽量贴合你的数据http://inner.earthsdk.com/layer.json?h=5000

0****3

对Cesium For Unreal上XYZ影像的支持

CesiumJS有10多种ImageryProvider，但是在C4U上只有tms和wms两种服务的支持，另一种更基础的url模板的方式却没有支持，这是极大不方便的，因为在国内的实际项目里，大家都直接接入的在线的各种影像，比如天地图，高德，谷歌等，这些在线服务里一般虽然切片规范满足tms标准，但是没有提供 tilemapresource.xml 这个服务元数据的接口。

这个简单的问题，如果关注CesiumLab的用户都知道，我们CesiumLab很早就支持切换服务形式来提供这个tilemapresource.xml 的接口

即便如此，我们感觉还是不方便，对于天地图，高德，谷歌数据，能不能直接就从CFU里支持了？答案是肯定的，这次只要引入CFU 以及我们EarthSDK For Unreal插件，并且把ESSceneObjectManager拖入场景

然后设置你CesiumTileMapServiceRasterOverlay的url，设置为你喜欢的底图的XYZ的url模板，比如谷歌的数据：https://gac-geo.googlecnapps.cn/maps/vt?lyrs=s&x={x}&y={y}&z={z}，影像就显示了。

另外国内地图的问题：

1.天地图的xyz方式，依然需要token ，而且只支持web墨卡托方式的地址

2.高德地图的xyz方式，有火星偏移，大家慎用。

3.百度地图由于切片方式不符合标注web墨卡托，所以不能接入

对Cesium For Uneal缓存的开启控制

为了方便数据的二次加载，CFU提供了数据缓存机制，将请求到的数据保存到本地的cesium-request-cache.sqlite文件中。但是数据缓存机制也会带来一些问题，比如网络问题导致的数据请求不完整等。由于CFU并没有提供整体的缓存开启或关闭状态控制方式，我们在EarthSDKForUE中做了相关的实现。

首先，我们需要向UE场景中拖入一个ESSceneObjectManager对象。ESSceneObjectManager对象是EarthSDKForUE的一个总控对象，可以说EarthSDKForUE中的大部分实现都与它有关。我们将全局类型的属性都封装在这个对象上了。所以如果想正确地使用EarthSDKForUE的功能，需要保证场景中有且只有一个ESSceneObjectManager对象。

然后，在世界大纲视图中选中ESSceneObjectMananger对象，在下方细节面板中可以看到Cesium属性下有一个UseCache属性，可以通过勾选来控制是否使用CFU的缓存模式。

0****5

加载Glb模型

Cesium提供了直接加载Glb模型的方法，但是CFU没有提供单独的加载Glb模型的对象，这个问题在EarthSDKForUE中也得到了解决。

在世界大纲中选中ESSceneObjectManager对象，添加ESGLTFModel组件，在细节面板中可以看到ESGLTFModel组件的一些属性，将Glb模型的地址填写到Url属性中，设置好模型的位置和朝向，运行程序，就可以在指定位置上看到Glb模型了。这些属性在运行时修改同样会生效。

如果觉得指定一个位置和朝向放置模型这件事情比较困难，希望在运行时拖动或转动模型进行编辑，可以勾选Editing属性，如果当前的Position属性是（0，0，0）则会在鼠标前方显示一个绿色的圆形表示当前处于位置选择状态，此时点击场景中的任意位置，Glb模型和坐标架就会出现在该位置上。然后就可以进行编辑模式，鼠标右键单击可以切换编辑模式（位置编辑模式、朝向编辑模式、缩放编辑模式）。编辑到理想状态后可以双击鼠标左键或者勾掉Editing属性来结束编辑状态。

唯一性启动的设置

考虑到性能消耗和程序运行的稳定性和流畅度，打包给Windows大屏使用的UE程序最好是单实例运行。为了保证这一点，我们在EarthSDKForUE中实现了唯一性启动机制。打包完成的UE程序在启动第二个实例时，会自动关闭新实例，并将之前已经启动的实例窗口放大并显示到最前方，如果没能显示到最前方也会高亮该实例的工具栏图标，方便用于找到之前已经启动的实例。那么如何使用唯一性启动呢？

首先，向场景中拖入一个ESSinglTonActor对象，在世界大纲中选中该对象，在下方的细节面板中可以看到属性SingletonName。这是一个用于标识程序唯一性的名称，注意，不同的项目工程中这个属性的值一定要是不同的。否则会导致被识别为同一程序，进而只能启动一个实例。

然后，打包UE场景，如果需要使用唯一性启动，需要在运行exe程序时带上参数-essingleton，就可以保证程序的单实例运行了。如果不需要使用唯一性启动，直接启动程序，将不受程序唯一性验证的影响。

下载插件和安装步骤

下载地址以及二进制依赖库的设置

给大家说了这么多，有没有给大家种草。虽然我们没开源，但是可以免费用（运行后，屏幕下方有一个非常非常小的文字水印），我们只是宣称一个版权，如果真的好用，真的对大家有帮助，希望大家不要吝啬。

下载地址和版本更新历史，我们会提交到这个项目的ReadMe文件里：https://gitee.com/cesiumlab/ESForUE.git

另外，因为CFU和EarthSDK For Unreal都会依赖一些 Cesium Native的库，所以我们这部分库的二进制预编译包放到了一个固定项目里

UE4.27 下的地址：https://gitee.com/cesiumlab/espluginsthirdparty4.27

UE5下的地址（UE5版本我们目前还在测试，慎用）：https://gitee.com/cesiumlab/espluginsthirdparty5.1.git

把项目的二进制包下来之后，双击

设置成功会有提示。如果EarthSDK使用有问题，还是建议大家，手动确保下面的环境变量在windows上设置成功了。

插件引入项目方式

在你的UE项目的Plugins目录（如果项目里没有Plugins目录，那么需要手动建立一个）下放置这两个插件，注意这里的CesiumForUnreal 不能用官方版本，必须用我们修改后的版本源码（本文开头有git地址），EarthSDKForUE因为是二进制插件包，所以比较大，可能需要其他方式下载后，手动解压到这里。