基于超点图的大规模点云语义分割

⚠️ 此仓库已不再维护！请查看我们全新的 SuperPoint Transformer，它在各方面都更优秀！⚠️

这是以下两篇论文的官方 PyTorch 实现：

基于超点图的大规模点云语义分割

由 Loic Landrieu 和 Martin Simonovski 撰写（CVPR2018），以及

基于图结构深度度量学习的点云超分割。

由 Loic Landrieu 和 Mohamed Boussaha 撰写（CVPR2019），

代码结构

• ./partition/* - 分割代码（使用手工特征进行几何分割和超点图构建）
• ./supervized_partition/* - 有监督分割代码（使用学习到的特征进行分割）
• ./learning/* - 学习代码（超点嵌入和上下文语义分割）。

若要切换到仅包含 SPG 的稳定分支，请切换至 release。

免责声明

我们的分割方法本质上是随机的。因此，即使我们提供了训练好的权重，您得到的结果仍可能与论文中展示的结果略有不同。

需求

0. 下载当前版本的仓库。建议使用 --recurse-submodules 选项，以确保 /partition 中使用的 cut pursuit 模块也被一同下载。如果您未使用以下命令，请参阅第 4 点：

git clone --recurse-submodules https://github.com/loicland/superpoint_graph

1. 安装 PyTorch 和 torchnet。

pip install git+https://github.com/pytorch/tnt.git@master

2. 安装其他 Python 包：

pip install future igraph tqdm transforms3d pynvrtc fastrlock cupy h5py sklearn plyfile scipy pandas

3. 在 Conda 中安装 Boost（1.63.0 或更高版本）和 Eigen3：

conda install -c anaconda boost; conda install -c omnia eigen3; conda install eigen; conda install -c r libiconv

4. 确保 cut pursuit 已被下载。否则，请克隆 此仓库 或将其作为子模块添加到 /partition：

cd partition
git submodule init
git submodule update --remote cut-pursuit

5. 编译 libply_c 和 libcp 库：

CONDAENV=YOUR_CONDA_ENVIRONMENT_LOCATION
cd partition/ply_c
cmake . -DPYTHON_LIBRARY=$CONDAENV/lib/libpython3.6m.so -DPYTHON_INCLUDE_DIR=$CONDAENV/include/python3.6m -DBOOST_INCLUDEDIR=$CONDAENV/include -DEIGEN3_INCLUDE_DIR=$CONDAENV/include/eigen3
make
cd ..
cd cut-pursuit
mkdir build
cd build
cmake .. -DPYTHON_LIBRARY=$CONDAENV/lib/libpython3.6m.so -DPYTHON_INCLUDE_DIR=$CONDAENV/include/python3.6m -DBOOST_INCLUDEDIR=$CONDAENV/include -DEIGEN3_INCLUDE_DIR=$CONDAENV/include/eigen3
make

6.（可选）安装 Pytorch Geometric

该代码已在 Ubuntu 14 和 16 上，使用 Python 3.5 至 3.8 以及 PyTorch 0.2 至 1.3 进行测试。

故障排除

常见错误及其解决方法：

• $CONDAENV 定义不正确：请定义它，或将 $CONDAENV 替换为您 Conda 环境的绝对路径（可通过 locate anaconda 查找）。
• Anaconda 使用的 Python 版本不是 3.6m：请在命令中相应调整。可通过 locate anaconda3/lib/libpython 查看 Conda 使用的 Python 版本。
• 您正在使用 Boost 1.62 或更早版本：请升级。
• cut pursuit 未下载：请手动将其克隆到 partition 文件夹中，或按照需求第 4 点所述将其添加为子模块。
• make 报错：“'numpy/ndarrayobject.h' 文件未找到”：通过 sudo ln -s $CONDAENV/lib/python3.7/site-packages/numpy/core/include/numpy $CONDAENV/include/numpy 设置指向 Python site-package 的符号链接。

运行代码

要运行我们的代码或从头开始在不同数据集上重新训练，请参阅相应的 README 文件。目前支持的数据集如下：

数据集	手工特征分割	学习特征分割
S3DIS	是	是
Semantic3D	是	即将支持
vKITTI3D	否	是
ScanNet	即将支持	即将支持

若要使用 PyTorch Geometric 的图卷积代替我们自己的实现，请在 ./learning/main.py 中使用 --use_pyg 1 选项。他们的代码更加稳定且速度相当。否则，请使用 --use_pyg 0。

评估

要定量评估训练好的模型，请使用（仅限 S3DIS 和 vKITTI3D）：

python learning/evaluate.py --dataset s3dis --odir results/s3dis/best --cvfold 123456

要可视化结果及所有中间步骤，请使用 partition 中的可视化函数（适用于 S3DIS、vKITTI3D 和 Semantic3D）。例如：

python partition/visualize.py --dataset s3dis --ROOT_PATH $S3DIR_DIR --res_file results/s3dis/pretrained/cv1/predictions_test --file_path Area_1/conferenceRoom_1 --output_type igfpres

output_type 的定义如下：

• 'i' = 输入 RGB 点云
• 'g' = 真实标签（如有），采用预定义的类别颜色映射
• 'f' = 几何特征，颜色编码：红色表示线性度，绿色表示平面度，蓝色表示垂直度
• 'p' = 分割结果，每个超点随机分配一种颜色
• 'r' = 结果点云，采用预定义的类别颜色映射
• 'e' = 错误点云，正确预测为绿色，错误预测为红色
• 's' = 超点的超边结构（可在 MeshLab 中开启线框模式查看）

如果您希望预测文件基于原始未修剪的数据（较长），请添加 --upsample 1 选项。

其他数据集

您可以在自己的数据集上应用 SPG，只需进行少量修改：

• 在 /partition/partition.py 中将引用调整为 custom_dataset
• 您需要在 /partition/provider.py 中创建函数 read_custom_format，该函数应输出 xyz 和 rgb 值，以及语义标签（对于 ply 和 las 文件，此功能已实现）
• 根据您的架构和设计选择，调整模板函数 /learning/custom_dataset.py
• 在 /learning/main.py 中将引用调整为 custom_dataset
• 将您的数据集颜色映射添加到 /partition/provider.py 中的 get_color_from_label
• 调整 learning/spg.py 的第 212 行，以反映缺失或额外的点特征
• 将 --model_config 更改为 gru_10,f_K，其中 K 为数据集的类别数；或者使用 gru_10_0,f_K 来采用矩阵边滤波器而非向量（仅当您的数据集非常大且包含许多不同的点云时才使用矩阵，例如 S3DIS）。

不含 RGB 的数据集

如果您的数据不包含 RGB 值，也可以轻松使用 SPG。您需要按照 partition/partition.ply 中关于修剪的说明进行操作。 此外，您还需要修改 /learning/custom_dataset.py 文件，使其不再引用 RGB 值。 切勿使用基于包含 RGB 值的数据预训练的模型。相反，请从头开始重新训练模型，并使用 --pc_attribs xyzelpsv 选项来从形状嵌入输入中移除 RGB。

引用

如果您使用语义分割模块（代码位于 /learning 目录下），请引用以下文献：
Large-scale Point Cloud Semantic Segmentation with Superpoint Graphs, Loic Landrieu and Martin Simonovski, CVPR, 2018.

如果您使用学习型分割模块（代码位于 /supervized_partition 目录下），请引用以下文献：
Point Cloud Oversegmentation with Graph-Structured Deep Metric Learning, Loic Landrieu and Mohamed Boussaha CVPR, 2019.

若需专门提及手工制作的分割步骤（代码位于 /partition 目录下），请参考：
Weakly Supervised Segmentation-Aided Classification of Urban Scenes from 3D LiDAR Point Clouds, Stéphane Guinard and Loic Landrieu. ISPRS Workshop, 2017.

若需专门提及 L0-cut 追踪算法（代码位于 github.com/loicland/cut-pursuit），请参考：
Cut Pursuit: Fast Algorithms to Learn Piecewise Constant Functions on General Weighted Graphs, Loic Landrieu and Guillaume Obozinski, SIAM Journal on Imaging Sciences, 2017。

有关 PyTorch Geometric 的实现，请参阅其 GitHub 仓库 中的 BibTeX 条目。

Superpoint Graph 快速上手指南

⚠️ 重要提示：本仓库已停止维护。作者推荐使用全新的 SuperPoint Transformer，其性能更优且功能更全面。本文档仅适用于需要复现旧版论文结果或特定研究需求的用户。

Superpoint Graph (SPG) 是用于大规模点云语义分割的官方 PyTorch 实现，基于 CVPR 2018 和 2019 的两篇论文。它通过构建超点图（Superpoint Graph）来实现高效的点云过分割和上下文分割。

环境准备

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

• 操作系统: Linux (测试于 Ubuntu 14/16)
• Python 版本: 3.5 - 3.8
• PyTorch 版本: 0.2 - 1.3
• 核心依赖:
  • Boost (>= 1.63.0)
  • Eigen3
  • CUDA (用于编译部分库)

安装步骤

1. 克隆代码库

建议使用 --recurse-submodules 参数一次性下载主代码及所需的 cut-pursuit 子模块。

git clone --recurse-submodules https://github.com/loicland/superpoint_graph
cd superpoint_graph

2. 安装 Python 依赖

安装 PyTorch、torchnet 及其他必要的 Python 包。国内用户可使用清华源或阿里源加速安装。

# 安装 torchnet
pip install git+https://github.com/pytorch/tnt.git@master

# 安装其他依赖 (建议配置国内 pip 源)
pip install future igraph tqdm transforms3d pynvrtc fastrlock cupy h5py sklearn plyfile scipy pandas

3. 安装系统级依赖 (Conda)

使用 Conda 安装 Boost 和 Eigen3 库是最简便的方式。

conda install -c anaconda boost
conda install -c omnia eigen3
conda install eigen
conda install -c r libiconv

4. 确认子模块

如果第 1 步未成功下载 cut-pursuit，请手动执行以下命令：

cd partition
git submodule init
git submodule update --remote cut-pursuit
cd ..

5. 编译 C++ 扩展库

需要编译 libply_c 和 libcp 库。注意：请将命令中的 YOUR_CONDA_ENVIRONMENT_LOCATION 替换为您实际的 Conda 环境绝对路径（可通过 conda info --envs 查看）。同时，请根据实际安装的 Python 版本（如 python3.7m）调整命令中的版本号。

# 设置环境变量 (请修改为实际路径)
export CONDAENV=/path/to/your/conda/env

# 编译 libply_c
cd partition/ply_c
cmake . -DPYTHON_LIBRARY=$CONDAENV/lib/libpython3.7m.so -DPYTHON_INCLUDE_DIR=$CONDAENV/include/python3.7m -DBOOST_INCLUDEDIR=$CONDAENV/include -DEIGEN3_INCLUDE_DIR=$CONDAENV/include/eigen3
make
cd ..

# 编译 libcp (cut-pursuit)
cd cut-pursuit
mkdir build
cd build
cmake .. -DPYTHON_LIBRARY=$CONDAENV/lib/libpython3.7m.so -DPYTHON_INCLUDE_DIR=$CONDAENV/include/python3.7m -DBOOST_INCLUDEDIR=$CONDAENV/include -DEIGEN3_INCLUDE_DIR=$CONDAENV/include/eigen3
make
cd ../..

(可选) 安装 PyTorch Geometric: 如果需要更稳定的图卷积操作，可安装 PyG 并在运行时启用：

pip install torch-geometric

基本使用

目前支持的数据集包括 S3DIS, Semantic3D, vKITTI3D 等。以下以 S3DIS 数据集为例展示基本用法。

1. 模型评估

使用预训练模型对 S3DIS 数据集进行定量评估（假设已下载预训练权重至 results/s3dis/best）：

python learning/evaluate.py --dataset s3dis --odir results/s3dis/best --cvfold 123456

2. 结果可视化

可视化输入点云、真值、分割结果及误差分析。以下命令展示 S3DIS 中 Area_1/conferenceRoom_1 的预测结果：

# 请替换 $S3DIR_DIR 为您的数据集根目录路径
python partition/visualize.py --dataset s3dis --ROOT_PATH $S3DIR_DIR --res_file results/s3dis/pretrained/cv1/predictions_test --file_path Area_1/conferenceRoom_1 --output_type igfpres

输出类型说明 (--output_type):

• i: 输入 RGB 点云
• g: 地面真值 (Ground Truth)
• f: 几何特征 (红=线性度，绿=平面度，蓝=垂直度)
• p: 超点分割结果 (每个超点随机颜色)
• r: 最终语义分割结果
• e: 误差云 (绿色=正确，红色=错误)
• s: 超边结构 (需在 Meshlab 中开启线框模式查看)

若需将预测结果上采样至原始未修剪的点云数据，请添加 --upsample 1 参数。

3. 使用自定义数据集

若需处理自有数据，需进行以下最小化修改：

1. 在 /partition/partition.py 和 /learning/main.py 中将数据集引用改为 custom_dataset。
2. 在 /partition/provider.py 中实现 read_custom_format 函数以读取 xyz, rgb 及标签。
3. 修改 /learning/custom_dataset.py 以适配您的数据结构。
4. 在 /partition/provider.py 的 get_color_from_label 中添加类别颜色映射。
5. 调整 learning/spg.py 第 212 行以匹配点特征维度。
6. 运行训练时，通过 --model_config 指定类别数，例如 gru_10,f_K (K 为类别数)。

注意：如果您的数据不包含 RGB 信息，请勿使用预训练模型。必须从头训练，并使用 --pc_attribs xyzelpsv 参数移除 RGB 输入。