手把手超详细介绍MATLAB+RoadRunner+Unreal Engine自动驾驶联合仿真

什么大师特

RoadRuner是MathWorks新收购的自动驾驶场景构建工具，Unreal Engine是商业游戏引擎。RoadRunner创建驾驶场景，导入到Unreal Engine，与Simulink联合仿真。这种方法兼具RoadRunner创建场景之便捷性和Unreal Engine渲染的高保真度。
之前的文章，已经介绍了RoadRunner这个工具的一些特点。
也有文章介绍了RoadRunner在自动驾驶仿真领域的实战应用。
但还没有文章详细介绍MATLAB+RoadRunner+Unreal Engine这三个软件具体怎么操作实现联合仿真。整个联合仿真的操作流程，几乎都可以在MATLAB帮助文档中找到。但笔者在亲身实践的过程中发现，即便有详细的帮助文档，但依然有一些坑，在MathWorks Support团队的支持下，总算趟完了这些坑，顺利地实现了整个流程。本文将手把手、一步步地详细说明这个联合仿真的过程。
MATLAB刚收购RoadRunner没多久，所以目前联合仿真对软件版本的匹配是有一定要求的。笔者采用的是MATLAB R2020a+RoadRunner+Unreal Engine4.23。
1.   电脑软硬件要求


软件要求：

Windows 64-bitplatformUnreal Editor 4.23Visual Studio 2017or higherMicrosoft DirectX —— If this software is not already installedon your machine and you try to simulate in the 3D environment, Vehicle DynamicsBlockset prompts you to install it. Once you install the software, you mustrestart the simulation.Automated DrivingToolbox Interface for Unreal Engine 4 Projects，详见3.1

最低硬件要求：

Graphics card (GPU)— Virtual reality-ready GPU with 8 GB of onboard RAMProcessor (CPU) —2.60 GHzMemory (RAM) — 12 GB

如果要获得流畅的仿真效果，建议配置高性能显卡。以上信息，引自以下链接中的Support Package for Customizing Scenes（无需关注此链接中其他内容）。
2. 安装基础软件

MATLAB和VS的安装顺序没有特别要求。VS需在Ureal Engine之前安装，否则有可能Unreal的.uproject文件没法找到VS进行编译。
2.1 安装Visual Studio2017
参照以下链接。
设置虚幻引擎的Visual Studio
请确保在工作量（Workloads）下选择“用C++开发游戏（Game developmentwith C++）”。在右侧的摘要（Summary）工具栏中，展开用C++开发游戏（Game development with C++），并勾选可选（Optional）下的虚幻引擎安装程序（Unreal Engine installer）。注意，不要勾选Windows 10 SDK (10.0.17763.0)。
另外，如果用户需要使用Simulink Real-Time工具箱，需要同时参照以下链接。
2.2 安装MATLAB R2020a
必备工具箱是Automated Driving Toolbox和Vehicle Dynamics Blockset。并使用mex -setup命令将MATLAB的编译器设置成VS2017。
2.3 安装Unreal Engine4.23
进入Unreal Engine官网，点击右上角的下载，注册账号，下载Epic Games Launcher并安装。
登陆Epic Games Launcher，在“库”界面中选择Unreal Engine 4.23并安装。
安装完成后，可在上图界面启动Unreal Editor 4.23。
2.4 安装RoadRunner和RoadRunner Asset Library
用正版或者申请试用版，点击以下链接可申请试用版。
点击以下链接，查看RoadRunner和RoadRunnerAsset Library的下载安装指南。
我们以Windows平台下的individual license为例，加以说明。在MathWorks官网个人账户的my account中，查看License。
点击上图中RoadRunner的license，在以下界面Download Products。
点击Manage Users→Add User。
Add User中设置邮箱和姓名等信息。接着Intall and Activate→Activate。
在下图界面中填写即将安装RoadRunner的电脑的一些信息。

Host ID——MAC地址或C盘序列号

如使用C盘序列号，在Windows command prompt中执行vol c:获得信息。

Computer Login Name

在Windows command prompt中执行set username获得信息。

Activation Label——自行定义

提交上述信息后，网站会生成一个包含上述信息的RoadRunner license文件，将它下载到电脑中。最后安装之前下载的程序，当提示输入license文件时，选择上一步下载的license文件。此时，已完成安装和激活工作。
3. 安装插件

注意：完成上述步骤后，再装插件。
3.1 安装MATLAB的Unreal支持包和Unreal的MathWorks插件
参见
打开MATLAB的Add On/附加功能界面。
在界面中搜索unreal。
点开上图红框链接（Automated Driving ToolboxInterface for Unreal Engine 4 Projects），选择安装。
安装完成后，需要在MATLAB中执行以下代码。
supportPackageFolder= fullfile( ...
   matlabshared.supportpkg.getSupportPackageRoot, ...
"toolbox","shared","sim3dprojects","driving");
localFolder = "C:\Local";


projectFolderName= "AutoVrtlEnv";
projectSupportPackageFolder= fullfile(supportPackageFolder,projectFolderName);
projectLocalFolder= fullfile(localFolder,projectFolderName);
if~exist(projectLocalFolder,"dir")
   copyfile(projectSupportPackageFolder,projectLocalFolder);
end


ueInstallFolder= "C:\Program Files\Epic Games\UE_4.23";


supportPackageFolder= fullfile( ...
   matlabshared.supportpkg.getSupportPackageRoot, ...
"toolbox","shared","sim3dprojects","driving");


mwPluginName = "MathWorksSimulation.uplugin";
mwPluginFolder =fullfile(supportPackageFolder,"PluginResources","UE423");
uePluginFolder =fullfile(ueInstallFolder,"Engine","Plugins");
uePluginDestination= fullfile(uePluginFolder,"Marketplace","MathWorks");


cd(uePluginFolder)
foundPlugins =dir("**/" + mwPluginName);


if~isempty(foundPlugins)
    numPlugins = siz(foundPlugins,1);
    msg2 = cell(1,numPlugins);
    pluginCell = struct2cell(foundPlugins);


    msg1 = "Plugin(s)already exist here:" + newline + newline;
for n = 1:numPlugins
        msg2{n} = "    " + pluginCell{2,n}+ newline;
end
    msg3 = newline + "Please removeplugin folder(s) and try again.";
    msg = msg1 + msg2 + msg3;
    warning(msg);
else
    copyfile(mwPluginFolder,uePluginDestination);
    disp("Successfullycopied MathWorksSimulation plugin to UE4 engine plugins!")
end


以上代码引自以下链接的Set Up Scene Customization UsingSupport Package。
值得注意的是：

localFolder ="C:\Local"，该路径可自行设定，上述代码会把支持包自带的Unreal工程拷贝到该文件夹。ueInstFolder ="C:\Program Files\Epic Games\UE_4.23"，此处是指明Unreal Engine 4.23的安装路径。如果您的安装路径不是C:\ProgramFiles\Epic Games\UE_4.23，需要调整成实际路径。

执行结束后，会有两个现象：
① localFolder中出现支持包自带的Unreal工程。
② Unreal Editor中出现MathWorks插件。在Unreal Editor中点击“编辑”→“插件”可进行查看。
3.2 新建Unreal工程，安装Unreal的RoadRunner插件
引自：
打开Unreal，设置项目文件夹和项目名称后，创建一个项目，如下图。
创建项目后，项目文件夹如下图。注意，路径中不要出现空格。
在该路径下新建一个Plugins文件夹。
接着，点击以下链接，下载Unreal的RoadRunner插件。
将插件文件夹中的RoadRunnerImporter和RoadRunnerMaterials文件夹（如下图）都复制到上图的Plugins文件夹中。每个unreal工程都得拷贝一次，否则roadrunner导出的信息没法加载到Unreal。
然后，右键刚才新建的unreal 工程demo1.uproject，点击Generate Visual Studio project files。之后，双击打开demo1.uproject，在弹出的窗口中选择“是”。引自
在弹出Unreal Editor中，可以在“编辑”→“插件”中查看到Unreal已经加载了RoadRunner的插件。
4. RoadRunner的场景导出到Unreal

参见：
我们以RoadRunner自带的FourWaySignal场景为例，将它导出到Unreal。
4.1 将RoadRunner场景导出成文件
打开RoadRunner，新建场景/New Scene。在RoadRunner界面中，“File”→“Open Scene”选择打开自带的场景文件FourWaySignal.rrscene（如下图）。
选择“File”→“Export”→“Unreal (.fbx + .xml)”。
设定导出的目标文件夹和文件名，如下图。
导出完成后，目标文件夹中就包含了导出的文件。
4.2 将导出文件加载到Unreal
打开Unreal Editor，在内容浏览器中点击“导入”。
选择4.1中Exports文件夹中的fbx文件。
接着，导入的设置。设置界面如下图。
具体如何设置，参考以下链接。导入完成后，注意保存，保存时设置MAP名称。
5. MATLAB与UnrealEditor联合仿真联合仿真

Unreal的场景能以两种形式与MATLAB联合仿真：
① Unreal Editor直接运行场景，联合仿真时需要打开Unreal Editor
② Unreal场景导出成可执行文件（exe），联合仿真时无需打开Unreal Editor
此节介绍第一种方式。
5.1 从MATLAB打开Unreal Editor
引自:
如果直接在Unreal Editor中打开项目文件，则MATLAB和Simulink不会与Unreal Editor建立连接，因此也将无法联合仿真。需要从MATLAB打开Unreal Editor。
双击Simulink模型的Simulation 3D SceneConfiguration模块，将Scene source参数设置为Unreal Editor。在Project参数中，浏览到包含场景的项目文件。
单击“Open Unreal Editor”，Unreal Editor将打开并从您的项目中加载场景。
第一次从MATLAB打开Unreal Editor时，可能会要求您重新编译UE4Editor DLL文件，点击“Yes”以重新编译。
当UnrealEditor打开时，您可以忽略有关名称“_BuiltData”加载失败的文件的所有警告消息。
如果您收到“the lighting needs to be rebuilt”的警告，请从Unreal Editor窗口上方的工具栏中，选择“Build”→“Build Lighting Only”。首次打开场景或向场景中添加新元素时，Unreal Editor会发出此警告。
另外，如果是自定义的场景，单击“Open Unreal Editor”后，在出现的Unreal Editor中需要重设蓝图父项，具体操作如下。
If this is your first time opening a customproject in Unreal Editor 4.23, you may need to associate, or reparent, thisproject with the Sim3dLevelScriptActor level blueprint used in Vehicle DynamicsBlockset. The level blueprint controls how objects interact once placed withinin the Unreal environment. If you do not reparent the project to this levelblueprint, the simulation returns an error.
To reparent the level blueprint:
In theUnreal Editor toolbar above the editor window, select Blueprints > OpenLevel Blueprint.
In theLevel Blueprint window, select File > Reparent Blueprint.
Click theSim3dLevelScriptActor blueprint and close the Level Blueprint window.
If you do not see this blueprint, make surethat you have the MathWorksSimulation plugin installed and enabled.
Navigate back to the editor window. In thetoolbar above this window, select Settings > Plugins.
In the Plugins window, verify that theMathWorks Interface plugin appears. This plugin refers to theMathWorksSimulation.uplugin file that you copied into your local Unreal Editorinstallation from the Vehicle Dynamics Blockset Support Package for UnrealEngine 4 Projects.
If you editor installation includes theplugin, then when you open a project in the editor for the first time, you areprompted to enable this plugin. If you do not see the MathWorks Interfaceplugin in this window, repeat the steps under and reopen the editor fromMATLAB.
Select the Enabled check box.Close the editor, reopen it from MATLAB, andrepeat the steps to reparent the blueprint.
实际操作步骤如下：
如果没找到名为Sim3dLevelScriptActor的蓝图，那要先确认Unreal是否启用了MathWorks插件。查看插件的方式，3.1有说明，正常的状态如下图。
5.2 联合仿真
在UnrealEditor中可以通过数字键切换视角，如下图。
对于自定义的场景，如果也要实现这个功能，需要把DefaultInput.ini从如下路径
C:\ProgramData\MATLAB\SupportPackages\<MATLABRelease>\toolbox\shared\sim3dprojects\driving\AutoVrtlEnv\Config
拷贝到下面的路径
<uproject路径>\Config
确保Simulation 3D Scene Configuration模块的Scene source参数设置为Unreal Editor，Project参数设置为需要联合仿真的场景文件。
先在Simulink中单击运行模型，等待DiagnosticViewer窗口显示以下确认消息：
In the Simulation 3D SceneConfiguration block, you set the scene source to 'Unreal Editor'.
In Unreal Editor, select'Play' to view the scene.
然后在Unreal Editor中点击播放/Play。
6. MATLAB与Unreal可执行文件联合仿真

Unreal场景打包成可执行文件（exe）进行联合仿真，联合仿真时无需打开Unreal Editor。引自：
操作步骤：
1. 在Simulation3D Scene Configuration模块，将Scene Source设置为Unreal Editor，选择要打包的uproject，点击“Open Unreal Editor”打开该uproject。同时确保已经如步骤5.1中所述重设了父蓝图（如果直接打包exe，而未进行unrealeditor形式的联合仿真，容易疏漏这一步）。
2. 建议先把Unreal Editor的语言设置为English，在Unreal Editor工具栏的编辑→编辑器偏好设置→区域和语言。然后，在Unreal Editor中选择Setting→Project Settings→Packaging，做以下设置。
3. 在List of maps toinclude in a packaged build中，点击“+”添加要打包的Map（Map是指步骤4.2中保存的Map），如下图。
红框中的路径很重要，之后在Simulink中会用到。
4. 回到Unreal Editor主界面，点击Build→Build Lighting Only。
If you do notrebuild the lighting, the shadows from the light source in your executable fileare incorrect and a warning about rebuilding the lighting displays duringsimulation.
5. (Optional) If you plan to semantic segmentation data from the sceneby using a Simulation 3D Camera block, enable rendering of the stencil IDs. Inthe left pane, in the Engine section, click Rendering. Then, in the mainwindow, in the Postprocessing section, set Custom Depth-Stencil Pass to Enabledwith Stencil. For more details on applying stencil IDs for semanticsegmentation, see Apply Semantic Segmentation Labels to Custom Scenes.
当需要用自动驾驶工具箱的摄像头模型输出语义分割图时才需要执行这一步。
6. 关闭Project Settings，在Unreal Editor主界面中点击File > Package Project > Windows > Windows (64-bit)，选择一个合适的路径，将exe打包到该路径。打包时间长短主要取决于电脑性能和场景的复杂程度。

注意：在建议在打包之前，建议确保完成以下操作，否则exe模式下操作UE4窗口不便。
把DefaultInput.ini从如下路径
C:\ProgramData\MATLAB\SupportPackages\<MATLABRelease>\toolbox\shared\sim3dprojects\driving\AutoVrtlEnv\Config
拷贝到下面的路径
<uproject路径>\Config
7. 打包完成后，在对应路径下会生成对应的exe文件，如下图。
8. 回到Simulink模型，在Simulation 3D Scene Configuration模块，将Scene Source设置为Unreal Executable，File name选择成步骤7中生成的exe文件，Scene设置为步骤3红框中的路径。
9. 在Simulink中运行模型，运行后场景界面会自动打开。

10. 默认情况下，场景是以全屏的方式打开的，如果想把场景以窗口模式打开，可以执行操作：在打包文件路径下的WindowsNoEditor\工程名\Saved\Config\WindowsNoEditor找到GameUserSettings.ini文件，打开该文件：把所有以mode结尾的参数（红色框）都设置成2；分辨率设置（蓝色框）要低于你所用电脑的分辨率。
注：第一次打开WindowsNoEditor\工程名时可能找不到Save的文件夹，可以先联合仿真一次，然后Saved文件夹会自动生成。