做自动驾驶规划控制的人早晚会撞上一个很尴尬的场面算法在自己搭的仿真里跑得漂漂亮亮换一份别人给的场景数据立刻原形毕露。问题往往不在算法本身而在数据——地图格式不一样、障碍物表示不一样、时间步长不一样、坐标系定义不一样你的轨迹在别人的数据上根本没法复现更别提横向对比谁的规划器更好。CommonRoad就是冲着这个痛点来的它用一套统一的 XML 格式把交通场景固定下来再配上一整套读取、可视化、转换、评测的 Python 工具链让不同团队做出来的规划器能在同一批场景上跑同一条赛道。这篇内容我会把 CommonRoad 是什么、由哪些部分组成、安装过程中每一步为什么这么做讲透最后给出一套能直接抄的安装与验证流程以及我踩过的那些坑。不管你是刚入门自动驾驶的学生还是需要给 ADAS 功能做场景化验证的工程师都能从里面拿到能用的东西。需要先说清楚一点CommonRoad 不是仿真器它不做物理引擎那套碰撞、轮胎、悬架的计算它管的是场景这件事——场景怎么描述、怎么读、怎么画、怎么在不同格式之间倒腾、怎么用它来打分。搞清楚这个定位后面安装哪几个包、装完之后能干什么逻辑就顺了。1. CommonRoad 到底是个什么东西1.1 从仿真里跑得通车上不敢跑这个老问题说起做规划控制验证最贵的是实车路测最不靠谱的是纯随机仿真最有用的是带真实交互的场景回放。可现实是场景数据的来源极度分散有的是从自然驾驶数据集里切出来的片段有的是从交通仿真软件里导出的路网有的是人工照着事故报告手绘的。这三类数据各说各话前者的坐标系可能是经纬度后者可能是局部笛卡尔时间步长从 0.01 秒到 1 秒都有。你想把三份数据放到同一个评测脚本里跑光是写格式转换就够喝一壶。CommonRoad 的做法是把场景抽象成一个与具体仿真器解耦的中间层。一个场景文件描述的是某一时刻某条路上有哪些车道、哪些车、哪些交通标志其中某一辆车的初始状态是什么、要去哪里。这个描述是纯几何和纯运动学的不绑定任何动力学模型。于是你用什么车辆模型去跑这条轨迹是你的自由而场景本身的描述是所有人共享的。它的核心价值可以归成三条。第一统一的场景描述格式让数据可以跨团队流转第二完整的工具链读、写、画、转、评测都有现成轮子不用自己造第三公开的基准与场景集你的算法跑出来的指标能跟别人比。这三条里第一条是地基后两条是让它真正被学术界和工业界用起来的原因。1.2 场景格式、工具链、基准评测三件套各管什么很多人第一次接触会被一堆仓库名绕晕其实按功能分层看就很清楚。场景层是数据本身。一个 CommonRoad 场景文件是 XML里面主要有几块内容车道网络lanelet network用左右边界点列描述每条车道并记录前后继、左右相邻关系、静态障碍物比如停在路边的车、隔离墩、动态障碍物带初始状态和轨迹的其他车辆、交通标志与信号灯、以及规划问题planning problem包含自车的初始状态和一个目标区域。你拿着这个文件就能完整复现一个交通片段。工具层是围绕这个格式的一堆 Python 包。最核心的是commonroad-io负责读写、可视化、坐标变换、场景修补commonroad-scenario-designer负责生成和转换场景能把 SUMO 路网、OpenDRIVE、Lanelet2 等格式互转commonroad-vehicle-models提供几种常用的车辆运动学/动力学模型比如单轨模型、点质量模型commonroad-route-planner做路径和路线规划commonroad-drivability-checker用一个 C 后端高效判断某个位姿是否落在可行驶区域内这是做碰撞和越界检查的关键再往上还有commonroad-reach可达集计算、commonroad-crime临界性度量用来量化场景有多危险、以及和各种仿真器的桥接包。基准层是评测。CommonRoad 会维护若干场景集按难度和场景类型分类比如手绘场景、车辆模型相关场景、交互密集场景等并提供统一的评测脚本和指标。这部分的意义在于你不需要自己定义什么叫规划得好照着官方指标跑就行。提示如果你只是想快速上手看看效果装commonroad-io加一个场景文件就够了其他包属于按需索取。一上来就把所有仓库 clone 下来大概率会在依赖编译上浪费一整天。1.3 什么人适合花时间啃它说句实在话CommonRoad 不是给所有人准备的。它对你有没有用取决于你在链条上的位置。如果你在做轨迹规划或运动规划的算法研究那它几乎是绕不开的论文里常见的做法就是在 CommonRoad 场景集上跑然后比成功率、舒适度、计算耗时。你不装它就没法跟别人对话。如果你在做ADAS 或自动驾驶功能验证需要拿一批典型场景去压测自己的控制器那它可以当你的场景数据源和回放框架。它的场景是几何级别描述不绑定动力学正好适合你把自家的车辆模型塞进去跑。如果你在做场景生成或者数据集处理commonroad-scenario-designer那套格式转换能力比你自己写解析器靠谱得多尤其是 OpenDRIVE 和 Lanelet2 这类格式自己解析一遍就是几个月的坑。如果你只是想入门自动驾驶、找个能跑起来的小项目练手它也算合适因为安装门槛不算高而且跑通加载和可视化只要几十行代码反馈很直观。但要注意它不教你怎么写规划器它只给你数据和工具。2. 装之前先把环境理清楚2.1 Python 版本怎么选为什么不能随手装个最新的这是我在这个环节见过最多的翻车点有人图省事直接去官网下了最新版 Python装完pip install commonroad-io一路报错然后怀疑人生。原因不复杂。CommonRoad 的依赖里有一批是带 C 扩展的包比如numpy、shapely、lxml这些包在 PyPI 上分发的是预编译好的 wheel也就是已经编译好的二进制包。某个特定版本组合下官方才会为某个 Python 版本提供对应平台的 wheel。你装了一个太新的 Pythonwheel 还没跟上pip 就只能退回去下源码包自己编译。而在 Windows 上编译这些 C 扩展需要装 Visual C 构建工具一编译就是十几分钟还随时可能因为缺个编译标志失败。我的建议是用 3.9 或 3.10这两个版本在科学计算生态里的 wheel 覆盖最完整踩坑概率最低。如果你手头项目对版本没强约束就选这两个不要逞强上新版本。装的时候顺手把 pip 升级到较新版本老版本 pip 在解析依赖时容易出现解析得很慢或者解出错误组合的问题。python --version # 输出确认在 3.9.x 或 3.10.x python -m pip install --upgrade pip setuptools wheel再有一条经验别用系统自带的 Python。macOS 自带的、Linux 发行版自带的 Python 往往跟系统组件绑定你往里面装包轻则污染重则搞坏系统工具。要么用 pyenv、要么用 conda、要么老老实实建虚拟环境。2.2 底层依赖到底有哪些谁在拖后腿commonroad-io自身的依赖不算夸张但每个都有明确用途理解它们能帮你在报错时快速定位。依赖包主要作用常见坑点numpy所有点列、状态向量的底层数组版本过高时与其他包不兼容scipy插值、积分、空间变换通常跟随 numpy 版本联动matplotlib场景可视化渲染后端配置不对会直接崩在 importlxml解析 CommonRoad XML需要 libxml2容器里常缺shapely几何计算如点在多边形内2.x 与 1.x API 有破坏性变更networkx车道拓扑图的路径搜索大场景下内存占用明显pillow图像导出一般无坑commonroad-vehicle-models车辆模型与 io 版本需匹配重点说两个。matplotlib的坑在于如果你在无图形界面的服务器上跑代码默认后端有些版本是 TkAgg 之类会因为找不到显示设备而报错。解决办法是在 import pyplot 之前先设置非交互后端import matplotlib matplotlib.use(Agg) import matplotlib.pyplot as plt这样绘图只出文件不弹窗适合在服务器或者 Docker 里批处理。shapely的坑在于2.0 版本做了一轮 API 清理一些老代码里的调用方式被移除如果你同时装了别的依赖老版本 shapely 的包pip 会陷入两难这时候手动锁版本比让它自己解析更快。2.3 虚拟环境venv 和 conda 的选择与实操虚拟环境这一步我建议不要省。理由很简单CommonRoad 对科学计算包的版本有要求你机器上如果已经装了另一个项目的 numpy两者很容易打架。虚拟环境把依赖隔离在项目目录里出问题直接删掉重来成本极低。用标准库自带的 venv最轻量# 新建环境 python -m venv .venv # 激活Linux / macOS source .venv/bin/activate # 激活Windows PowerShell .venv\Scripts\Activate.ps1 # 激活成功后再升级 pip python -m pip install --upgrade pip如果你机器上已经有 Anaconda 或 Miniconda用 conda 建环境也行好处是对非 Python 的底层库比如 C 编译工具链管理得更方便conda create -n commonroad python3.10 -y conda activate commonroad python -m pip install --upgrade pip选哪个我给个实用判断只在 Python 层面折腾用 venv需要摆弄编译器、C 依赖、或者你已经习惯 conda 生态用 conda。两者别混用在 conda 环境里再用 venv 套一层出问题时会很难查。注意Windows 上用 PowerShell 激活脚本时如果提示禁止运行脚本是执行策略的限制改一下当前用户的策略即可不要动全局策略。这一步网上教程很多不展开。3. 三种安装路径实操3.1 pip 安装最省事的路线对绝大多数人来说这条路就够了。# 确保在虚拟环境里 pip install commonroad-io国内网络环境下如果下载速度慢或者频繁超时可以指定镜像源pip install commonroad-io -i https://pypi.tuna.tsinghua.edu.cn/simple装完之后立刻验证不要等写完代码才发现没装上python -c import commonroad; print(commonroad.__version__)能打印出版本号说明包本身没问题。这里有个小坑有人执行这条命令报ModuleNotFoundError第一反应是重装其实十有八九是装到了另一个 Python 里。检查方法是which python # Linux / macOS where python # Windows which pip如果python和pip指向的路径不在同一个环境目录下那就是环境错位。用python -m pip install ...代替裸pip install ...基本能规避这个问题因为它是明确让当前这个 Python 去执行 pip。如果你还需要生成和转换场景再补一个pip install commonroad-scenario-designer车辆模型包通常会被commonroad-io作为依赖自动装上没装上就单独补。3.2 源码安装需要改代码或者跟仓库最新进展时用什么时候该走源码两种情况一是你要读源码、改源码或者给项目提 issue 需要复现最新代码的行为二是 pip 上的发布版有 bug而修复合在仓库里。前提是机器上有 git。Linux 下一条命令搞定Windows 下装完记得配置用户名和邮箱否则提交时会报错git config --global user.name your-name git config --global user.email your-emailexample.com git config --global core.autocrlf input最后那条core.autocrlf input是给跨平台协作用的避免 Windows 的换行符被提交进仓库导致整文件 diff。然后克隆并安装git clone commonroad-io 的仓库地址 cd commonroad-io pip install -e .这里的-e是关键表示可编辑安装。它不会把包复制到 site-packages而是建一个链接指回你的源码目录。你改了源码直接生效不用重装。反过来如果你不加-e改完代码发现没生效会怀疑人生。我个人更推荐用 pip 装发布版做日常使用另开一个源码目录做实验两个环境分开。混在一起最容易出现的状况是你为了调试改了一行后来忘了改回来结果跑出来的结果和预期不符排查半天才发现是代码被动了。3.3 可行驶性检查器的编译难点基本都在这commonroad-drivability-checker是这套工具里最不好装的一个因为它带 C 后端。它做的事情很实际给定车辆形状和一个位姿快速判断这个位姿在不在可行驶区域内做批量检查时性能比纯 Python 版本高一个量级。安装方式通常是先用 pip 试一下pip install commonroad-drivability-checker如果官方为你的 Python 版本和目标平台提供了预编译包这一步会直接成功那你运气不错。如果没有就会进入源码编译流程需要一个能用的 C 编译器Linux 上是 gWindows 上是 MSVCCMake用来生成构建文件Eigen做线性代数运算Boost提供一些基础组件Linux 上用包管理器装前置依赖大致是这样sudo apt update sudo apt install -y build-essential cmake libeigen3-dev libboost-all-dev然后按仓库 README 的说明编译安装。这里我不写死具体命令因为不同版本的构建脚本差异不小以仓库文档为准比自己猜命令靠谱。我要强调的是三个高频失败原因。第一编译器版本太老。一些 C 特性需要较新的 g系统的默认版本不够就得手动指定。第二Eigen 找不到。CMake 报错说找不到 Eigen3 是很常见的通常是因为头文件路径没被自动发现需要在 CMake 配置阶段手动指定。第三Python 版本不匹配。编译产物和 Python 解释器是绑定的你在 3.10 环境里编译的拿到 3.9 里用不了。所以务必在激活了正确虚拟环境的前提下编译。提示如果你的目的只是跑通场景加载和可视化完全可以先跳过这个包。等真正需要做精确的碰撞和越界检查时再回头啃它不要让它卡住你的整个上手流程。4. 验证把第一个场景加载出来4.1 先看懂场景文件长什么样在写代码之前花十分钟看一眼 XML 结构后面报错时你会感谢自己。一个 CommonRoad 场景文件大致长这样下面是简化示意实际字段更全?xml version1.0 encodingutf-8? scenario scenarioTags countryDEU/country /scenarioTags lanelet id1 leftBound pointx0.0/xy0.0/y/point pointx10.0/xy0.0/y/point /leftBound rightBound pointx0.0/xy-3.5/y/point pointx10.0/xy-3.5/y/point /rightBound predecessors/ successors/ /lanelet obstacle id1 typecar/type roleegoVehicle/role initialState positionx5.0/xy-1.75/y/position velocityx8.0/xy0.0/y/velocity orientationexact0.0/exact/orientation /initialState /obstacle /scenario几个要点值得记下来。坐标单位是米角度单位是弧度朝向角orientation的取值范围是 -π 到 π0 表示指向 x 轴正方向逆时针为正。速度是 m/s 的向量形式不是标量。默认时间步长是 0.1 秒这个值很重要因为你做的任何时间相关的计算都要基于它。拿这个时间步长做个换算你就能感受到它的含义。假设自车速度 30 km/h换算成米每秒是 30 / 3.6 ≈ 8.33 m/s。在 0.1 秒的时间步里车前进 8.33 × 0.1 ≈ 0.83 米。如果一个规划器输出的轨迹点是每 0.2 秒一个而你按 0.1 秒去插值位置就会整体错位。这类时空一致性问题在对接外部算法时非常常见务必在加载场景后第一件事就是确认时间步长dt scenario.dt print(f时间步长: {dt} 秒, 频率: {1/dt} Hz)保存场景 ID 也要注意。场景 ID 一般形如国家代码_地点-编号_类型标识它不只是一个名字很多工具会用 ID 去索引场景、管理缓存、拼接结果。如果你手工复制文件后改了名XML 内部记录的 ID 和文件名对不上某些接口会直接抛异常。稳妥做法是改名就一并改 XML 里的 ID或者走官方接口去设置。4.2 五行代码加载场景并打印关键信息加载场景只需要几行from commonroad.common.file_reader import CommonRoadFileReader # 传入场景文件路径 scenario, planning_problem_set CommonRoadFileReader(USA_Lanker-1_1_T-1.xml).open() print(场景 ID:, scenario.scenario_id) print(车道数量:, len(scenario.lanelet_network.lanelets)) print(动态障碍物数量:, len(scenario.dynamic_obstacles)) print(静态障碍物数量:, len(scenario.static_obstacles)) print(时间步长:, scenario.dt)注意.open()返回的是两个对象场景本身和规划问题集合。场景负责描述环境长什么样规划问题负责描述自车从哪来、要到哪去。这个分离是有意设计的——同一张地图可以配不同的规划问题一套地图数据能复用好几次。规划问题里最关键的是初始状态和目标区域for pp_id, pp in planning_problem_set.planning_problem_dict.items(): print(规划问题 ID:, pp_id) print(初始位置:, pp.initial_state.position) print(初始速度:, pp.initial_state.velocity) print(目标区域数量:, len(pp.goal_region))goal_region通常是一个多边形或者一组位置点表示车辆到达这些区域里任意一个位置就算完成任务。这个设计比必须到达某个精确坐标点宽松得多也更贴近真实驾驶场景你在写评测逻辑时要理解这个语义否则会出现车明明到了但算没到的误判。如果你想查询某个坐标落在哪条车道上工具提供了现成接口lanelet_ids scenario.lanelet_network.find_lanelet_by_position([[5.0, -1.75]]) print(该位置所在车道:, lanelet_ids)这个接口在调试车怎么跑到路外面去了这类问题时非常好用可以直接把自车每一帧的位置喂进去看它从哪一帧开始找不到所属车道。4.3 可视化渲染与导出加载成功但看不到图是不踏实的。渲染代码大致如下import matplotlib matplotlib.use(Agg) # 服务器上务必加这一行 import matplotlib.pyplot as plt from commonroad.visualization.mp_renderer import MPRenderer # 创建渲染器figsize 越大越清晰大场景建议 20x10 以上 renderer MPRenderer(figsize(20, 10)) # 依次绘制场景和规划问题 scenario.draw(renderer) planning_problem_set.draw(renderer) # 渲染到画布 renderer.render() plt.savefig(scenario.png, dpi150, bbox_inchestight) plt.close()这里有两个实操细节值得说。第一画布尺寸和分辨率的取舍。一个城市级别的场景动辄几百米宽你用默认的 6x4 画布画出来就是一团糊。我的经验是把 figsize 设成 20x10dpi 给 150出来的图既能看清车道线又能看清车辆文件大小也还能接受。如果你要批量出几百张图做论文插图dpi 降到 100 更划算。第二渲染顺序。先画场景再画规划问题最后 render顺序错了会出现图形互相遮挡。如果你要突出显示某几辆车可以在 render 之后用 matplotlib 的原生接口再叠加图形。想要矢量图走 SVG 渲染器from commonroad.visualization.svg_renderer import SVGRenderer renderer SVGRenderer(filenamescenario.svg) scenario.draw(renderer) renderer.render()SVG 的好处是放大不失真塞进论文或者做汇报都很合适缺点是复杂场景下文件会变得很大几百条车道一起画浏览器打开都要卡一下。可视化这块还有个小技巧只画你关心的区域。大场景全量渲染又慢又乱可以传入一个坐标范围做裁剪只画自车周围一百米内的内容查看局部细节时效率会高很多。5. 踩坑排查实录5.1 高频报错速查表安装和使用阶段能遇到的报错五花八门我把最常见的整理成表方便你对号入座。报错关键信息常见原因处理方式ModuleNotFoundError: No module named commonroadpip 和 python 不在同一环境改用python -m pip installCould not find a version that satisfies the requirementPython 版本过高或过低或缺 wheel换 3.9/3.10 重建环境error: Microsoft Visual C 14.0 or greater is requiredWindows 缺编译工具链装 VS Build Tools 或改用预编译包ImportError: libGL.so.1: cannot open shared object file容器/服务器缺图形库安装系统级图形依赖或用 Agg 后端XMLSyntaxError场景文件损坏或下载不完整重新下载并校验文件大小ValueError: Scenario ID does not match文件名与内部 ID 不一致统一命名或走官方接口设置TypeError出现在 shapely 调用处shapely 2.x 与老代码不兼容锁定 shapely 大版本渲染卡死无输出后端问题或场景过大设 Agg 后端裁剪绘图范围表格里有一个容易被忽略的场景文件下载不完整。场景集通常打成压缩包分发网络不稳的时候下载下来是个残缺的压缩包解压不报错但是读某个文件时 XML 解析失败。遇到这种报错先别怀疑代码去比一下文件大小对不对通常一分钟就能排除。5.2 依赖冲突与版本锁定依赖冲突是 Python 生态的老毛病CommonRoad 也躲不过。典型场景是这样你的项目里还装了另一个用numpy的高层库它要求 numpy 低于某个版本而commonroad-io的某个版本要求高于某个版本pip 报一堆ResolutionImpossible。处理方法我推荐先隔离再锁定。隔离就是给 CommonRoad 单独建一个环境不和别的项目混锁定就是把几个关键依赖的版本写进requirements.txt团队里所有人用同一份numpy1.24.4 scipy1.10.1 matplotlib3.7.2 shapely2.0.1 commonroad-io2023.1版本号要根据你实际跑通的组合来写不要照抄我这个示例因为版本迭代很快写死过期的版本反而会引入新问题。正确做法是在干净环境里装一遍跑通验证脚本然后pip freeze把当前环境导出这份导出结果就是你团队的可复现基线。以后别人装出问题拿这份文件一比就知道差在哪。还有个小坑值得提醒pip install时如果看到 pip 提示建议升级 pip别急着跳过。新版 pip 的依赖解析器比旧版聪明不少升级之后很多ResolutionImpossible会自己消失。5.3 Windows 和 Linux 上的差异处理如果你在 Windows 上做开发在 Linux 服务器上跑批量任务下面这几点差异会省你不少时间。编译类依赖。Linux 上装 C 依赖通常一条apt命令解决Windows 上得装 Visual Studio Build Tools安装包两个 G 起步装完还要确认环境变量。所以我的习惯是Windows 上只做代码编写和场景查看真跑批量计算就扔到 Linux 或者 Docker 里。这样能避开 Windows 上一大半的编译问题。路径与编码。Windows 的路径反斜杠在 Python 字符串里是转义符写路径时用原始字符串或者正斜杠path rC:\data\scenarios\DEU_Gar-1_1_T-1.xml # 或者 path C:/data/scenarios/DEU_Gar-1_1_T-1.xml第二个写法在 Windows 和 Linux 上都能跑我更推荐跨平台迁移时不用改代码。换行符。前面提过 git 配置这里再强调一次。如果你在 Windows 上生成场景文件然后提交到仓库给 Linux 服务器用不做换行符统一的话XML 里会混入多余的字符某些严格的解析器会报错。文件系统大小写。Linux 区分大小写Windows 不区分。在 Windows 上Scenario.xml和scenario.xml被当成同一个文件到了 Linux 上就是两个。团队协作时统一用全小写加下划线命名能避开这个问题。6. 上手之后的路线图6.1 从读场景到写场景读完别人的场景只是第一步真正开始产出是从写场景开始的。有两种路径。一种是从现有场景改。加载一个结构相近的场景把障碍物的初始状态改掉把目标区域挪一挪重新保存成新场景。这条路成本最低适合快速造测试用例。代码大致是加载、修改属性、然后走写入接口保存。另一种是从地图数据生成。如果你手上有 OpenDRIVE 或者 SUMO 的路网文件可以用场景设计工具把它转成 CommonRoad 格式再往里注入交通参与者。这条路适合有地理信息或者交通仿真背景的人能批量产出场景但对格式的理解深度要求更高。我的建议是先走第一条路。理由很实际手改一个场景你能立刻看到每一处修改对可视化结果的影响这个反馈循环最快。改上十几个场景你对 lanelet 结构、障碍物状态、规划问题的理解会比读十篇文档都扎实。等你能闭着眼睛说出我改这个字段会影响什么再去啃格式转换接受度高得多。6.2 对接自己的规划器和仿真器场景有了下一步是把自己的算法接进来。这里的核心问题是状态表示的对齐。CommonRoad 里自车的初始状态包含位置、速度、朝向可能还有横摆角速度、侧偏角等。你的规划器如果用的是另一套状态定义比如带曲率、带加速度就需要一个转换层。这个转换层别嫌麻烦一定要写成独立的模块别把转换逻辑散落在各处不然后面调参时会疯。对接仿真器也是同样的逻辑。仿真器输出的车辆状态每帧喂回 CommonRoad 的环境里做碰撞检查检查结果再反馈给仿真器决定是否终止。这个循环里最常见的坑是时间步对不上仿真器跑的是变步长CommonRoad 是固定 0.1 秒你要么把仿真器也固定步长要么在接口层做插值。我踩过这个坑插值方案在低速场景没问题高速急转弯时插值出来的位置会失真最后的结果就是明明没有碰撞被判定为碰撞。稳妥做法是尽量固定步长实在不行插值之后一定要做一次残差检查。还有一点评测指标要照着官方实现来。自己定义一套舒适度、通行效率的指标很容易但和别人的结果没法比。花点时间把官方的度量工具用起来让结果站得住脚这件事的收益远大于多写几个自己的指标。最后说个我个人在实际使用中的体会。CommonRoad 这套东西最大的门槛从来不是安装安装照着流程走半小时能搞定。真正花时间的是理解它的场景语义——为什么目标区域是个多边形而不是一个点为什么障碍物的速度是向量而不是标量为什么规划问题要和场景分离表示。这几个问题想通了后面无论是写评测脚本还是对接自己的算法都会顺畅很多。而想通它们最有效的方式不是看文档是打开一个真实场景文件一行一行读下来对照着可视化结果去理解每个字段在画面上是什么。我当年就是这么干的一个下午顶得上看了三天资料。