DGL 点云 Transformer(PCT)实战:ModelNet40 分类与 ShapeNet 部件分割的完整复现指南
DGL 点云 Transformer(PCT)实战:ModelNet40 分类与 ShapeNet 部件分割的完整复现指南
本指南基于 DGL 官方示例 examples/pytorch/pointcloud/pct,完整讲解如何在 DGL(Deep Graph Library)中复现 PCT: Point Cloud Transformer 论文,覆盖点云分类(ModelNet40)与部件分割(ShapeNet)两个任务。读完本文,你将掌握 PCT 的图结构建模思路、Transformer 自注意力层与降采样模块的实现细节,以及数据自动下载、数据增强、训练脚本参数与评估指标的实际配置方法。
项目概览:在 DGL 中实现 PCT
PCT(Point Cloud Transformer)是 PCT: Point cloud transformer 论文的官方复现,仓库将其实现为一个完整的 PyTorch + DGL 示例,位于 examples/pytorch/pointcloud/pct 目录。该示例将每个点云建模为一张 K 近邻(KNN)图,并用 Transformer 风格的注意力机制在图上聚合邻居特征,从而同时支持点云分类与逐点部件分割两个下游任务。
示例目录下的文件分工如下:
| 文件 | 职责 |
|---|---|
| pct.py | PCT 核心网络定义(分类网络、分割网络、自注意力层、损失函数) |
| helper.py | KNN 图构建、消息传递、TransitionDown 降采样模块(核心 DGL 部分) |
| train_cls.py | ModelNet40 点云分类训练/评估入口 |
| train_partseg.py | ShapeNet 部件分割训练/评估入口 |
| ModelNetDataLoader.py | ModelNet40 数据集加载器 |
| ShapeNet.py | ShapeNet 部件分割数据集加载器 |
| provider.py | 训练数据增强工具函数 |
代码实现中部分借鉴了开源的 PCT 原始实现 与 helper.py 的注释),属于典型的"用 DGL 图算子重写点云网络"的工程化落地。
复现性能一览
README 中给出了两个任务在 DGL 实现下的复现结果,并与论文原始得分进行对照:
| 任务 | 数据集 | 指标 | 论文得分 | DGL 得分(Adam 优化器) | DGL 单 epoch 耗时(s) |
|---|---|---|---|---|---|
| 分类 | ModelNet40 | Accuracy | 93.2 | 92.1 | 740.0 |
| 部件分割 | ShapeNet | mIoU | 86.4 | 85.6 | 390.0 |
关于上表,README 补充了两点重要说明:
- 耗时口径:表格中的 Time(s) 是平均每个 epoch 的训练时间,测试环境为 EC2 g4dn.12xlarge 实例上的 Tesla T4 GPU。这意味着完整的 250 个 epoch(分类默认配置)训练周期较长,首次复现时可先用较小的 epoch 数验证代码可运行性。
- 预处理差异:该示例使用的是 PointNet++ 示例 所采用的预处理流程(即随机点丢弃 + 缩放 + 抖动 + 平移,具体见下文"数据增强"小节)。README 明确指出:如果改回论文中描述的预处理(训练时对输入施加 [−0.2, 0.2] 范围内的随机平移、[0.67, 1.5] 范围内的随机各向异性缩放以及随机输入 dropout),分类准确率只能达到 84.5。因此,若想获得接近论文的成绩,请保持示例默认的 PointNet++ 风格数据增强,而不是照搬论文原文的增强参数。
快速开始:两条训练命令
在安装好 DGL(PyTorch 后端)及相关依赖(torch、numpy、scipy、tqdm)后,进入示例目录即可训练:
点云分类(ModelNet40):
python train_cls.py
点云部件分割(ShapeNet):
python train_partseg.py
两个脚本在首次运行时都会通过 DGL 的 download 工具自动下载对应数据集到 get_download_dir() 目录(默认是 ~/.dgl/ 下的数据目录),无需手动准备数据。若数据目录已存在则直接复用本地缓存,不会重复下载。
网络架构:从图构建到 Transformer 特征提取
总体流程:分类网络
分类网络 PointTransformerCLS(定义于 pct.py)的前向流程如下:
- 输入切分:输入张量
x的最后一维包含坐标与法向等特征,前 3 维作为xyz坐标,其余维度作为点特征; - 初始特征提取:两个
1×1卷积(3→64→64),将点特征映射到 64 维,得到B, D, N形状的特征; - 两级 TransitionDown 降采样:通过
TransitionDown模块将点云从 1024 点依次降采样到 512 点、256 点,并同步提取局部邻域特征; - PCT 位置编码 + 四层自注意力:在 256 个中心点上叠加位置嵌入,经过
PCTPositionEmbedding中的 4 层SALayerCLS自注意力层; - 特征融合与全局池化:将 4 层输出拼接(4×256 通道),与降采样特征拼接后经
conv_fuse融合,再通过torch.max做通道维最大池化得到全局特征; - 分类头:三层全连接(1024→512→256→output_channels,默认 40 类,对应 ModelNet40),中间插入 BatchNorm、ReLU 与 p=0.5 的 Dropout。
自注意力层 SALayer:PCT 的核心算子
SALayerCLS(分类用,见 pct.py)与 SALayerSeg(分割用,见 pct.py)是 PCT 的特征聚合核心,二者结构几乎一致,区别仅在于分类层需要把位置嵌入 xyz 加到输入特征上,而分割层的输入特征本身已含位置信息:
- 通过三个
1×1卷积分别生成 Query、Key、Value 特征(q_conv输出通道为输入通道的 1/4); - 计算注意力矩阵
energy = Q @ K^T(形状b, n, n),经 Softmax 归一化; - 归一化后额外除以行和(
attention / (1e-9 + attention.sum(dim=1, keepdims=True))),实现近似行归一化; - 用注意力矩阵加权 Value 得到
x_r,经过残差变换trans_conv(x - x_r)与x + x_r完成一次自注意力更新; - 注意
q_conv.weight = k_conv.weight,即 Query 与 Key 共享权重(见 pct.py)。
分类分支将 4 层输出在通道维拼接,得到 4×256=1024 维特征;分割分支则将 4 层 128 维输出拼接为 512 维。
位置嵌入与分割网络的全局特征
PCTPositionEmbedding(见 pct.py)先把 3 维坐标经 conv_pos 映射到 256 维,与点特征相加后送入 4 层 SALayerCLS。
分割网络 PointTransformerSeg(见 pct.py)在 4 层自注意力后,额外拼接了最大池化特征、平均池化特征与类别标签特征三类全局特征:类别标签先做 16 维 one-hot 编码(对应 ShapeNet 的 16 个部件类别),经 label_conv 映射到 64 维后沿点维广播,最终得到 1024*3 + 64 维的逐点特征,再通过三层 1×1 卷积输出 50 类(part_num=50,对应 ShapeNet 全部 50 个部件标签)。
损失函数
分割任务使用 PartSegLoss(见 pct.py):将 logits 重排为 (-1, num_classes) 后计算标准交叉熵损失,eps 参数在当前实现中为占位参数,实际未参与计算。
DGL 图构建与降采样:helper.py 的底层实现
整个示例最贴合 DGL 的部分集中在 helper.py,它把"KNN 建图 + 邻居消息聚合"完全建模为图神经网络操作:
1. KNN 图构建(KNNGraphBuilder)
KNearNeighbors 先利用 index_points 与 square_distance 计算每个中心点到全部点的平方距离,按距离排序取前 n_neighbor 个索引作为邻居;KNNGraphBuilder 再据此为 batch 中每个点云构造一张 DGL 图(helper.py):
- 以中心点为
dst、邻居为src,将src/dst合并去重后建立dgl.graph((src_idx, dst_idx)); - 把去重后点的坐标、中心标记、原始特征写入
ndata["pos"]、ndata["center"]、ndata["feat"]; - 多个点云用
dgl.batch合并成批量图,供后续update_all统一消息传递。
2. 消息与聚合(KNNMessage / KNNConv)
KNNMessage(helper.py)定义边上的消息函数:计算邻居特征与目标特征之差src["feat"] - dst["feat"],并与邻居特征拼接,作为聚合输入;KNNConv(helper.py)在目标节点上执行聚合:将mailbox中收到的消息 reshape 成(batch, 邻居数, 通道)布局,经两层1×1卷积 + BatchNorm + ReLU 后,在邻居维做最大池化,得到每个点的更新特征。
3. TransitionDown 降采样(核心模块)
TransitionDown(helper.py)是 PCT 分层下采样的关键:
- 调用 DGL 的
dgl.geometry.farthest_point_sampler(pos, n_point)(实现在 python/dgl/geometry/fps.py)选取n_point个最远点作为中心点,该采样器无需计算全量点对距离,只需维护"到已采样点的最小距离"并迭代选取最大者; - 用
KNNGraphBuilder在中心点周围建 KNN 图(n_neighbor=32); - 通过
g.update_all(message, conv)一次完成邻居消息传递与特征聚合; - 用
ndata["center"] == 1掩码筛选出中心点,返回降采样后的坐标pos_res与特征feat_res。
分类网络用两级 TransitionDown(128→128、256→256,邻居数 32)把 1024 点降到 256 点(见 pct.py),从而在保持几何结构的同时大幅压缩后续自注意力的计算量。
训练脚本详解:参数、优化器与数据流
分类脚本 train_cls.py
命令行参数(见 train_cls.py):
| 参数 | 默认值 | 说明 |
|---|---|---|
--dataset-path |
"" |
本地 ModelNet40 数据目录;为空时自动下载到 DGL 数据目录 |
--load-model-path |
"" |
加载已有模型权重路径(续训/推理用) |
--save-model-path |
"" |
保存最优模型权重路径(最优测试准确率时保存) |
--num-epochs |
250 |
训练轮数 |
--num-workers |
8 |
DataLoader 工作进程数 |
--batch-size |
32 |
批大小(训练与测试一致) |
训练配置要点:
- 优化器:SGD,
lr=0.01、weight_decay=1e-4、momentum=0.9(train_cls.py); - 学习率调度:
CosineAnnealingLR,T_max等于num_epochs,每个 epoch 结束时 step 一次(train_cls.py); - 数据加载:每个点云固定采样 1024 个点,训练/测试分别使用
ModelNetDataLoader(..., split="train"/"test");训练集shuffle=True, drop_last=True; - 数据流:脚本关闭了 cuDNN(
torch.backends.cudnn.enabled = False),每批数据先转 numpy 做增强(见下节),再转回 tensor 送入网络; - 评估与保存:每个 epoch 结束即在测试集上评估,记录最优测试准确率,并在指定
--save-model-path时保存最优权重。
分割脚本 train_partseg.py
分割脚本参数与分类基本一致,差异点包括:
| 参数 | 默认值 | 说明 |
|---|---|---|
--num-epochs |
500 |
训练轮数 |
--batch-size |
16 |
批大小(ShapeNet 每点云 2048 点,显存占用更大) |
--tensorboard |
False |
开启后使用 TensorBoard 记录损失、精度、mIoU 及预测点云网格可视化 |
数据流与评估细节:
- 数据集为
ShapeNet(2048, normal_channel=False),每点云采样 2048 个点,仅使用 3 维坐标(ShapeNet.py); collate函数把样本拆成(graphs, cat)——注意这里的graphs变量实际对应dgl.batch前的样本列表(train_partseg.py);- 训练时按样本类别构造 16 维 one-hot 张量(
np.eye(16)[cat_ind])作为类别条件输入; - 评估指标为 mIoU(平均交并比) 与 per-Category mIoU(逐类别平均 mIoU),每 5 个 epoch(含第 0 个 epoch)评估一次,并打印每个部件类别的 mIoU 明细(train_partseg.py);
- 开启
--tensorboard后,会把预测点云按 50 色调色板染色并通过add_mesh可视化(train_partseg.py)。
数据预处理与增强:精度差异的关键因素
ModelNet40 数据加载
ModelNetDataLoader(ModelNetDataLoader.py)要点:
- 自动读取
modelnet40_shape_names.txt、modelnet40_train.txt/modelnet40_test.txt划分文件,构建(类别, 文件路径)列表; - 默认取每点云前 1024 个点(
fps=False时截取,fps=True时用最远点采样),并对坐标执行pc_normalize:减去质心后除以最大半径(ModelNetDataLoader.py); - 默认保留法向通道(
normal_channel=True),即输入特征为 6 维(3 坐标 + 3 法向);normal_channel=False时仅保留 3 维坐标; - 提供
cache_size=15000的内存缓存,避免重复读盘。
训练增强组合(PointNet++ 风格)
分类训练脚本在每批数据上依次调用以下增强函数(train_cls.py),全部定义于 provider.py:
random_point_dropout:以 0~0.875 的随机比例将点替换为第一个点(模拟遮挡);random_scale_point_cloud:每个点云乘上 [0.8, 1.25] 的随机缩放;jitter_point_cloud:每个点加高斯噪声(sigma=0.01,clip=0.05);shift_point_cloud:每个点云加 [-0.1, 0.1] 的随机平移。
provider.py 中还额外提供了绕 Z 轴/任意轴的随机旋转(rotate_point_cloud 系列)、小角度扰动(rotate_perturbation_point_cloud)、normalize_data、shuffle_data 等增强工具,可按需替换组合。
分割任务的数据增强在 ShapeNet.py 的 translate 方法中完成:对每个点云施加 [2/3, 3/2] 的随机各向异性缩放与 [-0.2, 0.2] 的随机平移。
重要提示:README 明确指出,若将增强换成论文原文的方案([−0.2, 0.2] 随机平移、[0.67, 1.5] 各向异性缩放、随机输入 dropout),分类精度会从 92.1 掉到 84.5。因此复现时请保留示例默认增强,这直接决定了最终分数的可达性。
从源码结构看:与 PointNet++ 示例的差异与联系
同一 pointcloud 目录下还有 pointnet(PointNet/PointNet++)、edgeconv、point_transformer、bipointnet 等示例。PCT 与 PointNet++ 示例共享了同一套数据加载与增强基础设施(README 明确说明使用了 PointNet++ 的预处理),区别在于特征聚合方式:PointNet++ 依赖多尺度球查询与 max-pooling,而 PCT 改用 KNN 图上的 Transformer 自注意力,把"邻居关系"显式建模为 DGL 图的边,体现了 DGL 在点云这类不规则数据上的通用表达能力。
常见问题与调参建议
- 首次运行很慢/卡住:脚本首次运行会自动下载约数百 MB 的数据集,网络受限时可先用
--dataset-path指向已手动下载并解压好的本地目录; - 显存不足(OOM):分割任务默认 2048 点 + batch 16,可降低
--batch-size;分类任务可尝试 1024 点 + batch 32 的默认配置,若仍溢出可减小 batch; - 想快速验证代码可运行:先以
--num-epochs 1运行,确认数据下载、训练循环与评估链路正常后再开启完整训练; - 断点续训:用
--save-model-path保存最优权重,用--load-model-path加载后继续训练; - 追求论文分数:务必保持 PointNet++ 风格增强,切勿切回论文原始增强参数(会导致分类精度大幅下降至 84.5);
- 环境要求:示例基于 PyTorch 后端,需安装
dgl(含 PyTorch 支持)、torch、numpy、scipy、tqdm;README 中的性能数据基于 Tesla T4 GPU 测得,CPU 训练耗时将显著增加。
小结
本文围绕 DGL 官方 PCT 示例,完整梳理了 ModelNet40 分类与 ShapeNet 部件分割两个任务的复现路径:从 python train_cls.py / python train_partseg.py 两条启动命令出发,深入解读了 PCT 自注意力层(SALayer)、位置嵌入、TransitionDown 降采样在 helper.py 中的 DGL 图实现,以及训练脚本的优化器、学习率调度、数据增强与 mIoU 评估细节。若需要进一步对照同目录下的其他点云模型,可参考 PointNet/PointNet++ 示例 与 point_transformer 示例 的 README,它们共享同一套数据管线,便于横向比较不同聚合策略在点云任务上的效果。