PaddleDetection 中 CLRNet 车道线检测模型:原理、配置与实战全解析
PaddleDetection 中 CLRNet 车道线检测模型:原理、配置与实战全解析
导读
本文以 PaddleDetection 仓库中 configs/clrnet 目录下的 CLRNet 车道线检测方案为核心,系统讲解 CLRNet(Cross Layer Refinement Network)的模型原理、CULane 数据集准备、配置文件逐项解读,以及从单卡/多卡训练、评估到预测推理的完整实战流程。读完本文,你将掌握如何在 PaddleDetection 中一键复现 ResNet-18 骨干的 CLRNet 车道线检测模型,并能对照源码理解直线先验(line prior)、Line IoU 损失与多尺度 refine 的底层实现。
CLRNet 简介:面向车道线检测的跨层精炼网络
CLRNet(Cross Layer Refinement Network for Lane Detection)是 PaddleDetection 支持的车道线检测模型,其论文发表于 CVPR 2022(Zheng Tu 等人)。与通用目标检测不同,车道线具有"细长、连续、强先验"的特点,CLRNet 正是围绕这些特点设计了四个核心技术:
- 直线先验(Line Prior):为每条车道线候选建立直线形式的初始轨迹,作为后续回归与分类的锚点;
- Line IoU 损失:针对车道线这种长条状目标设计专门的 IoU 度量,比普通位置回归损失更贴合车道线形状;
- NMS 后处理:对高度重叠的车道线预测做非极大值抑制,去除冗余候选;
- 上下文高层特征与低层特征的融合 + FPN 多尺度精炼(refine):先提取车道线轨迹的上下文高层语义特征,再与低层细节特征融合,并通过 FPN 的多尺度特征逐步精炼定位结果。
从 PaddleDetection 源码结构看,CLRNet 的完整实现分布在以下模块中(均可从仓库根目录进入查看):
| 模块 | 源码位置 |
|---|---|
| 整体架构 | ppdet/modeling/architectures/clrnet.py |
| 骨干网络 CLRResNet | ppdet/modeling/backbones/clrnet_resnet.py |
| 特征金字塔 CLRFPN | ppdet/modeling/necks/clrnet_fpn.py |
| 检测头 CLRHead | ppdet/modeling/heads/clrnet_head.py |
| 损失函数 CLRNetLoss | ppdet/modeling/losses/clrnet_loss.py |
| 评估指标 CULaneMetric | ppdet/metrics/culane_metrics.py |
在架构层面,CLRNet 类继承自 BaseArch,其前向流程为:backbone(inputs['image']) 提取主干特征 → CLRFPN 生成多尺度特征 → CLRHead 输出预测。值得注意的是,在非训练模式下,代码会调用 get_lanes 将网络输出转换为车道线列表,并返回 img_path 与 img_name 用于可视化;源码中还保留了一段注释说明静态图模式下 get_lanes 尚存在 hard code 问题,这正是官方 README 中"预测功能暂不支持静态图推理部署"这一注意事项的源码级印证。
从源码实现细节看,CLRHead 中注册了 priors(初始直线先验)与 priors_on_featmap(特征图上的先验位置),并通过 ROIGather 按采样点收集先验特征,再经 reg_layers 与 cls_layers 完成回归和分类;头部分支还包含一个 SegDecoder 用于输出分割辅助信息,与损失中的分割分支(seg_loss)相呼应。
模型库:CULane 数据集上的精度表现
PaddleDetection 官方在 CULane 数据集上给出了 ResNet-18 骨干的 CLRNet 预训练模型结果,指标包括 mF1(平均 F1)、F1@50 与 F1@75(IoU 阈值分别为 0.5 与 0.75 时的 F1):
| 骨干网络 | mF1 | F1@50 | F1@75 | 下载链接 | 配置文件 |
|---|---|---|---|---|---|
| ResNet-18 | 54.98 | 79.46 | 62.10 | model |
上述精度由仓库内 模型配置文件 与对应训练日志复现得到。如需复现结果,需要下载 CULane 全量数据集进行训练;仓库还附带了一个小型 CULane 子集用于代码检查,直接运行训练脚本即可自动下载解压。
CULane 数据集准备与目录结构
数据集下载
首先从 CULane 项目官网下载 CULane 数据集,然后解压到 dataset/culane 目录下(相对于仓库根目录,即 dataset/culane)。完成后的目录结构应为:
culane/driver_xx_xxframe # 数据文件夹 x6
culane/laneseg_label_w16 # 车道线分割标签
culane/list # 数据列表
其中 driver_xx_xxframe 为 6 个视频帧数据文件夹,laneseg_label_w16 存放车道线分割标签,list 存放训练/测试数据列表文件。
特别提示:如果使用百度云链接下载,务必注意 driver_23_30frame_part1.tar.gz 与 driver_23_30frame_part2.tar.gz 解压后应合并到同一个 driver_23_30frame 目录下,而不是保留为两个分离的目录,否则数据列表中的相对路径将无法正确解析。
仓库内置小数据集
仓库已将用于代码检查的 CULane 小数据集上传到 PaddleDetection 中,直接运行下方训练脚本即可自动下载并解压数据。不过需要说明的是:该小数据集仅用于跑通训练代码流程,如需复现官方精度,必须下载链接中的 CULane 全量数据集进行训练。
数据配置说明
数据集相关的配置集中在 configs/datasets/culane.yml 中:
num_classes: 5(4 条车道线 + 背景);cut_height: 270:图像底部裁剪高度,用于去掉车辆引擎盖等无效区域;dataset_dir: dataset/culane:数据集根目录;TrainDataset/EvalDataset/TestDataset均使用CULaneDataSet,分别对应list/train_gt.txt(训练)与list/test.txt(测试)。
对应的数据集实现类为 ppdet/data/source/culane.py 中的 CULaneDataSet,负责按列表文件读取图像、车道线标注与分割标签。
配置文件详解
CLRNet 的完整训练配置由 clrnet_resnet18_culane.yml 通过 _BASE_ 机制继承而来,共组合了 5 个基础配置:
_BASE_: [
'../datasets/culane.yml', # 数据集与评估指标配置
'_base_/clrnet_reader.yml', # 数据读取与增强配置
'_base_/clrnet_r18_fpn.yml', # 网络结构配置
'_base_/optimizer_1x.yml', # 学习率与优化器配置
'../runtime.yml' # 运行时公共配置
]
weights: output/clr_resnet18_culane/model_final
weights 指定了模型权重保存路径(output/clr_resnet18_culane/model_final),训练完成后的评估命令会直接引用该路径下的 model_final.pdparams。
网络结构:clrnet_r18_fpn.yml
configs/clrnet/base/clrnet_r18_fpn.yml 定义了完整网络结构:
architecture: CLRNet
CLRNet:
backbone: CLRResNet
neck: CLRFPN
clr_head: CLRHead
CLRResNet:
resnet: 'resnet18'
pretrained: True
CLRFPN:
in_channels: [128,256,512]
out_channel: 64
extra_stage: 0
CLRHead:
prior_feat_channels: 64
fc_hidden_dim: 64
num_priors: 192
num_fc: 2
refine_layers: 3
sample_points: 36
loss: CLRNetLoss
conf_threshold: 0.4
nms_thres: 0.8
CLRNetLoss:
cls_loss_weight : 2.0
xyt_loss_weight : 0.2
iou_loss_weight : 2.0
seg_loss_weight : 1.0
refine_layers : 3
ignore_label: 255
bg_weight: 0.4
# for visualize lane detection results
sample_y:
start: 589
end: 230
step: -20
各关键参数的作用与取值含义如下:
- CLRResNet:骨干网络选用
resnet18并加载预训练权重(pretrained: True); - CLRFPN:输入通道为
[128, 256, 512](对应 ResNet-18 的 C3/C4/C5 层输出),输出通道out_channel: 64,extra_stage: 0表示不额外下采样; - CLRHead:
num_priors: 192:直线先验(候选车道线)的数量;sample_points: 36:每条先验在特征图上的采样点数,对应CLRHead源码中sample_x_indexs与prior_feat_ys缓冲区的生成逻辑;refine_layers: 3:跨层精炼的次数,与 FPN 的三个尺度对应;fc_hidden_dim: 64、num_fc: 2:回归/分类全连接子模块的隐藏维度与层数;conf_threshold: 0.4:推理时的置信度阈值,低于该值的预测被过滤;nms_thres: 0.8:车道线 NMS 的 IoU 阈值;loss: CLRNetLoss:指向下方定义的损失模块。
- CLRNetLoss:四部分损失加权组合——
cls_loss_weight: 2.0(分类损失权重,源码中分类使用 Focal Loss,alpha=0.25, gamma=2.0,见 clrnet_loss.py);xyt_loss_weight: 0.2(起止点/角度回归损失权重);iou_loss_weight: 2.0(Line IoU 损失权重);seg_loss_weight: 1.0(分割辅助损失权重);refine_layers: 3(与 head 的精炼次数一致);ignore_label: 255(分割标签中忽略的像素值);bg_weight: 0.4(背景类在 NLL 分割损失中的权重,用于缓解背景像素远多于车道线像素的类别不平衡,见 clrnet_loss.py)。
- sample_y:可视化时沿 y 轴的采样范围(
start: 589, end: 230, step: -20),即从图像下方 589 行向上每隔 20 像素取一个采样点绘制车道线。
数据读取与增强:clrnet_reader.yml
configs/clrnet/base/clrnet_reader.yml 定义了输入尺寸与数据增强管线:
worker_num: 10
img_h: &img_h 320
img_w: &img_w 800
ori_img_h: &ori_img_h 590
ori_img_w: &ori_img_w 1640
num_points: &num_points 72
max_lanes: &max_lanes 4
img_h: 320、img_w: 800:网络输入尺寸;ori_img_h: 590、ori_img_w: 1640:CULane 原始图像尺寸;num_points: 72:每条车道线采样 72 个点,内部计算n_strips = num_points - 1 = 71条水平条带;max_lanes: 4:单张图像最多标注的车道线数量。
Train / Eval / Test 三种 Reader 均组合了不同算子:
- CULaneTrainProcess:训练专用增强,基于 imgaug 对图像、车道线(line strings)与分割标签同步做随机几何/颜色增强(实现见 culane_operators.py);
- CULaneDataProcess:将标注转换为模型所需的数值格式(车道线裁剪出图、按
num_points采样、填充到max_lanes等,实现见 culane_operators.py); - CULaneResize:评估/推理时以
prob: 1.0确定性缩放到img_h × img_w(实现见 culane_operators.py)。
训练批大小为 24,worker_num: 10 表示数据加载进程数。
优化器与学习率:optimizer_1x.yml
configs/clrnet/base/optimizer_1x.yml 定义训练超参:
epoch: 15
snapshot_epoch: 5
LearningRate:
base_lr: 0.6e-3
schedulers:
- !CosineDecay
max_epochs: 15
use_warmup: False
OptimizerBuilder:
regularizer: False
optimizer:
type: AdamW
- 共训练 15 个 epoch,每 5 个 epoch 保存一次快照(
snapshot_epoch: 5); - 基础学习率
0.6e-3,使用无 warmup 的余弦退火(CosineDecay)调度; - 优化器为 AdamW,且关闭权重衰减正则化(
regularizer: False)。
训练
单卡训练
在仓库根目录下执行:
python tools/train.py -c configs/clrnet/clrnet_resnet18_culane.yml
首次运行时若未准备 CULane 全量数据,脚本会自动下载仓库附带的小数据集并解压,用于验证训练代码流程可以跑通。
多卡训练
export CUDA_VISIBLE_DEVICES=0,1,2,3
python -m paddle.distributed.launch --gpus 0,1,2,3 tools/train.py -c configs/clrnet/clrnet_resnet18_culane.yml
多卡训练通过 paddle.distributed.launch 启动,--gpus 与 CUDA_VISIBLE_DEVICES 指定参与训练的 GPU 编号。训练产物(模型权重、日志、可视化)默认输出到 output/clr_resnet18_culane/ 目录。
说明:官方 README 中的训练命令写作
configs/clrnet/clr_resnet18_culane.yml,而仓库当前实际的配置文件名为configs/clrnet/clrnet_resnet18_culane.yml,请以仓库实际文件名(本文给出的命令)为准,避免因文件名不匹配导致配置文件加载失败。
评估
训练完成后,使用 tools/eval.py 在 CULane 测试集上评估模型:
python tools/eval.py -c configs/clrnet/clrnet_resnet18_culane.yml -o weights=output/clr_resnet18_culane/model_final.pdparams
-o weights=... 用于覆盖配置中的 weights 字段,指向训练产出的最终权重文件。评估过程由 CULaneMetric(实现见 culane_metrics.py)完成:它将每条预测车道线在 y 从 270 到 590、间隔 8 的采样点上计算 x 坐标,输出为 CULane 官方评估工具兼容的 lines.txt 格式,并统计各类别(直道、弯道、交叉口等)的 F1 与整体 mF1、F1@50、F1@75。
推理预测
CLRNet 专门提供了车道线推理脚本 tools/infer_culane.py:
python tools/infer_culane.py -c configs/clrnet/clrnet_resnet18_culane.yml -o weights=output/clr_resnet18_culane/model_final.pdparams --infer_img=demo/lane00000.jpg
--infer_img 指定单张测试图像(上例使用仓库自带的 demo/lane00000.jpg 车道线样例图)。该脚本还支持以下参数(见 infer_culane.py):
| 参数 | 默认值 | 说明 |
|---|---|---|
--infer_dir |
None |
批量推理的图片目录;与 --infer_img 同时指定时,--infer_img 优先级更高 |
--infer_img |
None |
单张推理图片路径 |
--output_dir |
output |
可视化结果输出目录 |
--save_results |
False |
是否将推理结果以文本形式保存到 output_dir |
--visualize |
True |
是否保存可视化结果到 output_dir |
注意事项:如官方文档所述,CLRNet 的预测阶段暂不支持静态图模型部署。这一限制在源码中亦有体现——clrnet.py 中 get_lanes 的调用针对静态图模式存在待修复的 hard code 问题,因此推理请使用上文动态图脚本方式执行。
引用
复现或参考本模型时,请引用 CLRNet 原始论文:
@InProceedings{Zheng_2022_CVPR,
author = {Zheng, Tu and Huang, Yifei and Liu, Yang and Tang, Wenjian and Yang, Zheng and Cai, Deng and He, Xiaofei},
title = {CLRNet: Cross Layer Refinement Network for Lane Detection},
booktitle = {Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)},
month = {June},
year = {2022},
pages = {898-907}
}
小结
CLRNet 是 PaddleDetection 提供的一条完整的车道线检测技术路线:以直线先验为锚、Line IoU 损失为优化目标、FPN 多尺度精炼为手段,在 CULane 数据集上以 ResNet-18 骨干取得了 mF1 54.98 的成绩。通过本文梳理的配置文件(网络结构、数据管线、优化器)与训练/评估/推理命令,你可以在仓库中一键复现并二次开发自己的车道线检测方案;深入 clrnet_head.py 与 clrnet_loss.py 等源码,则能进一步理解先验生成、ROI 特征聚合与多任务损失的内在机理。