3DSSD 点云单阶段 3D 检测器:MMDetection3D 中的实现原理与 KITTI 实战指南
3DSSD 点云单阶段 3D 检测器:MMDetection3D 中的实现原理与 KITTI 实战指南
导读
3DSSD(Point-based 3D Single Stage Object Detector)是 OpenMMLab 的 MMDetection3D 中实现的一种纯点云(point-based)单阶段 3D 目标检测算法,它通过融合采样(Fusion Sampling)策略与锚框无关(anchor-free)的回归头,在精度与速度之间取得了良好的平衡。本文以 configs/3dssd/README.md 为骨架,结合 模型实现、检测头源码 与 KITTI 训练配置,系统讲解 3DSSD 的算法设计、与官方实现的差异、完整配置参数、训练/测试流程及 KITTI 上的评测结果,读完即可在 MMDetection3D 中复现并扩展 3DSSD。
一、算法背景:3DSSD 要解决什么问题
在 3DSSD 提出之前,体素(voxel-based)类单阶段 3D 检测器已经大量涌现,而基于原始点云(point-based)的单阶段方法仍然研究不足。3DSSD 论文(arXiv:2002.10187)提出了一种轻量且高效的点云单阶段检测器,其核心设计思想是:
- 抛弃上采样层与细化阶段:以往所有基于点的方法都依赖这两类模块,计算开销很大,3DSSD 将它们全部移除,从而显著降低计算量;
- 提出融合采样(Fusion Sampling)策略:在下采样过程中同时利用特征距离与欧氏距离进行采样,使得在"代表性较弱的点"上也能可靠地完成检测;
- 设计精致的框预测网络:包括候选点生成层(candidate generation layer)、基于 3D center-ness 分配策略的锚框无关(anchor-free)回归头,以满足精度与速度的双重要求。
该范式是一个简洁的单阶段、锚框无关框架。论文在 KITTI 与更富挑战性的 nuScenes 数据集上进行了评测,据论文报告,其性能大幅超越当时的体素类单阶段方法,并可与两阶段点云方法媲美,推理速度超过 25 FPS,是当时最先进点云方法的 2 倍。
在 MMDetection3D 仓库中,3DSSD 的实现以 configs/3dssd/ 目录下的配置为核心,模型代码位于 ssd3dnet.py 与 ssd_3d_head.py,当前提供 KITTI 数据集 Car 类别的完整训练配置与预训练权重登记(见 metafile.yml)。
二、仓库实现与官方实现的四点差异
configs/3dssd/README.md 明确指出,本仓库的 3DSSD 实现与官方实现存在一些设置上的差异,这些差异会在 KITTI 上带来轻微的性能波动,为统一和简化模型,仓库实现选择了跳过这些差异。理解这四点差异,有助于对比复现时解读指标差异:
-
空场景处理:官方代码在训练时会跳过没有任何目标的场景,仅使用 3229 个训练样本与 3394 个验证样本;本仓库沿用 KITTI 上其他所有模型的做法,使用完整的 3712 个训练样本与 3769 个验证样本(对应
kitti_infos_train.pkl/kitti_infos_val.pkl,见 kitti-3d-car.py)。 -
BatchNorm 衰减:本实现训练过程中不修改
batch normalization的衰减策略(decay),与官方代码不同。 -
数据库采样(DataBaseSampler)的参考基准:使用
ObjectSample(其底层即 DataBaseSampler,见 dbsampler.py)做数据增强时,官方代码以地面平面(road planes)为参考放置采样物体,本实现不使用地面参考。 -
坐标体系:本实现在 LiDAR 坐标系下做检测(配置中
coord_type='LIDAR'、box_type_3d='LiDAR'),而官方代码使用相机坐标系。
其中第 4 点直接体现在配置中:训练流水线使用 LoadPointsFromFile(coord_type='LIDAR', load_dim=4, use_dim=4) 加载点云,数据集的 box_type_3d='LiDAR' 表明 3D 框以 LiDAR 坐标编码。
三、模型结构源码级解析:SSD3DNet 的前向链路
3DSSD 的完整结构由 configs/base/models/3dssd.py 定义,运行时由 SSD3DNet 组装。从源码看,SSD3DNet 直接继承自 VoteNet(votenet.py 中的单阶段检测器基类),再经由 SingleStage3DDetector 获得统一的 loss / predict / aug_test 接口,其注册逻辑见 ssd3dnet.py。
模型由三大部分组成:PointNet2SAMSG 骨干网络、SSD3DHead 检测头,以及 Det3DDataPreprocessor 数据预处理器。整体前向流程是:输入点云 → 骨干网络逐层下采样并输出种子点(seed points)与特征 → 检测头中的 VoteModule 生成候选点 → 投票聚合层聚合局部特征 → 预测层输出分类与回归结果 → 解码得到 3D 框。
3.1 骨干网络:PointNet2SAMSG 与融合采样
骨干网络使用多尺度分组(Multi-scale Grouping)的 PointNet++,实现位于 pointnet2_sa_msg.py。其三个 SA(Set Abstraction)阶段的关键参数:
| 参数 | SA1 | SA2 | SA3 |
|---|---|---|---|
num_points |
4096 | 512 | (256, 256) |
radii |
(0.2, 0.4, 0.8) | (0.4, 0.8, 1.6) | (1.6, 3.2, 4.8) |
num_samples |
(32, 32, 64) | (32, 32, 64) | (32, 32, 32) |
fps_mods |
D-FPS | FS | (F-FPS, D-FPS) |
fps_sample_range_lists |
(-1) | (-1) | (512, -1) |
其中 fps_mods 是 3DSSD 融合采样策略的直接体现。根据 point_sa_module.py 的注释,采样模式共有三种:
- D-FPS:仅使用点坐标的欧氏距离做最远点采样(FPS);
- F-FPS:仅使用特征距离做 FPS;
- FS:同时使用 F-FPS 与 D-FPS 进行采样(即融合采样)。
可以看到,SA2 使用融合采样(FS),SA3 则同时包含 F-FPS 与 D-FPS 两路采样(对应 num_points=(256, 256)),这正是论文中"在代表性较弱的点上也能可靠检测"的核心机制。每个 SA 模块通过 QueryAndGroup 进行球查询(ball query)分组,再经 MLP 与最大池化聚合局部特征,各阶段聚合通道数为 aggregation_channels=(64, 128, 256)。骨干网络只输出最后一个 SA 阶段的 sa_xyz、sa_features 与 sa_indices,供检测头使用。
3.2 检测头 SSD3DHead:候选点生成 → 投票聚合 → 预测
SSD3DHead(ssd_3d_head.py)继承自 VoteHead,分为三个子模块:
候选点生成层(VoteModule):配置为 num_points=256、gt_per_seed=1、vote_xyz_range=(3.0, 3.0, 2.0)、with_res_feat=False。它从骨干输出的 256 维种子特征出发,为每个种子点生成一个指向目标中心的偏移量(vote),配合 vote_loss 监督候选点回归(VoteModule 的实现见 vote_module.py)。这里生成的是 256 个候选点,作为后续预测的"代表点"。
投票聚合层(vote_aggregation):使用 PointSAModuleMSG,num_point=256、radii=(4.8, 6.4)、sample_nums=(16, 32),两路 MLP 通道分别为 (256, 256, 256, 512) 与 (256, 256, 512, 1024)。它在每个候选点周围按两个尺度做球查询并聚合局部特征,聚合后拼接得到 512 + 1024 = 1536 维特征。
预测层(pred_layer_cfg):输入 in_channels=1536,经共享卷积 (512, 128) 后分支出分类与回归两个 128 维卷积头。回归输出通道数由 ssd_3d_head.py 中的 _get_reg_out_channels 决定:中心残差 3 维 + 尺寸回归 3 维 + 方向 bin 数与残差 num_dir_bins * 2(默认 num_dir_bins=12,即 24 维),共 30 维。
3.3 锚框无关的框编解码
检测头通过 bbox_coder 完成目标的编码与解码,其类型为 AnchorFreeBBoxCoder(anchor_free_bbox_coder.py),配置为 num_dir_bins=12, with_rot=True:
- 编码:中心目标取
gt_bboxes_3d.gravity_center,尺寸残差为dims / 2,朝向角通过angle2class离散到 12 个方向 bin 并归一化残差; - 解码:方向角由
argmax选出的 bin 与残差联合解出,尺寸通过clamp(size * 2, min=0.1)还原,最终输出[center, size, dir_angle]共 7 维的 3D 框。
3.4 损失函数与训练/测试配置
训练与测试配置同样定义在 models/3dssd.py 中:
train_cfg=dict(sample_mode='spec', pos_distance_thr=10.0, expand_dims_length=0.05)
test_cfg=dict(
nms_cfg=dict(type='nms', iou_thr=0.1),
sample_mode='spec',
score_thr=0.0,
per_class_proposal=True,
max_output_num=100)
sample_mode='spec' 表示使用指定点数采样(与 VoteHead 支持的 vote/seed/random/spec 模式对应,见 vote_head.py 中的 sample_mode 属性)。pos_distance_thr=10.0 用于判定聚合点是否属于正样本(距离目标顶部中心小于该阈值),expand_dims_length=0.05 用于生成 vote 目标时将 GT 框微扩。
损失由 ssd_3d_head.py 汇总为七项,全部使用 reduction='sum'、loss_weight=1.0:
| 损失 | 类型 | 监督目标 |
|---|---|---|
centerness_loss |
CrossEntropyLoss(sigmoid) | 3D center-ness 目标,即 objectness |
center_loss |
SmoothL1Loss | 聚合点到框中心的残差 |
dir_class_loss |
CrossEntropyLoss | 方向 bin 分类 |
dir_res_loss |
SmoothL1Loss | 方向残差回归 |
size_res_loss |
SmoothL1Loss | 尺寸残差回归 |
corner_loss |
SmoothL1Loss | 8 角点回归 |
vote_loss |
SmoothL1Loss | 候选点回归 |
其中 center-ness 目标的计算很有代表性(ssd_3d_head.py):将聚合点变换到框的 canonical 坐标系后,计算点到六个面的距离,得到 min/max 比值的三维乘积并开立方,最后 clamp 到 [0, 1]。这个 3D center-ness 赋值策略是 3DSSD anchor-free 回归头准确性的关键,正负样本掩码则由 points_in_boxes_all 判断点是否在框内、并结合 pos_distance_thr 距离阈值共同确定。
四、KITTI 数据配置与数据流水线详解
3DSSD 的 KITTI 配置 3dssd_4xb4_kitti-3d-car.py 基于 kitti-3d-car.py 的 Car 单类别设定,并针对 3DSSD 做了定制。
4.1 数据集基础设置
dataset_type = 'KittiDataset',data_root = 'data/kitti/',class_names = ['Car'];- 点云范围
point_cloud_range = [0, -40, -5, 70, 40, 3](x 为前向,注意与基础配置[0, -40, -3, 70.4, 40, 1]略有差异,由 3DSSD 配置覆盖); input_modality = dict(use_lidar=True, use_camera=False),纯 LiDAR 输入。
4.2 数据库采样(DB Sampler)
db_sampler = dict(
data_root=data_root,
info_path=data_root + 'kitti_dbinfos_train.pkl',
rate=1.0,
prepare=dict(filter_by_difficulty=[-1], filter_by_min_points=dict(Car=5)),
classes=class_names,
sample_groups=dict(Car=15),
points_loader=dict(
type='LoadPointsFromFile',
coord_type='LIDAR', load_dim=4, use_dim=4, backend_args=backend_args),
backend_args=backend_args)
含义:每个样本最多从 GT 数据库采样 15 个 Car 实例(sample_groups=dict(Car=15)),只保留点数不少于 5 的 Car 样本(filter_by_min_points=dict(Car=5)),难度过滤设置为 [-1] 即不按难度过滤。数据库中每个目标的点云通过 LoadPointsFromFile 以 LIDAR 坐标加载。
4.3 训练流水线
train_pipeline = [
dict(type='LoadPointsFromFile', coord_type='LIDAR', load_dim=4, use_dim=4),
dict(type='LoadAnnotations3D', with_bbox_3d=True, with_label_3d=True),
dict(type='PointsRangeFilter', point_cloud_range=point_cloud_range),
dict(type='ObjectRangeFilter', point_cloud_range=point_cloud_range),
dict(type='ObjectSample', db_sampler=db_sampler),
dict(type='RandomFlip3D', flip_ratio_bev_horizontal=0.5),
dict(type='ObjectNoise', num_try=100,
translation_std=[1.0, 1.0, 0],
global_rot_range=[0.0, 0.0],
rot_range=[-1.0471975511965976, 1.0471975511965976]),
dict(type='GlobalRotScaleTrans',
rot_range=[-0.78539816, 0.78539816],
scale_ratio_range=[0.9, 1.1]),
dict(type='PointSample', num_points=16384),
dict(type='Pack3DDetInputs', keys=['points', 'gt_bboxes_3d', 'gt_labels_3d'])
]
各环节要点:先按点云范围过滤点与目标框;ObjectSample 执行数据库采样增强;水平方向 50% 概率翻转(BEV);ObjectNoise 对目标做平移扰动(x/y 标准差 1.0、z 为 0)与 ±60° 的局部旋转;GlobalRotScaleTrans 做全局 ±45° 旋转与 0.9~1.1 的缩放;最后 PointSample 将每帧点云统一采样为 16384 个点(3DSSD 固定输入点数)。配置中特意注释掉了 BackgroundPointsFilter——3DSSD 不使用该变换时性能更高,这是官方复现实验得出的结论,值得在消融时留意。
4.4 测试流水线
测试时使用 MultiScaleFlipAug3D 包裹:pts_scale_ratio=1、flip=False,内部依次为恒等 GlobalRotScaleTrans、RandomFlip3D、PointsRangeFilter 与 PointSample(num_points=16384),保证推理时输入点云与训练分布一致。
五、训练、测试与评估实战
5.1 数据准备
KITTI 数据需先按仓库的数据准备指南(docs/user_guides/dataset_prepare.md)组织为 data/kitti/ 目录,并调用 tools/create_data.py 生成训练所需的 pkl 标注与数据库文件(包括配置中引用的 kitti_infos_train.pkl、kitti_infos_val.pkl 与 kitti_dbinfos_train.pkl)。
5.2 训练
单机多卡训练使用 tools/dist_train.sh,配置即为当前文件:
bash tools/dist_train.sh configs/3dssd/3dssd_4xb4_kitti-3d-car.py 4
单卡调试可改用 python tools/train.py configs/3dssd/3dssd_4xb4_kitti-3d-car.py。训练相关的关键超参数:
- 优化器:
AdamW,lr=0.002,weight_decay=0.,梯度裁剪clip_grad=dict(max_norm=35, norm_type=2); - 学习率调度:
MultiStepLR,里程碑milestones=[45, 60]、gamma=0.1,与训练轮数对齐; - 训练轮数:
EpochBasedTrainLoop(max_epochs=80, val_interval=2),每 2 轮验证一次。注意:当前配置实际为 80 轮,而 README 结果表中登记的Lr schd为 72e,两者存在版本演进差异,复现时应以当前配置的 80 轮为准; - batch_size:4(配置文件名
4xb4即 4 卡 × 4 的缩写),训练显存约 4.7 GB,metafile 登记的训练资源为 4× TITAN X。
5.3 测试与评估
bash tools/dist_test.sh configs/3dssd/3dssd_4xb4_kitti-3d-car.py <checkpoint路径> 4
或使用 tools/test.py 单卡推理,并可配合 demo/pcd_demo.py 对单帧点云做可视化推理。评估器为 KittiMetric(kitti_metric.py),配置为 metric='bbox'、ann_file=data/kitti/kitti_infos_val.pkl,即按 KITTI 官方 3D 目标检测协议输出 Car 类别的 mAP。
六、KITTI 实验结果
configs/3dssd/README.md 登记的官方复现结果如下(KITTI Car,3D 检测):
| Backbone | Class | Lr schd | Mem (GB) | mAP |
|---|---|---|---|---|
| PointNet2SAMSG | Car | 72e | 4.7 | 78.58(81.27)¹ |
¹ 表中报告了两种 3D 检测精度:78.58 mAP 由本仓库的评估代码计算,81.27 mAP 由官方开发工具包(即论文与 3DSSD 官方代码所用)计算。产生差异的原因在于:仓库 KITTI 评估所用的常见 Python 版 rotate_iou 实现,与 KITTI 官方基准的实现不同,导致两个数值之间存在偏差。因此在进行跨仓库横向对比时,务必注明所用的 mAP 口径。
预训练权重与训练日志已登记在 metafile.yml 的 Models 条目下,可通过模型库索引直接获取,便于加载权重做推理或微调。
七、单元测试:快速验证实现正确性
仓库为 3DSSD 提供了端到端的单元测试 tests/test_models/test_detectors/test_3dssd.py:测试通过 get_detector_cfg('3dssd/3dssd_4xb4_kitti-3d-car.py') 直接加载本配置构建 SSD3DNet,并断言:
- 模型成功注册且可构建(
hasattr(mmdet3d.models, 'SSD3DNet')); predict模式下输出包含bboxes_3d、scores_3d、labels_3d;loss模式下centerness_loss > 0,即七项损失中的关键监督项被正确激活。
这是验证环境、配置与依赖版本是否就绪的最快方式,也可作为修改配置后回归测试的基准。
八、引用信息
如论文复现中使用 3DSSD,configs/3dssd/README.md 建议引用:
@inproceedings{yang20203dssd,
author = {Zetong Yang and Yanan Sun and Shu Liu and Jiaya Jia},
title = {3DSSD: Point-based 3D Single Stage Object Detector},
booktitle = {Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},
year = {2020}
}
延伸阅读:相关文件索引
- 算法配置:configs/3dssd/3dssd_4xb4_kitti-3d-car.py、configs/base/models/3dssd.py、configs/base/datasets/kitti-3d-car.py
- 检测器实现:mmdet3d/models/detectors/ssd3dnet.py、mmdet3d/models/detectors/votenet.py
- 检测头与编解码:mmdet3d/models/dense_heads/ssd_3d_head.py、mmdet3d/models/dense_heads/vote_head.py、mmdet3d/models/task_modules/coders/anchor_free_bbox_coder.py
- 骨干与采样模块:mmdet3d/models/backbones/pointnet2_sa_msg.py、mmdet3d/models/layers/pointnet_modules/point_sa_module.py、mmdet3d/models/layers/vote_module.py
- 测试与数据准备:tests/test_models/test_detectors/test_3dssd.py、tools/create_data.py、docs/user_guides/dataset_prepare.md