Point Transformer V3

本仓库是论文 Point Transformer V3: Simpler, Faster, Stronger 的官方项目仓库，主要用于发布日程安排、更新说明文档、分享实验记录（包含模型权重）以及处理相关问题。代码将在 Pointcept v1.5 中更新。
[ 骨干网络 ] [PTv3] - [ arXiv ] [ 参考文献 ] [ 代码 ]

Sonata：自监督预训练 PTv3

🚀 欢迎关注我们最新推出的强大自监督预训练 PTv3——Sonata，其中包含了使用我们预训练 PTv3 的多种视觉演示。

重要更新

• 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 的项目仓库，如果你对我们的工作有任何疑问，欢迎提交 issue。你可以通过填写 表单 订阅我们的更新，并且可以通过编辑表单取消订阅。

目录概览

• 引用说明
• 安装指南
• 数据准备
• 快速开始
• 模型库

Citation

如果您发现 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={Point transformer V2: Grouped Vector Attention and Partition-based Pooling},
    author={Wu, Xiaoyang and Lao, Yixing and Jiang, Li and Liu, Xihui and Zhao, Hengshuang},
    booktitle={NeurIPS},
    year={2022}
}

@misc{pointcept2023,
    title={Pointcept: A Codebase for Point Cloud Perception Research},
    author={Pointcept Contributors},
    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 的最低要求，此时您需要禁用 FlashAttention 以启用 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
# Choose version you want here: https://pytorch.org/get-started/previous-versions/
# We use CUDA 11.8 and PyTorch 2.1.0 for our development of PTv3
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)
# refer https://github.com/traveller59/spconv
pip install spconv-cu118  # choose version match your local cuda version

# Open3D (visualization, optional)
pip install open3d

• Flash Attention

请参考 Flash Attention 仓库的 README 并为 PTv3 安装 Flash Attention。此安装为可选操作，但我们建议为 PTv3 启用 Flash Attention。

数据准备

详情请进一步参考 Pointcept 文档的 Data Preparation 部分。

快速开始

两种运行场景

我们为 PTv3 提供了两种运行场景：Pointcept 驱动和自定义框架驱动。对于前者，您只需将 Pointcept 的代码克隆到本地，并按照 Pointcept 中的 Quick Start 来运行 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}

对于后一种场景，我们提供了一个独立的 PointTransformerV3 实例，该实例不依赖于我们的 Pointcept 框架。要将此代码整合到您的项目中，请克隆项目仓库并将以下文件/文件夹复制到您的项目中：

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。

模型库（Model Zoo）

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的模型结构进行了调整，已发布的模型权重暂时失效。

示例运行脚本如下：

# Scratched ScanNet
sh scripts/train.sh -g 4 -d scannet -c semseg-pt-v3m1-0-base -n semseg-pt-v3m1-0-base
# PPT joint training (ScanNet + Structured3D) and evaluate in ScanNet
sh scripts/train.sh -g 8 -d scannet -c semseg-pt-v3m1-1-ppt-extreme -n semseg-pt-v3m1-1-ppt-extreme

# Scratched ScanNet200
sh scripts/train.sh -g 4 -d scannet200 -c semseg-pt-v3m1-0-base -n semseg-pt-v3m1-0-base
# Fine-tuning from  PPT joint training (ScanNet + Structured3D) with ScanNet200
# TODO

# Scratched S3DIS, S3DIS rely on RPE, also an example for disable flash attention
sh scripts/train.sh -g 4 -d s3dis -c semseg-pt-v3m1-0-rpe -n semseg-pt-v3m1-0-rpe
# PPT joint training (ScanNet + S3DIS + Structured3D) and evaluate in ScanNet
sh scripts/train.sh -g 8 -d s3dis -c semseg-pt-v3m1-1-ppt-extreme -n semseg-pt-v3m1-1-ppt-extreme

# More configs and exp records for PTv3 will be available soon.

2. 室外语义分割

模型	基准测试集	额外数据	GPU数量	验证集mIoU	配置文件	张量板	实验记录
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 Open Dataset训练的模型权重无法发布。

示例运行脚本如下：

# Scratched ScanNet
sh scripts/train.sh -g 4 -d scannet -c semseg-pt-v3m1-0-base -n semseg-pt-v3m1-0-base
# PPT joint training (ScanNet + Structured3D) and evaluate in ScanNet
sh scripts/train.sh -g 8 -d scannet -c semseg-pt-v3m1-1-ppt-extreme -n semseg-pt-v3m1-1-ppt-extreme

# Scratched ScanNet200
sh scripts/train.sh -g 4 -d scannet200 -c semseg-pt-v3m1-0-base -n semseg-pt-v3m1-0-base
# Fine-tuning from  PPT joint training (ScanNet + Structured3D) with ScanNet200
# TODO

# Scratched S3DIS, S3DIS rely on RPE, also an example for disable flash attention
sh scripts/train.sh -g 4 -d s3dis -c semseg-pt-v3m1-0-rpe -n semseg-pt-v3m1-0-rpe
# PPT joint training (ScanNet + S3DIS + Structured3D) and evaluate in 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-fold cross validation
# 1. The default configs are evaluated on Area_5, modify the "data.train.split", "data.val.split", and "data.test.split" to make the config evaluated on Area_1 ~ Area_6 respectively.
# 2. Train and evaluate the model on each split of areas and gather result files located in "exp/s3dis/EXP_NAME/result/Area_x.pth" in one single folder, noted as RECORD_FOLDER.
# 3. Run the following script to get S3DIS 6-fold cross validation performance:
export PYTHONPATH=./
python tools/test_s3dis_6fold.py --record_root ${RECORD_FOLDER}

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

# More configs and exp records for PTv3 will be available soon.