PCT for ModelNet40 Classification

基于 Jittor 框架的 PCT（Point Cloud Transformer）模型，用于 ModelNet40 三维形状分类任务。

模型结构参考论文 PCT: Point Cloud Transformer （Guo et al., Computational Visual Media 2021）。

1. 环境安装

Python 3.8+
建议使用支持 CUDA 的 NVIDIA GPU
安装依赖：

pip install -r requirements.txt

已验证环境：

Python 3.9.23
Jittor 1.3.11.0
CUDA 12.2
NVIDIA GeForce RTX 3080 Ti

可使用以下命令检查环境：

python -c "import jittor as jt; print(jt.__version__)"
python pct.py --help

2. 数据准备

本项目使用计图比赛平台提供的 ModelNet40 .npy 数据。数据集不随代码仓库发布，请从比赛赛题页下载后放入 data/ 目录：

data/
├── train_points.npy    # 训练点云，shape: (N, 2048, 3)
├── train_labels.npy    # 训练标签，shape: (N,)，类别范围 0~39
├── test_points.npy     # 测试点云，shape: (M, 2048, 3)
└── categories.txt      # 40 个类别名称

默认数据根目录为 ./data，可通过 --data_dir 修改。缺少数据文件时，程序会显示缺失文件的绝对路径和修复提示。

ModelNet40 数据集来自 Princeton ModelNet，数据使用应同时遵守数据集条款和比赛规则。

3. 训练

默认训练 42、123、456 三个随机种子：

python pct.py \
  --data_dir ./data \
  --output_dir ./outputs/ensemble \
  --epochs 300 \
  --batch_size 24 \
  --n_points 2048

单种子训练：

python pct.py \
  --data_dir ./data \
  --output_dir ./outputs/seed42 \
  --epochs 300 \
  --batch_size 24 \
  --n_points 2048 \
  --single \
  --seed 42

每次运行会在 --output_dir 保存：

config.json                    # 实际使用的参数
command.txt                    # 运行命令
train.log                      # 训练日志
pct_model_best_seed<seed>.pkl  # 最优验证集权重
training_curves_seed<seed>.png # 训练曲线
result.json                    # 测试集预测

关键超参均可通过命令行修改，完整列表请运行 python pct.py --help。

4. 评测/推理

三模型集成推理（命令中显式指定 checkpoint 路径）：

python pct.py \
  --data_dir ./data \
  --checkpoint_dir ./outputs/ensemble \
  --output_dir ./outputs/eval \
  --batch_size 24 \
  --n_points 2048 \
  --test \
  --use_tta

--checkpoint_dir 中必须包含：

pct_model_best_seed42.pkl
pct_model_best_seed123.pkl
pct_model_best_seed456.pkl

现有权重如果位于项目根目录，可将参数改为 --checkpoint_dir .。关闭 TTA 可使用 --no_tta。推理配置、命令、日志和 result.json 保存在 --output_dir 中。

本仓库不发布模型权重。可按第 3 节的训练命令从零生成权重。

5. 结果说明

指标：Overall Accuracy（OA）
计算：OA = 正确分类样本数 / 总样本数
模型：PCT，channels=256，约 2.8M 参数
训练策略：3-seed ensemble（42/123/456）+ TTA ×20
优化器：AdamW，lr=5e-5，weight_decay=1e-4
学习率：Cosine Annealing + 50 epoch warmup
正则化：Label Smoothing 0.15 + Dropout 0.5

训练随机种子会同时设置到 Python、NumPy 和 Jittor；训练/验证划分由 --split_seed 独立控制。线上结果与本地复现结果可能因 GPU 算子、数据加载和 TTA 存在小幅差异，不保证逐位一致。

项目结构

.
├── pct.py              # 模型、数据、训练和推理入口
├── requirements.txt    # Python 依赖
├── LICENSE             # MIT License
├── .gitignore
├── README.md
├── data/               # 本地数据，不提交
└── outputs/            # 日志、权重和结果，不提交

引用与声明

@inproceedings{guo2021pct,
  title={PCT: Point Cloud Transformer},
  author={Guo, Meng-Hao and Cai, Jun-Xiong and Liu, Zheng-Ning and
          Mu, Tai-Jiang and Martin, Ralph R and Hu, Shi-Min},
  booktitle={Computational Visual Media},
  year={2021}
}

本项目代码以 MIT License 发布。PCT 模型结构来源于上述论文， ModelNet40 数据不包含在本仓库中。如基于赛事模板或其他第三方代码继续修改，请同时保留对应的来源和许可证声明。