📌 描述

Superpoint Transformer

Superpoint Transformer (SPT) 是一种基于superpoint的Transformer架构🤖，能够高效⚡地对大规模3D场景进行语义分割。该方法包含一个快速算法，可以将点云分割成层次化的superpoint结构，同时利用自注意力机制来挖掘不同尺度下superpoint之间的关系。

SuperCluster

SuperCluster 是一种基于超点的架构，用于对（非常）大型 3D 场景进行全景分割 🐘，其基础为 SPT。我们将全景分割任务建模为一个 可扩展的超点图聚类 问题。为此，我们的模型被训练来预测一个图优化问题的输入参数，该问题的解即为全景分割结果 💡。这种建模方式使得我们仅需使用节点级和边级的目标函数来监督模型训练，从而避免了在训练时计算实际的全景分割结果以及相关的匹配问题。

在推理阶段，我们高效的并行化算法会求解这个小型的图优化问题，最终生成物体实例 👥。由于其轻量级的骨干网络和可扩展的建模方式，SuperCluster 能够在单个 GPU 上一次性处理前所未有的大规模场景 🚀，且模型参数量不足 100 万 🦋。

EZ-SP (Easy Superpoints)

EZ-SP 相较于 SPT 主要有两项改进：

• 预处理和推理速度大幅提升
• 分割参数化更加简单且可学习

EZ-SP 用一种 快速且可学习的 GPU 加速分割方法 替代了 SPT 中耗时的、基于 CPU 的切分追踪分割步骤。首先，我们训练一个小型卷积骨干网络，将输入场景中的每个点嵌入到低维空间中，在该空间内，来自不同语义类别的相邻点会被相互推开。随后，我们新开发的 GPU 加速图聚类算法 会将具有相似嵌入特征的邻近点分组在一起，同时鼓励形成简洁的簇边界，从而生成语义上同质的超点。这些超点可以进一步用于 SPT 的语义分割框架中。

注：如果您主要关注的是 EZ-SP 论文（https://arxiv.org/abs/2512.00385）中提出的快速图连通分量及分割算法，请参阅我们的 torch-graph-components 库。

📰 更新

• 31.01.2026 我们的论文EZ-SP：基于超点的快速轻量级3D分割已被**ICRA'26**接收 🥳
• 22.01.2026 将EZ-SP中引入的图连通分量和图划分算法以独立库的形式发布： torch-graph-components。 我们希望这能促进这些核心组件在其他基于图的项目中的应用。
• 27.11.2025 针对我们的可学习、GPU加速的划分的重大代码发布，实现了 EZ-SP：基于超点的快速轻量级3D分割。 新版本对代码库进行了一些不向后兼容的改动。 我们尽力记录了这些破坏性变更，并提供了说明和脚本，帮助旧版本用户迁移到新的代码库。 更多详情请参阅CHANGELOG❗
• 27.06.2024 发布了我们的Superpoint Transformer🧑‍🏫教程： 幻灯片、 笔记本以及视频。 如果你刚开始接触这个项目，不妨看看这些资料！
• 21.06.2024 Damien将于**📅 27.06.2024 下午1点（CEST）举办一场关于Superpoint Transformer的🧑‍🏫教程**。 如果你想获得该项目的实际操作经验，一定要来参加！ 注册链接。
• 28.02.2024 针对全景分割的重大代码发布，实现了 基于超点图聚类的可扩展3D全景分割。 新版本还实现了备受期待的功能，如Lightning的predict()行为、 体素分辨率和全分辨率预测。 部分依赖项和仓库结构的更改是不向后兼容的。如果你之前使用过旧版本的代码，建议重新安装你的conda环境，并重新运行数据预处理或数据集处理❗
• 15.10.2023 我们的论文**基于超点图聚类的可扩展3D全景分割被接受在3DV'24上作口头报告** 🥳
• 06.10.2023 欢迎参观我们在**ICCV'23上展示的海报， 主题为利用Superpoint Transformer实现高效的3D语义分割**。
• 14.07.2023 我们的论文**利用Superpoint Transformer实现高效的3D语义分割被ICCV'23**接收 🥳
• 15.06.2023 正式发布 🌱

💻 环境要求

该项目已在以下环境中测试通过：

• Linux操作系统
• 64G 内存
• NVIDIA GTX 1080 Ti 11G、NVIDIA V100 32G、NVIDIA A40 48G
• CUDA 11.8 和 12.1
• conda 23.3.1

🏗 安装

只需运行install.sh，即可在名为spt的新conda环境中安装所有依赖项。

# 创建名为'spt'的conda环境并安装依赖
./install.sh

可选依赖：TorchSparse是一个可选依赖，支持稀疏3D卷积，用于EZ-SP模型中。若需安装包含该依赖的环境，请使用：

# 创建名为'spt'的conda环境并安装所有依赖项 + TorchSparse
./install.sh with_torchsparse

注：请参阅数据集页面，了解如何设置你的数据集路径和文件结构。

🔩 项目结构

└── superpoint_transformer
    │
    ├── configs                   # Hydra配置文件
    │   ├── callbacks                 # 回调配置
    │   ├── data                      # 数据配置
    │   ├── debug                     # 调试配置
    │   ├── experiment                # 实验配置
    │   ├── extras                    # 其他工具配置
    │   ├── hparams_search            # 超参数搜索配置
    │   ├── hydra                     # Hydra配置
    │   ├── local                     # 本地配置
    │   ├── logger                    # 日志配置
    │   ├── model                     # 模型配置
    │   ├── paths                     # 项目路径配置
    │   ├── trainer                   # 训练配置
    │   │
    │   ├── eval.yaml                 # 评估主配置
    │   └── train.yaml                # 训练主配置
    │
    ├── data                      # 项目数据（详见docs/datasets.md）
    │
    ├── docs                      # 文档
    │
    ├── logs                      # 由hydra和lightning日志器生成的日志
    │
    ├── media                     # 展示项目的媒体资源
    │
    ├── notebooks                 # Jupyter笔记本
    │
    ├── scripts                   # Shell脚本
    │
    ├── src                       # 源代码
    │   ├── data                      # 分层划分的数据结构
    │   ├── datamodules               # Lightning DataModules
    │   ├── datasets                  # 数据集
    │   ├── dependencies              # 编译后的依赖
    │   ├── loader                    # DataLoader
    │   ├── loss                      # 损失函数
    │   ├── metrics                   # 指标
    │   ├── models                    # 模型架构
    │   ├── nn                        # 模型构建模块
    │   ├── optim                     # 优化
    │   ├── transforms                # 变换、预变换等功能
    │   ├── utils                     # 工具函数
    │   ├── visualization             # 交互式可视化工具
    │   │
    │   ├── eval.py                   # 运行评估
    │   └── train.py                  # 运行训练
    │
    ├── tests                     # 各类测试
    │
    ├── .env.example              # 存储私有环境变量的示例文件
    ├── .gitignore                # Git忽略的文件列表
    ├── .pre-commit-config.yaml   # 代码格式化预提交钩子配置
    ├── install.sh                # 安装脚本
    ├── LICENSE                   # 项目许可证
    └── README.md

注：有关data/的更多信息，请参阅数据集页面。

注：有关logs/的更多信息，请参阅日志页面。

🚀 使用

数据集

请参阅数据集页面，以设置你的数据集。

评估

使用以下命令结构从检查点文件 checkpoint.ckpt 评估我们的模型，其中 <task> 应为 semantic 表示使用 SPT，panoptic 表示使用 SuperCluster：

# 在 <dataset> 数据集上评估 <task> 分割任务
python src/eval.py experiment=<task>/<dataset> ckpt_path=/path/to/your/checkpoint.ckpt

一些示例：

# 在 S3DIS 第 5 折上评估 SPT
python src/eval.py experiment=semantic/s3dis datamodule.fold=5 ckpt_path=/path/to/your/checkpoint.ckpt

# 在 KITTI-360 验证集上评估 SPT
python src/eval.py experiment=semantic/kitti360  ckpt_path=/path/to/your/checkpoint.ckpt 

# 在 DALES 上评估 SPT
python src/eval.py experiment=semantic/dales ckpt_path=/path/to/your/checkpoint.ckpt

# 在 S3DIS 第 5 折上评估 SuperCluster
python src/eval.py experiment=panoptic/s3dis datamodule.fold=5 ckpt_path=/path/to/your/checkpoint.ckpt

# 在 S3DIS 第 5 折上评估 SuperCluster，将 {wall, floor, ceiling} 定义为 'stuff'
python src/eval.py experiment=panoptic/s3dis_with_stuff datamodule.fold=5 ckpt_path=/path/to/your/checkpoint.ckpt

# 在 ScanNet 验证集上评估 SuperCluster
python src/eval.py experiment=panoptic/scannet ckpt_path=/path/to/your/checkpoint.ckpt

# 在 KITTI-360 验证集上评估 SuperCluster
python src/eval.py experiment=panoptic/kitti360  ckpt_path=/path/to/your/checkpoint.ckpt 

# 在 DALES 上评估 SuperCluster
python src/eval.py experiment=panoptic/dales ckpt_path=/path/to/your/checkpoint.ckpt

# 在 DALES 上评估 EZ-SP
python src/eval.py experiment=semantic/dales_ezsp ckpt_path=/path/to/your/checkpoint.ckpt datamodule.pretrained_cnn_ckpt_path=/path/to/your/partition_checkpoint.ckpt

注意：

SPT 和 SPT-nano 模型在 S3DIS 6-Fold、KITTI-360 Val 和 DALES 上的预训练权重可在以下链接获取：

SuperCluster 模型在 S3DIS 6-Fold、S3DIS 6-Fold with stuff、ScanNet Val、KITTI-360 Val 和 DALES 上的预训练权重可在以下链接获取：

EZ-SP 模型在 S3DIS 6-Fold、KITTI-360 Val 和 DALES 上的预训练权重可在以下链接获取：

训练

SPT & SuperCluster

使用以下命令结构在 32G 显存的 GPU 上训练我们的模型，其中 <task> 应为 semantic 表示使用 SPT，panoptic 表示使用 SuperCluster：

# 在 <dataset> 数据集上训练 <task> 分割任务
python src/train.py experiment=<task>/<dataset>

一些示例：

# 在 S3DIS 第 5 折上训练 SPT
python src/train.py experiment=semantic/s3dis datamodule.fold=5

# 在 KITTI-360 验证集上训练 SPT
python src/train.py experiment=semantic/kitti360 

# 在 DALES 上训练 SPT
python src/train.py experiment=semantic/dales

# 在 S3DIS 第 5 折上训练 SuperCluster
python src/train.py experiment=panoptic/s3dis datamodule.fold=5

# 在 S3DIS 第 5 折上训练 SuperCluster，并将 {wall, floor, ceiling} 定义为 'stuff'
python src/train.py experiment=panoptic/s3dis_with_stuff datamodule.fold=5

# 在 ScanNet 验证集上训练 SuperCluster
python src/train.py experiment=panoptic/scannet

# 在 KITTI-360 验证集上训练 SuperCluster
python src/train.py experiment=panoptic/kitti360 

# 在 DALES 上训练 SuperCluster
python src/train.py experiment=panoptic/dales

若需在 11G 显存的 GPU 上训练 💾（训练时间和性能可能会有所不同），可使用以下命令：

# 在 S3DIS 第 5 折上训练 SPT
python src/train.py experiment=semantic/s3dis_11g datamodule.fold=5

# 在 KITTI-360 验证集上训练 SPT
python src/train.py experiment=semantic/kitti360_11g 

# 在 DALES 上训练 SPT
python src/train.py experiment=semantic/dales_11g

# 在 S3DIS 第 5 折上训练 SuperCluster
python src/train.py experiment=panoptic/s3dis_11g datamodule.fold=5

# 在 S3DIS 第 5 折上训练 SuperCluster，并将 {wall, floor, ceiling} 定义为 'stuff'
python src/train.py experiment=panoptic/s3dis_with_stuff_11g datamodule.fold=5

# 在 ScanNet 验证集上训练 SuperCluster
python src/train.py experiment=panoptic/scannet_11g

# 在 KITTI-360 验证集上训练 SuperCluster
python src/train.py experiment=panoptic/kitti360_11g

# 在 DALES 数据集上训练 SuperCluster
python src/train.py experiment=panoptic/dales_11g

注意: 遇到 CUDA 内存不足错误 💀💾 吗？请参阅我们专门的 故障排除部分。

注意: 其他开箱即用的配置文件位于 configs/experiment/。您可以通过组合配置文件轻松设计自己的实验：

# 在 DALES 数据集上训练 Nano-3 模型 50 个 epoch
python src/train.py datamodule=dales model=nano-3 trainer.max_epochs=50

有关配置系统的工作原理以及 Lightning+Hydra 组合的所有强大优势，请参阅 Lightning-Hydra。

注意: 默认情况下，您的日志会自动上传到 Weights and Biases，您可以在那里跟踪和比较您的实验。其他日志记录器可在 configs/logger/ 中找到。有关日志记录选项的更多信息，请参阅 Lightning-Hydra。

注：当前 EZ-SP 实现支持 <dataset>，取值为 s3dis、kitti360 和 dales。

EZ-SP

我们的 EZ-SP 方法包含两个训练阶段。

1. 我们训练一个小型模型，用于学习超点划分的逐点特征，通过在语义边界上解决对比任务来实现。

2. 然后我们训练一个超点 Transformer 模型，该模型以这些点特征作为输入，并基于相关的层次化划分进行推理，通过解决语义分类任务来完成。

注意: 如果您主要关注的是在 EZ-SP 论文 中介绍的快速图连通分量及划分算法， 请查看我们的 torch-graph-components 库。

1. 训练划分模型

python src/train.py experiment=partition/<dataset>_ezsp

检查点应记录在 logs/train/runs/<run_dir>/checkpoints/last.ckpt （请检查您的 bash 和 wandb 日志 😉）。

注意: config/experiments/partition 中的实验会训练一个用于 EZ-SP 的小型稀疏 CNN，该网络将每个点嵌入到低维空间中，使得来自不同语义类别的相邻点被相互推开。 这一训练阶段由 model.training_partition_stage 参数控制。

2. 训练语义模型

python src/train.py experiment=semantic/<dataset>_ezsp datamodule.pretrained_cnn_ckpt_path=<partition_ckpt_path>

请确保设置划分模型的检查点路径 pretrained_cnn_ckpt_path。为此，您可以按照步骤 1 的说明训练您自己的划分模型，或者使用我们提供的预训练检查点（名为 ezsp_partition_<dataset>.ckpt）。

注意: config/experiments/semantic 中以 _ezsp 结尾的实验会训练完整的 EZ-SP 模型用于语义分割。请注意，这些配置需要指定划分模型的检查点路径，通过 datamodule.pretrained_cnn_ckpt_path 参数进行设置。预训练的划分模型用于在预处理阶段计算层次化的超点划分，而完整模型则在此基础上进行训练时的推理。

PyTorch Lightning predict()

SPT 和 SuperCluster 均继承自 LightningModule，并实现了 predict_step() 方法，这使得可以使用 PyTorch Lightning 的 Trainer.predict() 机制。

from src.models.semantic import SemanticSegmentationModule
from src.datamodules.s3dis import S3DISDataModule
from pytorch_lightning import Trainer

# 对语义分割任务从 torch DataLoader 中进行预测
dataloader = DataLoader(...)
model = SemanticSegmentationModule(...)
trainer = Trainer(...)
batch, output = trainer.predict(model=model, dataloaders=dataloader)

不过，这仍然需要您实例化一个 Trainer、一个 DataLoader，以及一个具有相关参数的模型。

为了更简便起见，我们所有的数据集都继承自 LightningDataModule，并实现了 predict_dataloader() 方法，默认指向各自的数据集测试集。这使得可以直接将数据模块传递给 PyTorch Lightning 的 Trainer.predict() 而无需显式地实例化 DataLoader。

from src.models.semantic import SemanticSegmentationModule
from src.datamodules.s3dis import S3DISDataModule
from pytorch_lightning import Trainer

# 对 S3DIS 数据集上的语义分割任务进行预测
datamodule = S3DISDataModule(...)
model = SemanticSegmentationModule(...)
trainer = Trainer(...)
batch, output = trainer.predict(model=model, datamodule=datamodule)

有关如何实例化这些组件以及我们模型输出格式的更多详细信息，我们强烈建议您尝试我们的 demo notebook，并查看 src/eval.py 脚本。

全分辨率预测

根据设计，我们的模型在训练过程中只需对 $P_1$ 分区级别的超点生成预测。所有损失和指标都是以超点为单位定义的。这在训练和评估时能够有效节省计算资源和内存。

然而，在推理阶段，我们通常需要获得 $P_0$ 分区级别的体素预测，或对全分辨率输入点云的预测。为此，我们提供了辅助函数来恢复体素级和全分辨率的预测结果。

有关这些内容的详细信息，请参阅我们的 demo notebook。

在自定义数据上使用预训练模型

如需在您自己的点云数据上运行预训练模型，请参考我们的教程幻灯片、笔记本以及视频。

在自定义数据上参数化超点划分

我们的层次化超点划分是在预处理阶段计算的。其构建过程涉及多个步骤，这些步骤的参数化需要根据您的特定数据集和任务进行调整。请参考我们的教程幻灯片、笔记本以及视频，以便更好地理解这一过程，并根据您的需求进行优化。

超簇图聚类的参数化

超簇的一个特殊之处在于，该模型并非直接训练用于进行全景分割，而是用于预测超像素图聚类问题的输入参数，而该问题的解即为全景分割结果。

因此，针对这一图优化问题的超参数是在训练完成后，通过在训练集或验证集上进行网格搜索来选择的。我们发现，在所有数据集上，使用大致相同的超参数都能获得最佳性能（详见我们的论文附录）。不过，您可能仍希望针对自己的数据集探索这些超参数。为此，请参阅我们的演示笔记本，以了解如何对全景分割进行参数化。

笔记本与可视化

我们提供了笔记本，帮助您快速上手操作我们的核心数据结构、配置加载、数据集和模型实例化、各数据集上的推理以及可视化。

特别地，我们开发了一个交互式可视化工具✨，可用于生成可分享的HTML文件。关于如何使用该工具的演示已在笔记本中提供。此外，此类HTML文件的示例也已收录在media/visualizations.7z中。

📚 文档

位置	内容
README	项目概述
docs/data_structures	介绍本项目的核心数据结构：Data、NAG、Cluster 和 InstanceData
docs/datasets	介绍我们实现的数据集、BaseDataset 类，以及如何创建您自己的继承自该类的数据集
docs/logging	介绍日志记录及项目的 logs/ 目录结构
docs/visualization	介绍我们的交互式3D可视化工具

注：我们尽可能地为代码添加了注释，以使该项目易于使用。如果您在 docs/ 中未能找到所需答案，请务必查看源代码和过往的问题。即便如此，若您仍觉得某些部分不够清晰，或认为需要更多文档说明，请随时通过提交问题告知我们！

👩‍🔧 故障排除

以下是一些常见问题及其解决方法。

SPT 或超簇在 11G 显存的 GPU 上运行

我们的默认配置是为 32G 显存的 GPU 设计的。然而，SPT 和超簇也可以在**11G 显存的 GPU 💾**上运行，只是在时间和性能上会有一些细微差异。

我们在 configs/experiment/semantic 中提供了在**11G 显存的 GPU 💾**上训练 SPT 的配置：

# 在 S3DIS 第5折上训练 SPT
python src/train.py experiment=semantic/s3dis_11g datamodule.fold=5

# 在 KITTI-360 验证集上训练 SPT
python src/train.py experiment=semantic/kitti360_11g 

# 在 DALES 数据集上训练 SPT
python src/train.py experiment=semantic/dales_11g

同样地，我们在 configs/experiment/panoptic 中提供了在**11G 显存的 GPU 💾**上训练超簇的配置：

# 在 S3DIS 第5折上训练超簇
python src/train.py experiment=panoptic/s3dis_11g datamodule.fold=5

# 将 {墙、地板、天花板} 视作“stuff”类别，在 S3DIS 第5折上训练超簇
python src/train.py experiment=panoptic/s3dis_with_stuff_11g datamodule.fold=5

# 在 ScanNet 验证集上训练超簇
python src/train.py experiment=panoptic/scannet_11g

# 在 KITTI-360 验证集上训练超簇
python src/train.py experiment=panoptic/kitti360_11g 

# 在 DALES 数据集上训练超簇
python src/train.py experiment=panoptic/dales_11g

CUDA 内存不足错误

遇到一些 CUDA OOM 错误 💀💾 吗？以下是一些可以根据错误发生时机调整的参数，以减少 GPU 内存占用。

影响 CUDA 内存的参数。

图例: 🟡 预处理 | 🔴 训练 | 🟣 推理（包括训练过程中的验证和测试）

参数	描述	发生阶段
datamodule.xy_tiling	根据规则的 XY 网格，将数据集瓦片分割成 xy_tiling^2 个更小的瓦片。适合 DALES 那样的理想正方形瓦片。请注意，这会影响训练步数。	🟡🟣
datamodule.pc_tiling	根据数据点的主要成分，将数据集瓦片分割成 2^pc_tiling 个更小的瓦片。适合 S3DIS 和 KITTI-360 那样的形状不一的瓦片。请注意，这会影响训练步数。	🟡🟣
datamodule.max_num_nodes	限制 训练批次 中 $P_1$ 分割节点/超点的数量。	🔴
datamodule.max_num_edges	限制 训练批次 中 $P_1$ 分割边的数量。	🔴
datamodule.voxel	增大体素大小会缩短预处理、训练和推理时间，但会降低性能。	🟡🔴🟣
datamodule.pcp_regularization	分割层级的正则化项。值越大，超点数量越少。	🟡🔴🟣
datamodule.pcp_spatial_weight	超点分割中 3D 位置的重要性。值越小，超点数量越少。	🟡🔴🟣
datamodule.pcp_cutoff	超点的最小尺寸。值越大，超点数量越少。	🟡🔴🟣
datamodule.graph_k_max	超点图中每个节点的最大邻接节点数。值越小，超边数量越少。	🟡🔴🟣
datamodule.graph_gap	超点图中相邻超点之间的最大距离。值越小，超边数量越少。	🟡🔴🟣
datamodule.graph_chunk	在 RadiusHorizontalGraph 预处理超点图时，减小该值以避免内存不足。	🟡
datamodule.dataloader.batch_size	控制加载的瓦片数量。每个 训练批次 由 batch_size*datamodule.sample_graph_k 次球面采样组成。推理则在 整个验证和测试瓦片 上进行，不进行球面采样。	🔴🟣
datamodule.sample_segment_ratio	在每个分割层级随机丢弃一部分超点。	🔴
datamodule.sample_graph_k	控制 训练批次 中的球面采样次数。	🔴
datamodule.sample_graph_r	控制 训练批次 中球面采样的半径。设置为 sample_graph_r<=0 可以不进行球面采样，直接使用整个瓦片。	🔴
datamodule.sample_point_min	控制 训练批次 中每个超点采样的 $P_0$ 点的最小数量。	🔴
datamodule.sample_point_max	控制 训练批次 中每个超点采样的 $P_0$ 点的最大数量。	🔴
callbacks.gradient_accumulator.scheduling	梯度累积。可用于以较小的批次进行训练，从而增加训练步数。	🔴

💬 引用我们的工作

如果您在工作中使用了本代码的全部或部分内容，请务必包含以下引用：

@article{robert2023spt,
  title={高效三维语义分割的超点Transformer},
  author={Robert, Damien and Raguet, Hugo and Landrieu, Loic},
  journal={IEEE/CVF国际计算机视觉会议论文集},
  year={2023}
}

@article{robert2024scalable,
  title={可扩展的三维全景分割：基于超点图的聚类},
  author={Robert, Damien and Raguet, Hugo and Landrieu, Loic},
  journal={IEEE三维视觉国际会议论文集},
  year={2024}
}

@article{geist2025ezsp,
  title={EZ-SP：快速轻量级的超点基三维分割},
  author={Geist, Louis and Landrieu, Loic and Robert, Damien},
  journal={arXiv},
  year={2025},
}

📄 您可以在arXiv上找到我们的论文：

• SPT
• SuperCluster
• EZ-SP

另外，如果您喜欢或只是使用了这个项目，请别忘了给仓库点个⭐，这对我们来说意义重大！

💳 致谢

• 本项目基于Lightning-Hydra模板构建。
• 本工作的主要数据结构依赖于PyTorch Geometric。
• 部分点云操作受到Torch-Points3D框架的启发，尽管目前尚未与官方项目合并。
• 对于KITTI-360数据集，部分代码源自官方KITTI-360项目。
• 一些与超点图相关的操作灵感来自Superpoint Graph。
• 在SPT和SPC中，我们使用了Parallel Cut-Pursuit来计算层次化的超点划分和图聚类。需要注意的是，在EZ-SP中，这一步已被我们基于GPU的算法所取代。

本项目得到了Romain Janvier的大力支持。此次合作得益于3DFin项目。3DFin项目由英国斯旺西大学野火研究中心与西班牙CSIC生物多样性研究所、西班牙奥维耶多大学采矿工程系共同开发。该项目获得了英国NERC项目（NE/T001194/1）——“推进用于野火行为及风险缓解建模的三维燃料测绘”——以及西班牙知识创造项目（PID2021-126790NB-I00）——“应用人工智能处理三维地面点云以提升野火碳排放估算水平”的资助。

此外，本项目还受益于**Louis Geist**的贡献，其工作得到了PEPR IA SHARP项目的资助。

Superpoint Transformer 快速上手指南

Superpoint Transformer (SPT) 及其衍生模型（SuperCluster, EZ-SP）是用于大规模 3D 场景语义分割和全景分割的高效架构。本指南将帮助您快速搭建环境并运行基础示例。

🛠️ 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 18.04+)
• Python: 3.8 或更高版本
• GPU: 支持 CUDA 的 NVIDIA 显卡（建议显存 ≥ 8GB 以处理大型点云）
• 编译器: GCC/G++ (用于编译部分扩展)

前置依赖

本项目基于 PyTorch Lightning 和 Hydra 构建。建议先创建一个干净的虚拟环境：

# 创建虚拟环境
python -m venv spt_env
source spt_env/bin/activate

# 升级 pip
pip install --upgrade pip

📦 安装步骤

1. 安装 PyTorch

请访问 PyTorch 官网 获取适合您 CUDA 版本的安装命令。以下是通用示例（请根据实际情况调整 cuXXX 版本）：

# 示例：安装 PyTorch 2.2+ (请替换为您的实际 CUDA 版本)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

国内加速提示：如果遇到下载速度慢的问题，推荐使用清华大学或阿里云镜像源：

pip install torch torchvision torchaudio --index-url https://pypi.tuna.tsinghua.edu.cn/simple

2. 克隆仓库并安装项目依赖

# 克隆代码库
git clone https://github.com/drprojects/superpoint_transformer.git
cd superpoint_transformer

# 安装项目依赖
pip install -e .

如果 pip install -e . 失败，可以尝试手动安装核心依赖：

pip install pytorch-lightning==2.2.* hydra-core==1.3.* omegaconf

🚀 基本使用

本项目使用 Hydra 进行配置管理，所有实验通过命令行参数启动。以下是最简单的数据预处理和训练示例（以 S3DIS 数据集为例）。

1. 数据预处理

SPT 需要先将原始点云转换为超点（Superpoint）结构。以 S3DIS 数据集为例：

# 运行预处理脚本 (假设数据已放置在 data/s3dis 目录下)
python scripts/preprocess_s3dis.py \
  dataset_path=data/s3dis \
  output_path=data/s3dis_preprocessed \
  mode=train

注意：EZ-SP 版本引入了更快的 GPU 加速分区算法，如果使用 EZ-SP 模式，请确保参考其特定的预处理标志。

2. 开始训练

使用默认配置在单个 GPU 上启动训练。以下命令演示如何训练 SPT 模型：

# 训练 SPT 模型 (S3DIS 6-Fold 示例)
python train.py \
  model=spt \
  dataset=s3dis \
  trainer.accelerator=gpu \
  trainer.devices=1 \
  data.root_dir=data/s3dis_preprocessed

3. 推理与评估

训练完成后，使用保存的检查点进行推理：

python evaluate.py \
  model=spt \
  dataset=s3dis \
  ckpt_path=outputs/train/run_0/checkpoints/epoch=50-step=1000.ckpt \
  data.root_dir=data/s3dis_preprocessed

💡 核心配置说明

• model: 选择模型架构 (spt, supercluster, ez_sp)。
• dataset: 选择数据集 (s3dis, scannet, kitti360, dales)。
• trainer: 配置训练参数（如 GPU 数量、精度 precision=16-mixed 等）。

您可以查看 configs/ 目录下的 YAML 文件来修改网络结构、超参数和数据增强策略。