MMDetection3D库中的一些模块介绍

本文目前仅包含2个体素编码器、2个中间编码器、1个主干网络、1个颈部网络和1个检测头。如果有机会，会继续补充更多模型。
若发现内容有误，欢迎指出。

  MMDetection3D的点云数据一般会经历如下步骤/模块：

训练阶段

测试阶段

点云

体素化

体素编码器

中间编码器

主干网络

颈部网络

检测头

损失函数计算

预测结果生成

  下面分别介绍每个部分的一些典型模型。

0. 体素化函数

  在介绍体素编码器前，需要先介绍体素化函数，以理解体素编码器的输入参数含义。

0.1 mmcv.ops.voxelize中的Voxelization类

• 初始化参数：

参数名称	数据类型	默认值	含义	取值说明
max_voxels	(int, int)	-	最大体素数	两个元素分别表示训练时和测试时的最大体素数
max_num_points	int	-	体素内最大点数	记为$M$
point_cloud_range	List(float)	–	点云范围	列表长为6，依次表示$x,y,z$方向的最小值和$x,y,z$方向的最大值，即[x_min,y_min,z_min,x_max,y_max,z_max]
voxel_size	List(float)	-	每个体素的大小	列表长为3，依次表示体素的$x,y,z$尺寸，即[x_size,y_size,z_size]

注：将体素大小z_zise设置为与点云高度范围相同时，就可以实现柱体化操作。

• forward函数：

参数名称	数据类型	默认值	含义	取值说明
input	Tensor(float)	-	点云特征	$(n_p,C)$，其中$n_p$为点的数量，$C$为通道维度
features	Tensor(float)	返回值1	每个体素内的点	$(n,M,C)$，其中$n$为非空体素数，若第$i$个体素内的点数$m_i<M$，则features[i,j,:]（$j\ge m_i$）为零向量
num_points	Tensor(int)	返回值2	每个体素内的点数	$(n,)$，其中第$i$个体素内的点数为num_points[i]（即上文的$m_i$）
coors	Tensor(int)	返回值3	每个体素的3维位置索引	$(n,3)$，其中3表示z_id,y_id,x_id

0.2 MVXTwoStageDetector类中的体素化函数voxelize

• 初始化：初始化mmcv.ops.voxelize中的Voxelization类为self.points_voxel_layer
• voxelize函数：

参数名称	数据类型	默认值	含义	取值说明
points	List(Tensor(float))	-	一个batch的点云	列表长为batch size，其第$i$个元素大小为$(n_{i,p},C)$
voxels	Tensor(float)	返回值1	每个体素内的点	$(N,M,C)$，其中$N$为整个batch的总非空体素数，即$N={\sum }_i{n}_i$
num_points	Tensor(int)	返回值2	每个体素内的点数	大小为$(N,)$
coors	Tensor(int)	返回值3	每个体素的batch索引和3维位置索引	$(N,4)$，其中4表示batch_id,z_id,y_id,x_id

1. 体素编码器（VOXEL_ENCODERS）

1.1 HardSimpleVFE

• 作用：将体素内的点取平均作为体素特征。通常搭配SparseEncoder中间编码器。
• 初始化参数：

参数名称	数据类型	默认值	含义	取值说明
num_features	int	-	点云的特征维度	记为$C$

• forward函数：

参数名称	数据类型	默认值	含义	取值说明
features	Tensor(float)	-	每个体素内的点	大小为$(N,M,C)$，可为MVXTwoStageDetector类中的voxelize函数输出
num_points	Tensor(int)	-	每个体素内的点数	大小为$(N,)$，可为MVXTwoStageDetector类中的voxelize函数输出
coors	Tensor(int)	-	每个体素的batch索引和3维位置索引	大小为$(N,4)$，可为MVXTwoStageDetector类中的voxelize函数输出（在本函数中无实际作用，仅为和其余体素编码器有相同的输入）
返回值	Tensor(float)	返回值	非空体素特征	大小为$(N,C)$

1.2 PillarFeatureNet

  用于点云的柱体表达编码。通常搭配PointPillarsScatter中间编码器。

• 初始化参数：

参数名称	数据类型	默认值	含义	取值说明
in_channels	int	-	柱体的特征维度	记为$C$
feat_channels	Tuple(int)	-	-	长度表示图中PFN的数量$N$，第$i$个元素表示第$i$个PFN的输出通道数
with_distance	bool	False	表示是否将点到原点的距离附加在点的通道维度	-
with_cluster_center	bool	True	表示是否将点到体素质心的三维偏移量附加在点的通道维度	-
with_voxel_center	bool	True	表示是否将点到体素中心的三维偏移量附加在点的通道维度	-
voxel_size	List(float)	-	每个体素的大小	列表长为3，依次表示体素的$x,y,z$尺寸，即[x_size,y_size,z_size]
point_cloud_range	Tuple(float)	-	点云范围	长为6，依次表示$x,y,z$方向的最小值和$x,y,z$方向的最大值，即[x_min,y_min,z_min,x_max,y_max,z_max]
norm_cfg	dict	归一化类型默认为BN1d	设置归一化类型	配置文件格式
mode	str	池化类型默认为最大池化	设置池化类型	'max’表示最大池化，'avg’表示均值池化
legacy	bool	True	-	若为True，会导致with_cluster_center=True时影响到原始特征，且若此时with_distance=True，则附加的特征会变为到体素中心的距离而非到原点的距离；为False时结果正常

• forward函数：与HardSimpleVFE的forward函数输入和输出含义相同。
  
  

2. 中间编码器（MIDDLE_ENCODERS）

2.1 SparseEncoder

• 初始化参数：

参数名称	数据类型	默认值	含义	取值说明
in_channels	int	-	输入通道数	记为$C$
sparse_shape	List(int)	-	体素空间的shape	列表长为3，依次表示$z,y,x$方向的体素数
order	Tuple(str)	(‘conv’, ‘norm’, ‘act’)	表示卷积、归一化和激活函数的顺序	-
norm_cfg	dict	归一化类型默认为BN1d	归一化类型设置	配置文件格式
base_channel	int	-	第一个卷积的输出通道数	-
output_channels	int	-	最后一个卷积的输出通道数	-
encoder_channels	Tuple(Tuple(int))	-	每层的输出通道维度	外层元组长度为阶段数（图中$N$），内层元组长度为每阶段层数（图中$L$）
encoder_paddings	Tuple(Tuple(int))	-	每层的填充值	内外层元组长度分别与encoder_channels相同
block_type	str	-	使用的模块类型	可为’conv_module’或’basicblock’（区别如图）

• forward函数：

参数名称	数据类型	默认值	含义	取值说明
voxel_features	Tensor(float)	-	非空体素特征	$(N,C)$，$N$为体素数；该参数通常是VOXEL_ENCODERS的输出
coors	Tensor(int)	-	非空体素坐标	$(N,4)$，该参数通常是体素化函数的输出
batch_size	int	-	batch size	记为$B$
spatial_features	Tensor(float)	返回值	BEV特征图	大小为$(B,C^{\prime },H,W)$，其中$H$为宽度（y_size），$W$为长度（x_size）

2.2 PointPillarsScatter

  用于点云的柱体表达编码。可搭配PillarFeatureNet体素编码器。

• 作用：将柱体特征根据柱体坐标和batch_id生成BEV特征图。
• 初始化参数：

参数名称	数据类型	默认值	含义	取值说明
in_channels	int	-	输入通道数	-
output_shape	List(int)	-	输出BEV特征图的大小	长度为2，分别为BEV特征图的宽度$H$（y_size）和长度$W$（x_size）

• forward函数：与SparseEncoder的forward函数输入和输出含义相同。

3. 主干网络（BACKBONES）

3.1 SECOND

  SECOND主干网络通常搭配SECONDFPN颈部网络。前面可搭配体素操作（如HardSimpleVFE + SparseEncoder）或柱体操作（如PillarFeatureNet + PointPillarsScatter）。

• 初始化参数：

参数名称	数据类型	默认值	含义	取值说明
in_channels	int	-	输入的体素特征维度	-
out_channels	List(int)	-	每个阶段的输出通道数	长度为图中$L$
layer_nums	List(int)	-	每阶段的卷积层数（图中$N$）	长度与out_channels相同
layer_strides	List(int)	-	每阶段第一个卷积的步长	长度与out_channels相同
conv_cfg	dict	默认卷积类型为Conv2d	设置卷积类型	配置文件格式
norm_cfg	dict	默认归一化类型为BN	设置归一化类型	配置文件格式

• forward函数：

参数名称	数据类型	默认值	含义	取值说明
x	Tensor(float)	-	点云的BEV表达	$(B,C,H,W)$，通常为MIDDLE_ENCODERS的输出
返回值	List(Tensor(float))	返回值	输出为点云的多尺度BEV特征	列表长度等于尺度数，每个尺度特征图大小为$(B,C_i,H_i,W_i)$

4. 颈部网络（NECKS）

4.1 SECONDFPN

  SECONDFPN颈部网络通常搭配SECOND主干网络。

• 初始化参数：

参数名称	数据类型	默认值	含义	取值说明
in_channels	List(int)	-	表示各尺度特征通道数	与SECOND的out_channels相同
out_channels	List(int)	-	每个DeConv的输出通道数	长度为图中$L$
upsample_strides	List(int)	-	上采样步长	每个上采样块的上采样比例
conv_cfg	dict	默认卷积类型为Conv2d	设置卷积类型	配置文件格式
norm_cfg	dict	默认归一化类型为BN	设置归一化类型	配置文件格式
upsample_cfg	dict	默认上采样方式为DeConv	上采样方式	配置文件格式
use_conv_for_no_stride	bool	False	-	-

use_conv_for_no_stride=False且upsample_stride=1时，或upsample_stride>1时使用upsample_cfg搭建DeConv卷积，否则（即use_conv_for_no_stride=True且upsample_stride=1，或upsample_stride<1）使用conv_cfg搭建Conv2d卷积

• forward函数：

参数名称	数据类型	默认值	含义	取值说明
x	List(Tensor(float))	-	点云多尺度BEV特征	列表长度为尺度数，可直接使用SECOND的输出
返回值	List(Tensor(float))	返回值	多尺度融合后的BEV特征	列表长度为1

5.检测头（DENSE_HEADS）

检测头模块需要注意两点：
  一是loss函数的计算以及预测结果的生成均是在检测头中实现的方法；
  二是检测头初始化一般都有train_cfg和test_cfg两个参数，但在配置文件中，这两个参数往往需要写到检测器模型（DETECTOR）中而非检测头中。

5.1 CenterHead

  CenterPoint的检测头。可搭配SECOND + SECONDFPN结构使用。

• 初始化参数：

参数名称	数据类型	默认值	含义	取值说明
in_channels	List(int)	-	输入通道数	与颈部网络的输出通道数相同
shared_conv_channel	int	-	第一个共享卷积的输出通道维度	-
bias	str	’auto’	第一个共享卷积层的偏置项设置	-
tasks	List(dict)	-		dict为{'num_class': int, 'class_names': List(str)}的结构；列表的每一个元素对应图中的一个SeperateHead结构（即对不同的类别，head的网络参数可能不同）
num_heatmap_convs	int	-	每个中心热图头的卷积数	-
common_heads	dict	-	-	可包含如’reg’（BEV位置偏差）、‘hei’（离地高度）、‘dim’（尺寸）、‘rot’（旋转角）、‘vel’（速度）等项；每一项的值为二元组(int,int)：第一元素为最终维度，第二元素为head中的卷积层数（对应图中$N$）
norm_bbox	bool	True	是否对数归一化边界框尺寸作为估计值	-
conv_cfg	dict	默认卷积类型为Conv2d	设置卷积类型	配置文件格式
norm_cfg	dict	默认归一化类型为BN2d	设置归一化类型	配置文件格式
bbox_coder	dict	默认BBOX_CODERS类型为CenterPointBBoxCoder类	设置BBOX_CODERS类型	配置文件格式
loss_cls	dict	默认LOSS类型为GaussianFocalLoss	设置分类任务的LOSS类型	配置文件格式
loss_bbox	dict	默认LOSS类型为L1Loss	设置回归任务的LOSS类型	配置文件格式
seperate_head	dict	默认为SeperateHead类	设置SeperateHead的参数	配置文件格式，其中需要手动设置的初始化参数包括：head_conv为Head卷积的中间维度；final_kernal为Head卷积核大小

  train_cfg和test_cfg均为字典格式，这里单独拿出来介绍：

• train_cfg包含：

参数名称	数据类型	含义	取值说明
grid_size	List(int)	原始体素空间的shape	列表长为3，依次表示$x,y,z$方向的体素数
point_cloud_range	List(float)	点云范围	列表长为6，依次表示$x,y,z$方向的最小值和$x,y,z$方向的最大值，即[x_min,y_min,z_min,x_max,y_max,z_max]
voxel_size	List(float)	体素大小	列表长为3，依次表示体素的$x,y,z$尺寸，即[x_size,y_size,z_size]
out_size_factor	int	下采样倍数	最后BEV预测的大小为grid_size//out_size_factor
max_objs	int	最大检测物体数量	会取至多max_objs个物体计算热图回归目标
dense_reg	float	与max_objs相乘作为最终的最大检测数量	可固定为1，仅设置max_objs即可
gaussian_overlap	float	计算高斯半径时的参数	与真实物体尺寸一起用于计算高斯半径，从而生成热图的真值
min_radius	float	最小高斯半径	防止上述计算出来的高斯半径过小
code_weights	List(float)	计算损失时的各项权重	长度与边界框参数编码项数相同，如边界框编码包含3维位置、3维尺度，以及朝向角的正余弦值则长度应为8

• test_cfg包含：

参数名称	数据类型	含义	取值说明
post_center_limit_range	List(float)	后处理时物体中心的范围	列表长为6，依次表示$x,y,z$方向的最小值和$x,y,z$方向的最大值，即[x_min,y_min,z_min,x_max,y_max,z_max]；该范围一般略大于点云范围
nms_type	str	NMS方法的类型	只能是’circle’（CenterPoint文章提到的NMS方法）或’rotate’（常规的NMS方法）
nms_thr	float	rotate NMS的IoU阈值	仅在nms_type='rotate’时需要设置
score_threshold	float	rotate NMS的分数筛选阈值	仅在nms_type='rotate’时需要设置，nms前仅筛选满足分数大于该阈值的物体
pre_max_size	int	rotate NMS前考虑的最大物体数量	仅在nms_type='rotate’时需要设置，多余的预测会被丢弃（若需要全部考虑，可设置为None）
post_max_size	int	rotate NMS或circle NMS后保留的最大物体数量	-
min_radius	List(float)	circle NMS的最小半径	仅在nms_type='circle’时需要设置，长度为tasks数；第$i$项对应第$i$个task的物体BEV中心距离阈值

• forward函数（训练和测试阶段均会调用）：

参数名称	数据类型	默认值	含义	取值说明
feats	List(Tensor(float))	-	（多尺度）特征图	通常为颈部网络的输出
返回值	Tuple(List(dict))	返回值	BEV上的预测结果	外层元组长为任务数，内层列表长为尺度数，字典的键为’heatmap’以及common_heads中的键（如’reg’、‘hei’、‘dim’、‘rot’），值为相应Head的输出Tensor（大小为$(B,\ast ,h,w)$）

• loss函数（训练阶段调用）：

参数名称	数据类型	默认值	含义	取值说明
pred_dicts	Tuple(List(dict))	-	BEV下的预测结果	检测头模块forward函数的输出结果
gt_bboxes_3d	List(Tensor(float))	-	真实边界框参数	列表长为batch size，Tensor为$(n_b,\text{box\_dim})$，其中$n_b$表示该帧的真实边界框数量
gt_labels_3d	List(Tensor(int))	-	真实边界框类别标签	列表长为batch size，Tensor为$(n_b,)$
返回值	dict	返回值	损失字典	包含各任务的分类损失和回归损失，格式为{'task0.loss_heatmap': float, 'task0.loss_bbox': float, 'task1.loss_heatmap': float, ...}

• get_bboxes函数（测试阶段调用）：

参数名称	数据类型	默认值	含义	取值说明
pred_dicts	Tuple(List(dict))	-	BEV预测下的预测结果	检测头模块forward函数的输出结果
img_metas	List(dict)	-	数据信息	检测器模型forward函数输入中的img_meta项；列表长为batch size
返回值	List(List(Tensor))	-	最终的检测结果	外层列表长为batch_size，内层列表长为3，分别是预测的边界框参数$(n_b^{\text{pred}},\text{box\_dim})$、分数$(n_b^{\text{pred}},)$和类别标签$(n_b^{\text{pred}},)$