esmini：开源自动驾驶场景引擎全攻略

esmini 是一款轻量级开源场景引擎，专注于解析和执行 OpenSCENARIO 标准（ISO 18388）定义的自动驾驶测试场景。作为开发者友好的工具包，它支持道路网络建模、交通参与者行为模拟及传感器数据生成，为自动驾驶算法测试提供标准化虚拟环境。

探索核心价值：为什么选择 esmini？

项目定位与应用场景

如何为自动驾驶系统构建标准化测试环境？esmini 提供了从场景定义到动态执行的完整解决方案。其核心价值体现在：

• 场景标准化：严格遵循 OpenSCENARIO/OpenDRIVE 标准，确保测试用例的可移植性
• 轻量级架构：无需依赖重型游戏引擎，核心库体积小于 5MB
• 多语言支持：提供 C++ 原生 API 及 Python/ROS 接口，适配不同开发栈
• 实时可视化：内置基于 OpenSceneGraph 的 3D 渲染模块，支持场景调试与演示

技术架构解析

esmini 采用模块化设计，主要由五大功能模块构成：

esmini
├── 核心引擎层
│   ├── RoadManager：道路网络数据管理
│   └── ScenarioEngine：场景逻辑执行
├── 交互控制层
│   ├── Controllers：车辆行为控制算法
│   └── ViewerBase：可视化渲染系统
└── 接口适配层
    ├── esminiLib：跨语言调用接口
    └── esminiROS：机器人操作系统适配

常见问题速查表

问题	解决方案
场景文件解析失败	检查 XML 格式规范性，使用 scripts/run_schema_comply.py 验证
可视化窗口卡顿	降低渲染分辨率：--window 0 0 800 600
第三方控制器集成困难	参考 code-examples/follow_reference 示例实现 UDP 通信

快速上手：3分钟启动你的第一个场景

零基础环境搭建

如何在Linux系统快速部署esmini？只需三步：

1. 获取源码

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

2. 编译项目 💡 确保已安装 CMake 3.10+ 和 OpenGL 开发库

mkdir build && cd build
cmake ..
make -j4

3. 验证安装

./bin/esmini --version

场景运行实战

如何加载并运行示例场景？以高速公路换道场景为例：

1. 执行预定义场景

./bin/esmini --osc ../EnvironmentSimulator/Unittest/xosc/highway_split.xosc

2. 关键参数解析

--window x y width height  # 设置窗口位置和尺寸
--headless                 # 无界面模式运行（用于CI测试）
--record                   # 记录仿真数据到CSV文件

3. 交互控制

• W/S：控制主车加速/减速
• A/D：控制方向盘转向
• ESC：退出仿真

常见问题速查表

问题	解决方案
编译缺少依赖	执行 sudo apt install libglfw3-dev libopenscenegraph-dev
场景文件找不到	使用绝对路径或确保工作目录正确
控制器无响应	检查 --controller 参数是否正确指定

深度探索：从场景定义到算法测试

解析配置文件：从参数到场景

OpenSCENARIO 文件如何描述复杂交通场景？以 highway_merge.xosc 为例，核心结构包括：

<Scenario>
  <RoadNetwork>                   <!-- 道路网络定义 -->
    <LogicFile filepath="highway.xodr"/>
  </RoadNetwork>
  <Entities>                      <!-- 交通参与者定义 -->
    <Vehicle name="Ego" controller="External"/>
    <Vehicle name="Lead" controller="FollowRoute"/>
  </Entities>
  <Storyboard>                    <!-- 场景事件逻辑 -->
    <Story>
      <Act name="MergeAct">
        <ManeuverGroup>
          <Maneuver name="MergeManeuver">
            <LaneChangeAction targetLane="-1"/>
          </Maneuver>
        </ManeuverGroup>
      </Act>
    </Story>
  </Storyboard>
</Scenario>

💡 提示：使用 tools/osc-validator 工具可验证场景文件语法正确性

扩展开发：自定义控制器

如何开发符合项目需求的车辆控制器？

1. 创建控制器类

#include "Controller.hpp"

class MyController : public Controller {
public:
  void Update(double dt) override {
    // 实现自定义控制逻辑
    vehicle->SetSpeed(desired_speed);
  }
};

2. 注册控制器

REGISTER_CONTROLLER(MyController, "MyController")

3. 编译与使用

cmake -DCMAKE_BUILD_TYPE=Debug ..
make
./bin/esmini --osc scenario.xosc --controller MyController

常见问题速查表

问题	解决方案
控制器接口文档缺失	参考 Libraries/esminiLib/esminiLib.hpp 头文件
自定义参数无法传递	使用 <ParameterDeclarations> 标签定义场景参数
仿真步长不匹配	通过 --dt 参数调整仿真时间步长

进阶路径图：从入门到专家

初级：场景创建与运行

• 掌握 OpenSCENARIO 基础语法
• 使用 scenario_scripts/generate_traffic.py 创建随机交通流
• 熟悉 run/ 目录下的批处理脚本

中级：功能扩展与集成

• 开发自定义传感器模型（参考 code-examples/ideal-sensors）
• 集成 ROS 系统（使用 Libraries/esminiROS 模块）
• 实现场景自动化测试（结合 test/smoke_test.py）

高级：性能优化与部署

• 研究 ScenarioEngine 模块的并行化改造
• 优化渲染性能（调整 ViewerBase 中的LOD参数）
• 构建场景数据库与版本管理系统

通过这套系统学习路径，开发者可逐步掌握从场景编辑到自动驾驶算法测试的全流程应用，充分发挥 esmini 在自动驾驶研发中的价值。