DGL 复现 Point Transformer:点云分类与部件分割的图注意力实战指南
DGL 复现 Point Transformer:点云分类与部件分割的图注意力实战指南
本文以 DGL(Deep Graph Library)开源仓库中的 Point Transformer 示例 为核心,讲解如何基于 DGL 与 PyTorch 复现 2020 年提出的 Point Transformer 点云 Transformer 模型,涵盖模型结构、图消息传递实现、ModelNet40 点云分类与 ShapeNet 部件分割两套完整训练流程,以及优化器与数据增强等实战细节。读完本文,你将能独立运行该示例并在自定义点云任务中复用其图建边、最远点采样与特征传播的代码思路。
一、项目背景:为什么在 DGL 中复现 Point Transformer
Point Transformer 由论文 Point Transformer(arXiv:2012.09164)提出,其核心思想是将 Transformer 的自注意力机制引入点云处理:以每个点为中心,在其 k 近邻构成的局部邻域内计算注意力,从而在保留点云原始坐标信息的同时建模点间的相互关系。
本仓库中的实现于 2021 年 8 月 27 日完成,当时官方尚未发布代码,因此复现工作基于社区实现 qq456cvb/Point-Transformers)。与社区版本不同的是,本示例充分利用了 DGL 的图编程能力:
- 借助
dgl.graph与dgl.batch构建批量化的 k 近邻有向图; - 借助
dgl.geometry.farthest_point_sampler完成下采样层的中心点选取; - 通过
update_all消息传递机制实现邻域特征聚合。
示例目录位于 examples/pytorch/pointcloud/point_transformer/,包含以下文件:
| 文件 | 职责 |
|---|---|
point_transformer.py |
模型主体:PointTransformerBlock、编码器/解码器、分类与分割头 |
helper.py |
图构建(KNNGraphBuilder)、下采样(TransitionDown)、上采样(TransitionUp)等组件 |
train_cls.py |
ModelNet40 点云分类训练脚本 |
train_partseg.py |
ShapeNet 部件分割训练脚本 |
ModelNetDataLoader.py |
ModelNet40 数据加载与归一化 |
ShapeNet.py |
ShapeNet 部件分割数据加载与 16 类划分 |
provider.py |
训练数据增强工具集 |
二、复现性能表现
原文档给出了本实现与论文报告分数的对比(训练于 EC2 p3.8xlarge 实例、单张 Tesla V100 GPU,时间项为每 epoch 的平均训练耗时):
| 任务 | 数据集 | 指标 | 论文分数 | DGL (Adam) | DGL (SGD) | DGL 耗时(s) |
|---|---|---|---|---|---|---|
| 分类 | ModelNet40 | Accuracy | 93.7 | 92.0 | 91.5 | 117.0 |
| 部件分割 | ShapeNet | mIoU | 86.6 | 84.3 | 85.1 | 260.0 |
从表格可以看到:
- Adam 优化器在分类任务上表现更好(92.0 vs 91.5);
- SGD 优化器在部件分割任务上反而更优(85.1 vs 84.3);
- 两套任务的复现精度均与论文结果接近,验证了实现的正确性。
值得一提的是,两套训练脚本均同时内置了 Adam 与 SGD 两套优化策略(--opt 参数切换),这正是复现实验“双优化器对照”的价值所在,后文将详细介绍两者的参数差异。
三、快速开始:运行分类与分割训练
3.1 环境要求
- Python 3 环境,安装 DGL 与 PyTorch(安装方式可参考仓库 docs/source/install 目录下的官方安装指南);
- 训练脚本依赖
tqdm、numpy,分割脚本额外依赖scipy(用于稀疏矩阵)与可选依赖torchvision(用于 TensorBoard 可视化); - 推荐使用带 CUDA 的 GPU 环境(脚本会自动检测:
dev = torch.device("cuda" if torch.cuda.is_available() else "cpu"))。
3.2 运行点云分类
python train_cls.py --opt [sgd/adam]
其中 --opt 可取 sgd 或 adam。首次运行脚本会自动从 https://shapenet.cs.stanford.edu/media/modelnet40_normal_resampled.zip 下载 ModelNet40 数据集(含法线、重采样版本),下载与解压到 DGL 的数据缓存目录(dgl.data.utils.get_download_dir()),后续运行会直接复用本地数据。
3.3 运行点云部件分割
python train_partseg.py --opt [sgd/adam]
分割脚本会自动下载 ShapeNet Core 部件分割数据集(shapenetcore_partanno_segmentation_benchmark_v0_normal.zip),涵盖 16 个物体大类(如 Airplane、Bag、Car、Chair 等),共 50 个部件语义类别。
四、模型结构深度剖析
4.1 PointTransformerBlock:局部邻域自注意力
模型的基本计算单元是 PointTransformerBlock,其前向过程可拆解为五步:
- 建邻:对输入点坐标
pos计算两两平方距离square_distance(pos, pos),按距离排序取前n_neighbors个近邻索引,用index_points取出近邻坐标knn_pos; - 特征投影:
fc1将输入特征映射到transformer_dim维得到h,随后通过三个无偏置线性层w_qs / w_ks / w_vs分别生成 query、key、value; - 位置编码:
fc_delta对“中心点坐标 − 近邻坐标”的相对位置(pos[:, :, None] - knn_pos)做两层 MLP(线性 + ReLU + 线性),得到逐邻域的位置编码pos_enc; - 注意力计算:
fc_gamma处理q - k + pos_enc得到注意力权重,除以sqrt(k.size(-1))后在邻域维做 softmax; - 聚合与残差:用注意力权重对
v + pos_enc做加权求和(torch.einsum("bmnf,bmnf->bmf", ...)),经fc2后与输入x相加,构成残差连接。
核心超参数 n_neighbors(默认 16)直接控制每个中心点聚合的邻域规模,transformer_dim 默认与 input_dim 一致。
4.2 编码器:PointTransformer 主干网络
PointTransformer 组织为“一层初始 Transformer 块 + 若干下采样阶段”的金字塔结构,关键参数如下:
n_points:输入点云点数(分类 1024,分割 2048);n_blocks(默认 4):下采样阶段数;downsampling_rate(默认 4):每阶段点数缩减倍率;hidden_dim(默认 32):初始隐藏维,第 i 阶段翻倍为hidden_dim * 2**(i+1);- 第 i 阶段点数为
n_points // downsampling_rate**(i+1)。
前向过程中,每个阶段先由 TransitionDown 完成“选点 + 聚合”,再由一个 PointTransformerBlock 精炼特征,同时把各阶段 (pos, h) 存入 hidden_state 供解码器使用——这与 PointNet++ 等经典点云编码器保持了一致的多尺度设计。
4.3 解码器:TransitionUp 与特征传播
PointTransformerSeg 在编码器输出的最深层特征上先经 fc + 一个 Transformer 块提炼,随后逐级上采样:
- 每一级
TransitionUp接收深层(pos1, feat1)与浅层(pos2, feat2),通过 FeaturePropagation 基于 3 近邻的距离反比加权插值(dist_recip = 1.0 / (dists + 1e-8))把深层特征回传到浅层坐标,并与浅层特征相加; - 每个上采样阶段之后紧跟一个
PointTransformerBlock细化特征; - 最后把解码器输出与类别 one-hot 向量
cat_vec拼接,经三层 MLP 映射到 50 个部件类别。
4.4 分类头
PointTransformerCLS 复用编码器主干,对最深层特征做全局平均池化(torch.mean(h, dim=1)),再经 Linear → ReLU → Linear → ReLU → Linear 输出 40 类(ModelNet40)的 logits。
五、DGL 图计算在模型中的落地
本示例最有 DGL 特色的是 helper.py 中的三个组件,它们把“建图 + 消息传递 + 图池化”串成了标准的 DGL 编程范式。
5.1 KNNGraphBuilder:把点云转成 DGL 批量图
KNNGraphBuilder 的核心逻辑:
- 对每个 batch 样本,以
centroids(下采样中心点)为源、k 近邻点为目标建立边; - 把每个样本的
(src_idx, dst_idx)经torch.unique统一编号后调用dgl.graph((src_idx, dst_idx))构图; - 将点坐标写入
g.ndata["pos"]、中心点标记写入g.ndata["center"]、可选特征写入g.ndata["feat"]; - 最后
dgl.batch(glist)把批量样本打包成一张大图,供后续消息传递统一处理。
5.2 RelativePositionMessage + KNNConv:图消息传递聚合
- RelativePositionMessage 作为边函数,计算
edges.src["pos"] - edges.dst["pos"]的相对位置,并与源点特征拼接成agg_feat; - KNNConv 作为节点函数,把
nodes.mailbox["agg_feat"]按 batch 维度 reshape 成(B, C, N, K),经 1×1 卷积 + BatchNorm + ReLU 后做 max pooling,聚合邻域特征。
两者通过 g.update_all(self.message, self.conv) 完成一次完整的消息传递(见 TransitionDown.forward)。
5.3 TransitionDown:最远点采样驱动的下采样
TransitionDown 是编码器下采样的关键:
- 调用
dgl.geometry.farthest_point_sampler(pos, self.n_points)从当前点集中选出目标数量的中心点索引。该算子由 DGL 官方实现(python/dgl/geometry/fps.py),无需预先计算所有点对距离:先在每批随机选定起始点,维护“每个点到已采样点集的最小距离”,反复挑选距离最大者,直到采够npoints个点; - 以中心点为聚合目标建立 kNN 图并完成消息传递;
- 用
g.ndata["center"] == 1掩码取出中心点的坐标与聚合特征,view(batch_size, -1, dim)还原回[B, S, C]形状。
由此每个下采样阶段都实现了“图内聚合、掩码取点”,天然兼容批量训练。
六、点云分类实战:train_cls.py 详解
6.1 命令行参数
train_cls.py 支持的参数及默认值如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
--dataset-path |
"" |
本地 ModelNet40 数据根目录;留空则自动下载 |
--load-model-path |
"" |
预训练权重路径(恢复训练/评估用) |
--save-model-path |
"" |
最优模型保存路径(测试精度提升时保存) |
--num-epochs |
200 |
训练轮数 |
--num-workers |
8 |
DataLoader 加载进程数 |
--batch-size |
16 |
批大小 |
--opt |
adam |
优化器:sgd 或 adam |
分类网络构造为 PointTransformerCLS(40, batch_size, feature_dim=6),即 40 个输出类、输入特征 6 维(XYZ + 法线)。
6.2 双优化器配置:论文策略 vs 社区策略
脚本中 --opt 对应两套完整策略(train_cls.py):
SGD(论文中的优化策略)
opt = torch.optim.SGD(
net.parameters(), lr=0.01, momentum=0.9, weight_decay=1e-4
)
scheduler = torch.optim.lr_scheduler.MultiStepLR(
opt, milestones=[120, 160], gamma=0.1
)
Adam(社区复现采用的策略)
opt = torch.optim.Adam(
net.parameters(),
lr=1e-3,
betas=(0.9, 0.999),
eps=1e-08,
weight_decay=1e-4,
)
scheduler = torch.optim.lr_scheduler.StepLR(opt, step_size=50, gamma=0.3)
两者学习率调度差异显著:SGD 在 120/160 epoch 处各衰减 10 倍;Adam 每 50 epoch 衰减为原来的 0.3 倍。两套策略与第二节的性能对照表一一对应,读者可据此复现 92.0/91.5 的分类精度。
6.3 训练流程与数据增强
每个 epoch 的 train 函数会依次执行四步数据增强(train_cls.py):
provider.random_point_dropout(data):随机丢弃最多 87.5% 的点(用首点填充);provider.random_scale_point_cloud(data[:, :, 0:3]):每个点云随机缩放 0.8~1.25 倍;provider.jitter_point_cloud(data[:, :, 0:3]):逐点高斯抖动(σ=0.01,截断 0.05);provider.shift_point_cloud(data[:, :, 0:3]):整云随机平移 ±0.1。
以上增强函数均实现在 provider.py(如 jitter_point_cloud、shift_point_cloud、random_scale_point_cloud、random_point_dropout),并且只作用于 XYZ 前 3 维,法线通道保持不变。
训练循环为:前向 → CrossEntropyLoss → 反向 → opt.step(),随后 scheduler.step();每个 epoch 结束时在测试集评估,若精度创新高且指定了 --save-model-path 则保存权重。注意脚本开头设置了 torch.backends.cudnn.enabled = False。
6.4 数据加载细节
ModelNet40 数据由 ModelNetDataLoader.py 负责读取:每个点云取前 1024 个点(fps=False 时不走最远点采样),XYZ 通道执行“去质心 + 除以最大半径”的归一化(pc_normalize),并通过 cache_size=15000 的内存缓存加速重复访问。
七、部件分割实战:train_partseg.py 详解
7.1 任务设定
ShapeNet 部件分割按 16 个物体大类分别定义其部件类别集合(ShapeNet.py),例如:
- Airplane:部件类别 [0,1,2,3](机身、机翼等 4 类);
- Chair:部件类别 [12,13,14,15](椅背、椅座等 4 类);
- Motorbike:部件类别 [24,25,26,27] 之外的 [28,29,30,31,32,33,34,35],共 8 类。
全部 16 类共计 50 个部件语义类别,因此分割网络输出为 PointTransformerSeg(50, batch_size)。数据切分遵循数据集自带的 shuffled_train/val/test_file_list.json,训练使用 trainval(训练 + 验证)集合。
7.2 训练与评估指标
train_partseg.py 相比分类脚本新增了:
--tensorboard:开启 TensorBoard 记录,用writer.add_mesh可视化预测着色的点云网格(内置 50 色调色板color_map为每个部件类别上色),并记录每 epoch 耗时、AvgLoss、AvgAcc、测试 mIoU 等标量;- mIoU 评估:
evaluate按物体类别分组计算部件 IoU(对每个样本,取该物体类别部件集合上的交集/并集比均值),输出整体 mIoU 与 per-Category mIoU,并可逐类打印; - 每 5 个 epoch(含 epoch 0)评估一次测试集,保存最优模型。
7.3 类别条件输入
分割训练要求模型感知物体大类,脚本为每个样本构造 16 维 one-hot 类别向量,并 repeat(1, 2048) 扩展为逐点向量:
cat_ind = [category_list.index(c) for c in cat]
cat_tensor = torch.tensor(eye_mat[cat_ind]).to(dev, dtype=torch.float).repeat(1, 2048)
cat_tensor = cat_tensor.view(num_examples, -1, 16)
该 cat_tensor 作为 cat_vec 传入 PointTransformerSeg.forward(x, cat_vec),最终与解码特征拼接后分类(见 point_transformer.py)。
7.4 损失与上采样链
- 损失函数 PartSegLoss 把
[B, C, N]的 logits 置换为[B*N, C]后计算CrossEntropyLoss; - 解码器按
for i in range(self.n_blocks)逐级执行TransitionUp+ Transformer 块,从最深层一路恢复到原始 2048 点分辨率,保证逐点预测的精度。
八、总结与二次开发建议
本示例完整呈现了“Transformer 自注意力 + 图神经网络消息传递 + 多尺度编码解码”三类技术在点云任务上的结合方式,其价值主要体现在:
- 可直接复现:两条命令即可训练分类/分割模型,双优化器策略让复现实验具备对照意义;
- 组件可复用:
KNNGraphBuilder、TransitionDown/Up、FeaturePropagation均与数据集解耦,可迁移到 PointNet++ 风格的其他点云模型; - DGL 能力示范:
dgl.graph、dgl.batch、update_all、farthest_point_sampler的组合展示了如何用图 API 高效组织点云邻域计算。
如果你希望在此示例基础上扩展,可重点关注以下方向(均在仓库源码中有对应实现可参考):
- 将
helper.py中的图构建与聚合逻辑替换为dgl.nn提供的现成图卷积层以对比精度差异; - 调整
PointTransformerBlock的n_neighbors与downsampling_rate,观察对精度与训练耗时(分类 117s/epoch、分割 260s/epoch,V100)的影响; - 参考 examples/pytorch/pointcloud 下的
pointnet、pct、edgeconv等其他点云示例,横向比较不同点云骨干在相同数据集上的表现。