点云变换器V3

这个仓库是论文**《点云变换器V3：更简单、更快速、更强大》**的官方项目仓库，主要用于发布日程安排、更新说明、分享实验记录（包含模型权重）和处理问题。代码将在_Pointcept v1.5_中更新。
[ 骨干网络 ] [PTv3] - [ arXiv ] [ 引用 ] [ 代码 ]

亮点

2024年4月5日：PTv3被CVPR'24选为90个口头报告之一（3.3%的接受论文，0.78%的投稿）！
2024年2月28日：PTv3被CVPR'24接受 🎉🎉🎉。
2023年12月31日：我们发布了PTv3的模型代码，现已提供从头训练的ScanNet和ScanNet200实验记录。更多内容将很快可用。
2023年12月19日：我们发布了PTv3的项目仓库，如果您对我们的工作有任何问题，请随时提出问题。通过填写表单订阅我们的更新，可以通过编辑表单取消订阅。

日程安排

为了尽快提供我们优化过的代码和复现的实验，这次我们将在验证后立即发布已完成的内容，而不是等所有工作完成后一起发布。我们列出了以下任务列表：

引用

如果您发现_PTv3_对您的研究有用，请引用我们的工作以表示感谢。(੭ˊ꒳ˋ)੭✧

@inproceedings{wu2024ptv3,
    title={Point Transformer V3: Simpler, Faster, Stronger},
    author={Wu, Xiaoyang and Jiang, Li and Wang, Peng-Shuai and Liu, Zhijian and Liu, Xihui and Qiao, Yu and Ouyang, Wanli and He, Tong and Zhao, Hengshuang},
    booktitle={CVPR},
    year={2024}
}

@inproceedings{wu2024ppt,
    title={Towards Large-scale 3D Representation Learning with Multi-dataset Point Prompt Training},
    author={Wu, Xiaoyang and Tian, Zhuotao and Wen, Xin and Peng, Bohao and Liu, Xihui and Yu, Kaicheng and Zhao, Hengshuang},
    booktitle={CVPR},
    year={2024}
}
@inproceedings{wu2022ptv2,
    title={点变换器V2:分组向量注意力和基于分区的池化},
    author={Wu, Xiaoyang and Lao, Yixing and Jiang, Li and Liu, Xihui and Zhao, Hengshuang},
    booktitle={NeurIPS},
    year={2022}
}

@misc{pointcept2023,
    title={Pointcept:一个用于点云感知研究的代码库},
    author={Pointcept贡献者},
    howpublished={\url{https://github.com/Pointcept/Pointcept}},
    year={2023}
}

安装

要求

PTv3依赖于FlashAttention,而FlashAttention依赖于以下要求,请确保您的本地Pointcept环境满足这些要求:

(推荐)

Ubuntu: 20.04及以上
CUDA: 11.6及以上
PyTorch: 1.12.0及以上

如果您无法将本地环境升级以满足上述推荐要求,以下是运行带Pointcept的PTv3的最低要求,您需要禁用Flash Attention以启用PTv3:

(最低)

Ubuntu: 18.04及以上
CUDA: 11.3及以上
PyTorch: 1.10.0及以上

环境

基础环境

conda create -n pointcept python=3.8 -y
conda activate pointcept
conda install ninja -y
# 在此选择您想要的版本:https://pytorch.org/get-started/previous-versions/
# 我们在开发PTv3时使用CUDA 11.8和PyTorch 2.1.0
conda install pytorch==2.1.0 torchvision==0.16.0 torchaudio==2.1.0 pytorch-cuda=11.8 -c pytorch -c nvidia
conda install h5py pyyaml -c anaconda -y
conda install sharedarray tensorboard tensorboardx yapf addict einops scipy plyfile termcolor timm -c conda-forge -y
conda install pytorch-cluster pytorch-scatter pytorch-sparse -c pyg -y
pip install torch-geometric

cd libs/pointops
python setup.py install
cd ../..

# spconv (SparseUNet)
# 参考 https://github.com/traveller59/spconv
pip install spconv-cu118  # 选择与您本地cuda版本匹配的版本

# Open3D (可视化,可选)
pip install open3d

Flash Attention

按照Flash Attention仓库中的README安装PTv3的Flash Attention。这个安装是可选的,但我们建议为PTv3启用Flash Attention。

数据准备

请进一步参考Pointcept readme的数据准备部分。

快速开始

两种运行场景

我们为PTv3提供了两种运行场景,Pointcept驱动和自定义框架驱动。对于前者,您只需将Pointcept的代码克隆到本地,然后按照Pointcept中的快速开始运行PTv3:

git clone https://github.com/Pointcept/Pointcept.git
sh scripts/train.sh -p ${INTERPRETER_PATH} -g ${NUM_GPU} -d ${DATASET_NAME} -c ${CONFIG_NAME} -n ${EXP_NAME}

对于后一种场景,我们提供了一个与我们的Pointcept框架分离的PTv3独立实例。要将此代码整合到您的项目中,请克隆项目仓库并将以下文件/文件夹复制到您的项目中:

git clone https://github.com/Pointcept/PointTransformerV3.git
cp model.py ${PATH_TO_YOUR_PROJECT}
cp -r serialization ${PATH_TO_YOUR_PROJECT}

调整我们的模型文件中定义的输入字典,模型将返回给定批次点云的编码特征。

Flash Attention

完整的PTv3依赖于Flash Attention,而Flash Attention依赖于CUDA 11.6及以上,请确保您的本地Pointcept环境满足这些要求。

如果您无法将本地环境升级以满足要求(CUDA >= 11.6),那么您可以通过将模型参数enable_flash设置为false并将enc_patch_size和dec_patch_size降低到一定水平(例如128)来禁用FlashAttention。

FlashAttention强制禁用RPE并强制将精度降低到fp16。如果您需要这些功能,请禁用enable_flash并调整enable_rpe、upcast_attention和upcast_softmax。

模型库

1. 室内语义分割

模型	基准测试	额外数据	GPU数量	验证mIoU	配置	Tensorboard	实验记录
PTv3	ScanNet	✗	4	77.6%	链接	链接	链接
PTv3 + PPT	ScanNet	✓	8	78.5%	链接	链接	链接
PTv3	ScanNet200	✗	4	35.3%	链接	链接	链接
PTv3 + PPT	ScanNet200	✓ (f.t.)	4
PTv3	S3DIS (Area5)	✗	4	73.6%	链接	链接	链接
PTv3 + PPT	S3DIS (Area5)	✓	8	75.4%	链接	链接	链接
*_由于PTv3的模型结构进行了调整，已发布的模型权重暂时无效。**_

以下是示例运行脚本:

# 从头训练ScanNet
sh scripts/train.sh -g 4 -d scannet -c semseg-pt-v3m1-0-base -n semseg-pt-v3m1-0-base
# PPT联合训练(ScanNet + Structured3D)并在ScanNet上评估
sh scripts/train.sh -g 8 -d scannet -c semseg-pt-v3m1-1-ppt-extreme -n semseg-pt-v3m1-1-ppt-extreme

# 从头训练ScanNet200
sh scripts/train.sh -g 4 -d scannet200 -c semseg-pt-v3m1-0-base -n semseg-pt-v3m1-0-base
# 从PPT联合训练(ScanNet + Structured3D)模型微调ScanNet200
# 待完成

# 从头训练S3DIS，S3DIS依赖RPE，同时也是禁用flash attention的示例
sh scripts/train.sh -g 4 -d s3dis -c semseg-pt-v3m1-0-rpe -n semseg-pt-v3m1-0-rpe
# PPT联合训练(ScanNet + S3DIS + Structured3D)并在ScanNet上评估
sh scripts/train.sh -g 8 -d s3dis -c semseg-pt-v3m1-1-ppt-extreme -n semseg-pt-v3m1-1-ppt-extreme

# 更多PTv3的配置和实验记录将很快推出。

2.室外语义分割

模型	基准	额外数据	GPU数量	验证集mIoU	配置	Tensorboard	实验记录
PTv3	nuScenes	✗	4	80.3	链接	链接	链接
PTv3 + PPT	nuScenes	✓	8
PTv3	SemanticKITTI	✗	4
PTv3 + PPT	SemanticKITTI	✓	8
PTv3	Waymo	✗	4	71.2	链接	链接	链接 (仅日志)
PTv3 + PPT	Waymo	✓	8

_*由于PTv3的模型结构进行了调整，已发布的模型权重暂时无效。_ _*由于Waymo开放数据集的规定，使用该数据集训练的模型权重无法公开发布。_

以下是示例运行脚本:

# 从头训练ScanNet
sh scripts/train.sh -g 4 -d scannet -c semseg-pt-v3m1-0-base -n semseg-pt-v3m1-0-base
# PPT联合训练(ScanNet + Structured3D)并在ScanNet上评估
sh scripts/train.sh -g 8 -d scannet -c semseg-pt-v3m1-1-ppt-extreme -n semseg-pt-v3m1-1-ppt-extreme

# 从头训练ScanNet200
sh scripts/train.sh -g 4 -d scannet200 -c semseg-pt-v3m1-0-base -n semseg-pt-v3m1-0-base
# 从PPT联合训练(ScanNet + Structured3D)模型微调ScanNet200
# 待完成

# 从头训练S3DIS，S3DIS依赖RPE，同时也是禁用flash attention的示例
sh scripts/train.sh -g 4 -d s3dis -c semseg-pt-v3m1-0-rpe -n semseg-pt-v3m1-0-rpe
# PPT联合训练(ScanNet + S3DIS + Structured3D)并在ScanNet上评估
sh scripts/train.sh -g 8 -d s3dis -c semseg-pt-v3m1-1-ppt-extreme -n semseg-pt-v3m1-1-ppt-extreme
# S3DIS 6折交叉验证
# 1. 默认配置在Area_5上评估，修改"data.train.split"、"data.val.split"和"data.test.split"，使配置分别在Area_1 ~ Area_6上评估。
# 2. 在每个区域分割上训练和评估模型，并将位于"exp/s3dis/EXP_NAME/result/Area_x.pth"的结果文件收集到一个文件夹中，记为RECORD_FOLDER。
# 3. 运行以下脚本获取S3DIS 6折交叉验证性能:
export PYTHONPATH=./
python tools/test_s3dis_6fold.py --record_root ${RECORD_FOLDER}

# 从头训练nuScenes
sh scripts/train.sh -g 4 -d nuscenes -c semseg-pt-v3m1-0-base -n semseg-pt-v3m1-0-base
# 从头训练Waymo
sh scripts/train.sh -g 4 -d waymo -c semseg-pt-v3m1-0-base -n semseg-pt-v3m1-0-base

# 更多PTv3的配置和实验记录将很快推出。