开源模拟引擎esmini：从环境搭建到场景实践的全指南

如何快速搭建跨平台场景模拟环境？

作为一款轻量级的开源模拟引擎，esmini专注于解析和执行OpenSCENARIO格式的场景文件，为自动驾驶系统测试提供灵活的虚拟环境。本章节将通过三个核心步骤，帮助你在不同操作系统上快速部署esmini开发环境。

环境准备三步骤

1. 获取源代码

   git clone https://gitcode.com/gh_mirrors/es/esmini
   cd esmini
   

   [!NOTE] 确保本地已安装Git工具和C++编译环境。Windows用户需额外安装Visual Studio 2019或更高版本。

2. 配置构建系统

   cmake -S . -B build
   

   该命令会在项目根目录创建build文件夹，并生成适合本地环境的构建配置。

3. 编译项目

   cmake --build build --config Release
   

   编译过程可能需要5-10分钟，具体时间取决于硬件配置。成功编译后，可执行文件将生成在build/bin目录下。

项目核心目录解析

目录路径	功能描述	常用操作
EnvironmentSimulator/Applications	应用程序入口	运行esmini、odrviewer等可执行文件
scripts	辅助脚本集合	执行generate_osg_libs.sh生成依赖库
run	场景运行脚本	使用run_cut-in.bat快速启动示例场景
code-examples	代码示例	学习hello_world了解基础API使用
Unittest/xosc	测试场景	验证引擎对不同场景的支持能力

从零开始创建第一个OpenSCENARIO场景

OpenSCENARIO（场景描述标准）是esmini的核心输入格式，通过XML语法定义交通参与者、环境条件和事件逻辑。本章节将通过一个简单的车辆变道场景，展示如何从零开始构建可执行的模拟场景。

场景文件基础结构

一个完整的OpenSCENARIO文件包含以下核心元素：

• Entities：定义参与场景的交通参与者
• Storyboard：描述场景事件的时间序列
• RoadNetwork：指定场景使用的道路网络数据

简易变道场景实现

1. 创建基础场景文件 在项目根目录下创建my_first_scenario.xosc文件，添加基本XML结构：

   <?xml version="1.0" encoding="UTF-8"?>
   <OpenSCENARIO xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="OpenSCENARIO.xsd">
     <RoadNetwork>
       <LogicFile filepath="code-examples/follow_reference/follow_reference.xodr"/>
     </RoadNetwork>
     <Entities>
       <ScenarioObject name="Ego">
         <Vehicle>
           <ParameterDeclarations>
             <ParameterDeclaration name="maxSpeed" value="100"/>
           </ParameterDeclarations>
         </Vehicle>
       </ScenarioObject>
     </Entities>
     <!-- 此处添加Storyboard内容 -->
   </OpenSCENARIO>
   

2. 添加场景行为逻辑 在Storyboard节点中添加车辆变道动作：

   <Storyboard>
     <Init>
       <Actions>
         <PrivateAction object="Ego">
           <TeleportAction>
             <Position>
               <RoadPosition roadId="1" s="50" t="0" laneId="1"/>
             </Position>
           </TeleportAction>
         </PrivateAction>
       </Actions>
     </Init>
     <Story name="LaneChangeStory">
       <Act name="LaneChangeAct">
         <ManeuverGroup name="LaneChangeManeuverGroup" maximumExecutionCount="1">
           <Maneuver name="LaneChangeManeuver">
             <Event name="LaneChangeEvent" priority="overwrite">
               <Action name="LaneChangeAction">
                 <PrivateAction object="Ego">
                   <LaneChangeAction targetLaneId="2" duration="3"/>
                 </PrivateAction>
               </Action>
             </Event>
           </Maneuver>
         </ManeuverGroup>
       </Act>
     </Story>
   </Storyboard>
   

3. 运行场景

   ./build/bin/esmini --osc my_first_scenario.xosc
   

   执行后将看到车辆从初始车道平稳变道至目标车道的模拟效果。

[!NOTE] 如果出现"无法找到道路文件"错误，请检查xodr文件路径是否正确。可使用项目提供的code-examples/follow_reference/follow_reference.xodr作为测试道路网络。

📊 完成度：2/4

如何利用高级控制器实现复杂驾驶行为？

esmini提供了多种内置控制器，支持模拟不同驾驶行为和交通场景。本章节将深入探讨如何配置和使用这些控制器，实现从简单的定速巡航到复杂的自动紧急制动等高级功能。

控制器类型及应用场景

控制器名称	适用场景	核心参数
ControllerACC	自适应巡航控制	跟车距离、最大减速度
ControllerALKS	自动车道保持	车道居中精度、响应时间
ControllerFollowGhost	轨迹跟踪	路径点列表、速度曲线
ControllerHID	人机交互控制	键盘/手柄输入映射

自适应巡航控制(ACC)场景配置

1. 创建ACC场景文件

   <ScenarioObject name="Ego">
     <Vehicle>
       <Controller name="ACCController" type="ACC">
         <ParameterDeclarations>
           <ParameterDeclaration name="targetDistance" value="50"/>
           <ParameterDeclaration name="timeGap" value="1.5"/>
           <ParameterDeclaration name="maxSpeed" value="100"/>
         </ParameterDeclarations>
       </Controller>
     </Vehicle>
   </ScenarioObject>
   

2. 配置前置车辆

   <ScenarioObject name="LeadVehicle">
     <Vehicle>
       <Controller name="LeadController" type="SloppyDriver">
         <ParameterDeclarations>
           <ParameterDeclaration name="speed" value="60"/>
         </ParameterDeclarations>
       </Controller>
     </Vehicle>
   </ScenarioObject>
   

3. 运行ACC场景

   ./build/bin/esmini --osc code-examples/hello_world/acc_with_external_controller.xosc
   

   该命令将启动一个包含主车和前置车的场景，演示ACC系统如何根据前车速度自动调整本车速度。

多控制器协作案例

在复杂场景中，可同时启用多个控制器并设置优先级：

<Controller name="PrimaryController" type="ALKS" priority="1"/>
<Controller name="SecondaryController" type="UDPDriver" priority="2"/>

当UDPDriver接收到外部控制指令时，将临时覆盖ALKS控制器的决策，实现外部干预功能。

如何优化模拟性能与可视化效果？

esmini提供了丰富的配置选项，帮助用户在模拟精度、运行性能和可视化质量之间取得平衡。本章节将介绍实用的优化技巧和高级配置方法。

性能优化参数调整

通过命令行参数调整模拟性能：

./build/bin/esmini --osc scenario.xosc --fixed_timestep 0.01 --disable_rendering

参数	功能	优化效果
--fixed_timestep	设置固定时间步长	步长越小精度越高但性能消耗大
--disable_rendering	禁用图形渲染	CPU占用降低约60%
--headless	无头模式运行	适合服务器端批量测试
--osg_anti_aliasing	抗锯齿级别	0-4，0为禁用

高级可视化配置

修改配置文件config.yml自定义渲染效果：

viewer:
  width: 1280
  height: 720
  fullscreen: false
  camera_position: [0, -50, 10]
  camera_target: [0, 0, 0]
  draw_road_edges: true
  draw_lane_marks: true
  draw_signs: true
  draw_buildings: false

[!NOTE] 禁用建筑物渲染可显著提升复杂场景的帧率，特别适合包含城市环境的大型场景。

数据记录与分析

启用数据记录功能捕获模拟过程：

./build/bin/esmini --osc scenario.xosc --record data.log --record_osi

生成的日志文件可通过scripts/osi2csv.py转换为CSV格式，用于后续分析：

python scripts/osi2csv.py data.log -o analysis.csv

📊 完成度：4/4

常见问题解决方案

编译错误：缺少OpenSceneGraph依赖

解决方案：执行scripts/generate_osg_libs.sh自动下载并编译依赖库

场景加载失败："Invalid OpenSCENARIO file"

解决方案：使用scripts/run_schema_comply.py验证文件格式：

python scripts/run_schema_comply.py scenario.xosc

性能问题：模拟帧率低于10fps

解决方案：

1. 降低视窗分辨率：--window 100 100 800 600
2. 简化场景复杂度：减少交通参与者数量
3. 使用低精度物理引擎：--physics_engine simplified

通过以上方法，大多数常见问题都能得到有效解决。如需进一步帮助，可参考项目中的docs/目录文档或提交issue获取社区支持。