从零构建赛道摩擦地图:global_racetrajectory_optimization的frictionmap网格生成实战(cKDTree实现原理拆解)
从零构建赛道摩擦地图:global_racetrajectory_optimization的frictionmap网格生成实战(cKDTree实现原理拆解)
📍 本文带你完整走一遍 global_racetrajectory_optimization 开源项目的赛道摩擦地图(friction map)生成流程:从读取赛道参考线、切分网格单元格,到用 cKDTree 空间索引加速查询。即使你是第一次接触轨迹优化,也能照着跑通自己的第一张摩擦地图。
上图就是项目文档中展示的 Berlin FE 赛道摩擦地图(来源:opt_mintime_traj/Readme.md):红黄色区域代表高摩擦路面,蓝绿色代表低摩擦路面。当赛车开到不同位置时,四个车轮实际能获得的横向抓地力各不相同,最小圈时优化器会利用这张地图"扬长避短",从而压出更快的圈速。
一、赛道摩擦地图是什么?为什么需要它
传统最优化赛线求解通常假设全赛道摩擦系数 μ 恒定(例如统一取 1.0)。但真实赛道存在磨损带、雨水痕迹、砂石分布等,路面摩擦值随位置变化。
global_racetrajectory_optimization 项目的核心创新之一,就是把摩擦系数做成一张空间地图,并在最小圈时(minimum time)优化中按车轮位置逐一查表。项目 Readme.md 中引用了相关论文(Hermansdorfer 等,A Concept for Estimation and Prediction of the Tire-Road Friction Potential for an Autonomous Racecar),本仓库实现了其中的摩擦地图生成部分。
工作流程可以概括为三句话:
- 网格化:用
main_gen_frictionmap.py把赛道切成一格一格的"摩擦单元格"; - 填值:每个单元格默认填入初始 μ 值(真实项目中可替换为传感器估计值);
- 查询:最优化求解时用
cKDTree快速查到任意坐标点所属单元格的 μ。
二、项目结构与数据准备 🗂️
仓库目录结构如下(关键部分):
| 路径 | 作用 |
|---|---|
| main_gen_frictionmap.py | 摩擦地图生成主脚本(本文主角) |
| frictionmap/src/reftrack_functions.py | 参考线加载、法向量与赛道边界计算 |
| frictionmap/src/plot_frictionmap_grid.py | 网格 / Voronoi 图可视化 |
| opt_mintime_traj/src/friction_map_interface.py | FrictionMapInterface 查询接口(cKDTree 核心) |
| inputs/tracks/ | 赛道参考线 CSV(x, y, 右侧宽, 左侧宽) |
| inputs/frictionmaps/ | 生成的 *_tpamap.csv 与 *_tpadata.json |
| params/racecar.ini | 车辆与优化参数 |
输入赛道文件格式:以 inputs/tracks/berlin_2018.csv 为例,每行是参考线上的一个点,四列含义为 [x_m, y_m, w_tr_right_m, w_tr_left_m],即坐标 + 参考线左右两侧到赛道边界的距离(参见 Readme.md 的 "Wording and conventions" 一节)。
环境依赖:摩擦地图生成只需要 numpy、matplotlib、scipy(提供 cKDTree 与 Voronoi),安装方式见 requirements.txt:
pip3 install -r requirements.txt
三、四步生成摩擦地图网格 🏁
打开 main_gen_frictionmap.py,最上方的 USER INPUT 区有 5 个参数,以默认配置为例:
track_name = "modena_2019" # 赛道名,需在 inputs/tracks 下有同名 csv
initial_mue = 0.8 # 所有单元格的初始摩擦系数
cellwidth_m = 2.0 # 网格边长(米),正方形单元格
inside_trackbound = 'right' # 内边界在右侧(环道必填)
bool_show_plots = True # 是否弹出可视化窗口
执行 python main_gen_frictionmap.py 后,脚本内部依次完成四步:
第 1 步:加载参考线并计算赛道边界
- reftrack_functions.py 的
load_reftrack读入 CSV; check_isclosed_refline判断首尾点距离是否小于 10 m,从而区分环道(circuit)和开放路段;calc_refline_normvecs用相邻点梯度与 z 轴叉积,求出每个点指向右侧的单位法向量(见calc_trackboundaries,reftrack_functions.py);- 边界坐标 = 参考线 ± 法向量 × 半宽,得到左右两条赛道边线。
第 2 步:铺满赛道的二维坐标网格
脚本先算出一个向外扩张的包围盒 xyRange(在赛道外接矩形基础上再加 max(右宽)+max(左宽)+5m 的余量),然后用 np.arange 按 cellwidth_m 步长铺出 x_grid、y_grid,拼接成一张覆盖整个包围盒的密集坐标矩阵 coordinates(见 main_gen_frictionmap.py)。
💡 先铺满再筛选,而不是直接在赛道内采样,是因为
matplotlib.path.Path的contains_points可以对整批坐标做向量化批量判断,效率很高。
第 3 步:只保留"在赛道上"的网格点
这是网格生成中最关键的一步(main_gen_frictionmap.py):
- 留一个
dist_to_trackbound = cellwidth_m * 1.1的外扩余量,让赛道边缘外再多保留一圈单元格; - 环道情况:用外侧边界多边形(半径 +1.1 倍格宽,相当于"膨胀")与内侧边界多边形(半径为负,相当于"收缩")分别做包含判断,取在膨胀外边界内、且不在收缩内边界内的网格点——正好形成覆盖赛道 + 一圈边距的"带状"单元格集合;
- 开放赛道情况:把内、外边界拼成一个闭合多边形,向内收缩一个余量后直接取内部点。
第 4 步:构建 cKDTree 并落盘
tpa_map = cKDTree(coordinates[bool_OnTrack]) # 空间索引
tpa_data = dict(zip(tpamap_indices, np.full(...))) # 索引 -> [初始μ]
最终输出两个文件到 inputs/frictionmaps/(带时间戳前缀):
*_tpamap.csv:只存单元格的x_m;y_m坐标(柏林赛道、2m 格宽下约有 10.4 万行,参见 berlin_2018_tpamap.csv);*_tpadata.json:以单元格索引为 key、μ 值为 value 的字典(参见 berlin_2018_tpadata.json)。
如果开启 bool_show_plots,还会调用 plot_frictionmap_grid.py 画出散点网格和 Voronoi 图——每个网格点生成一个 Voronoi 单元,直观展示"谁负责哪块路面"。
四、cKDTree 实现原理拆解 🔍
为什么项目选择 scipy.spatial.cKDTree 而不是普通的二维数组?核心原因有三点:
- 赛道形状不规则。网格点只落在赛道"带状"区域内,无法用一个规则的
[rows, cols]数组按行列索引; - 查询模式是"任意坐标 → 最近格点"。最优化求解时每个车轮的位置是任意浮点坐标,需要找它最近的网格中心,这正是 KD-Tree 的近邻查询场景;
- 速度快。KD-Tree 是一种二叉空间分区树:每个节点按坐标轴(x/y 交替)把点集一分为二,查询时只沿"目标点所在的一侧"优先递归,平均复杂度约 O(log n)。10 万个格点,单次查询微秒级,批量查询更是直接走向量化 C 实现(
cKDTree中的 c 即 C 加速版)。
查询接口封装在 opt_mintime_traj/src/friction_map_interface.py 的 FrictionMapInterface 类中:
__init__:np.loadtxt读入 csv 坐标 →cKDTree(map_coords)建树;json 读入后转成{int(key): value}字典;get_friction_singlepos(positions):调用self.tpa_map.query(positions)(friction_map_interface.py)一次拿到每个查询点最近的单元格索引,再查字典取出 μ 值。
这里有一个巧妙的设计:μ 数据不存进树里,而是用"行号索引 → 字典 key"的对应关系分离存储。这样做的好处是换摩擦数据不需要重建空间索引——赛道几何(tpamap)固定不变,只是把 tpadata 里的 μ 值换掉即可,非常适合"同一赛道、不同路面状态"的对比实验(仓库里就备有 berlin_2018_varmue08-12_tpadata.json、berlin_2018_varmue09-11_tpadata.json 两组变体数据)。
五、摩擦地图如何接入最小圈时优化 🏎️
地图生成后,main_globaltraj.py 通过 file_paths["tpamap"] 和 file_paths["tpadata"] 指定文件(命名规则:赛道名_tpamap.csv / 赛道名_tpadata.json),并支持三种摩擦模式(见 opt_mintime_traj/Readme.md):
var_friction |
行为 |
|---|---|
None |
全赛道恒定 μ,不用地图 |
"linear" |
沿法向对每车轮的 μ 做线性拟合近似 |
"gauss" |
用高斯基函数线性组合近似,表达能力更强 |
处理链路为:
- extract_friction_coeffs.py:沿参考线每个切点,在法向量上按
dn步长取点,计算四个车轮(前左/前右/后左/后右)各自的坐标,逐一调用FrictionMapInterface.get_friction_singlepos查表,得到"沿赛道的 μ 剖面"; - approx_friction_map.py:把离散剖面拟合为解析表达式(线性或高斯基函数),让 NLP 优化器可以直接在求解过程中调用 μ(n) 函数,而不必反复查离散表。
下图是 Berlin 赛道最小圈时优化的最终赛线结果(opt_raceline_berlin.png,见 Readme.md):
六、常见问题与参数建议 ✅
Q1:格宽 cellwidth_m 怎么选?
格宽决定地图分辨率与计算开销。格宽越小 μ 变化捕捉越精细,但单元格数量随面积近似按 1/格宽² 增长(2m 格宽的柏林赛道约 10.4 万个单元格,1m 格宽则约 4 倍)。建议从 2~3 m 起步。
Q2:inside_trackbound 填错会怎样?
环道下内/外边界判断方向会反,导致选出的网格带整体偏移或为空。若生成的 tpamap 单元格数量异常(为 0 或少得离谱),优先检查该参数。
Q3:生成的文件命名带时间戳,main_globaltraj.py 却按 赛道名_tpamap.csv 找文件?
生成脚本的文件名带 datetime_save 时间戳,用于避免覆盖;跑最优化前,请把文件重命名为 {track_name}_tpamap.csv 与 {track_name}_tpadata.json(仓库 inputs/frictionmaps/ 下的既有文件就是这种命名)。
Q4:想让某些区域 μ 不同?
tpadata 本质是"索引 → μ"字典,跑通生成流程后,可以手工改写 json 中对应区域的值(或用感知/估计模块填充),空间索引无需重建。
七、总结
main_gen_frictionmap.py用"铺满网格 → 多边形包含判断筛选 → cKDTree 建索引 → csv/json 分离落盘"四步,把任意赛道切分成带 μ 值的摩擦地图;cKDTree(KD 空间树)让"任意坐标 → 最近单元格"的查询达到对数复杂度,是整张地图可被优化器高频调用的关键;- 地图最终通过
FrictionMapInterface为最小圈时优化提供逐车轮的变摩擦系数,让赛线规划真正考虑路面异质性。
按本文流程,你只需要准备一份赛道 CSV 和一行 python main_gen_frictionmap.py,就能从零得到自己的第一张赛道摩擦地图 🎯

