DGL 复现 Point Transformer:点云分类与部件分割的图注意力实战指南

原创2026-09-22 22:22:372,299 阅读
文章标签:深度学习机器学习人工智能图计算分布式训练高性能计算数据科学

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,其前向过程可拆解为五步:

  1. 建邻:对输入点坐标 pos 计算两两平方距离 square_distance(pos, pos),按距离排序取前 n_neighbors 个近邻索引,用 index_points 取出近邻坐标 knn_pos;
  2. 特征投影:fc1 将输入特征映射到 transformer_dim 维得到 h,随后通过三个无偏置线性层 w_qs / w_ks / w_vs 分别生成 query、key、value;
  3. 位置编码:fc_delta 对“中心点坐标 − 近邻坐标”的相对位置(pos[:, :, None] - knn_pos)做两层 MLP(线性 + ReLU + 线性),得到逐邻域的位置编码 pos_enc;
  4. 注意力计算:fc_gamma 处理 q - k + pos_enc 得到注意力权重,除以 sqrt(k.size(-1)) 后在邻域维做 softmax;
  5. 聚合与残差:用注意力权重对 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 的核心逻辑:

  1. 对每个 batch 样本,以 centroids(下采样中心点)为源、k 近邻点为目标建立边;
  2. 把每个样本的 (src_idx, dst_idx) 经 torch.unique 统一编号后调用 dgl.graph((src_idx, dst_idx)) 构图;
  3. 将点坐标写入 g.ndata["pos"]、中心点标记写入 g.ndata["center"]、可选特征写入 g.ndata["feat"];
  4. 最后 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 是编码器下采样的关键:

  1. 调用 dgl.geometry.farthest_point_sampler(pos, self.n_points) 从当前点集中选出目标数量的中心点索引。该算子由 DGL 官方实现(python/dgl/geometry/fps.py),无需预先计算所有点对距离:先在每批随机选定起始点,维护“每个点到已采样点集的最小距离”,反复挑选距离最大者,直到采够 npoints 个点;
  2. 以中心点为聚合目标建立 kNN 图并完成消息传递;
  3. 用 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):

  1. provider.random_point_dropout(data):随机丢弃最多 87.5% 的点(用首点填充);
  2. provider.random_scale_point_cloud(data[:, :, 0:3]):每个点云随机缩放 0.8~1.25 倍;
  3. provider.jitter_point_cloud(data[:, :, 0:3]):逐点高斯抖动(σ=0.01,截断 0.05);
  4. 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 自注意力 + 图神经网络消息传递 + 多尺度编码解码”三类技术在点云任务上的结合方式,其价值主要体现在:

  1. 可直接复现:两条命令即可训练分类/分割模型,双优化器策略让复现实验具备对照意义;
  2. 组件可复用:KNNGraphBuilder、TransitionDown/Up、FeaturePropagation 均与数据集解耦,可迁移到 PointNet++ 风格的其他点云模型;
  3. 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 等其他点云示例,横向比较不同点云骨干在相同数据集上的表现。
登录后查看全文
dgl