ModelNet40 Point Cloud Classification with PCT and Jittor

本仓库为计图（Jittor）比赛热身赛 ModelNet40 点云分类任务的开源代码。代码基于 PCT（Point Cloud Transformer）baseline，实现了训练集/验证集划分、训练与验证指标记录、最佳模型保存、曲线绘制和测试集 result.json 生成。

1. 项目结构

.
├── README.md
├── LICENSE
├── NOTICE
├── requirements.txt
├── .gitignore
├── configs/
│   └── pct_val_sgd_1024.json
├── data/
│   └── README.md
├── scripts/
│   ├── train.sh
│   ├── infer.sh
│   └── make_submission.sh
├── src/
│   ├── pct_val.py
│   └── infer.py
└── outputs/
    └── .gitkeep

data/ 仅保留数据说明，不提交 .npy 数据文件；outputs/ 用于保存日志、权重、曲线和结果文件，默认不提交。

2. 环境安装

推荐环境：

Python 3.8
CUDA 11.8（可根据服务器环境调整）
Jittor 1.3.11 或更高版本

创建环境示例：

conda create -n jittor_pcd python=3.8 -y
conda activate jittor_pcd
pip install -r requirements.txt

测试 Jittor：

python - <<'PY'
import jittor as jt
print(jt.__version__)
PY

3. 数据准备

将比赛提供的 ModelNet40 预处理点云数据放到 data/ 目录下：

data/
├── train_points.npy   # shape: (9843, 2048, 3)
├── train_labels.npy   # shape: (9843,)
├── test_points.npy    # shape: (2468, 2048, 3)
└── categories.txt     # 40 类类别名称

数据文件由比赛提供，本仓库不包含原始数据。

4. 训练

本次最终采用的配置为：

模型：PCT
优化器：SGD
初始学习率：0.01
学习率策略：CosineAnnealingLR
点数量：1024
Batch size：32
Epochs：200
验证集比例：0.1
随机种子：42

运行训练：

bash scripts/train.sh

或直接运行：

OMP_NUM_THREADS=8 python -u src/pct_val.py \
  --data_dir ./data \
  --n_points 1024 \
  --batch_size 32 \
  --epochs 200 \
  --lr 0.01 \
  --seed 42 \
  --val_ratio 0.1 \
  --best_model_path outputs/best_pct_model.pkl \
  --last_model_path outputs/last_pct_model.pkl \
  --result_path outputs/result.json \
  --history_path outputs/history.csv \
  --loss_curve_path outputs/loss_curve.png \
  --acc_curve_path outputs/acc_curve.png

训练完成后会生成：

outputs/best_pct_model.pkl
outputs/last_pct_model.pkl
outputs/result.json
outputs/history.csv
outputs/loss_curve.png
outputs/acc_curve.png

5. 推理

若已经训练得到 outputs/best_pct_model.pkl，可以单独生成测试集预测结果：

bash scripts/infer.sh

或直接运行：

python -u src/infer.py \
  --data_dir ./data \
  --ckpt outputs/best_pct_model.pkl \
  --n_points 1024 \
  --batch_size 32 \
  --seed 42 \
  --result_path outputs/result.json

6. 生成提交文件

bash scripts/make_submission.sh

生成的提交文件为：

result.zip
└── result.json

result.json 格式为：

{
  "0": 4,
  "1": 35,
  "2": 10
}

其中 key 为测试样本编号字符串，value 为预测类别编号，范围为 0-39。

7. 结果说明

验证集划分方式为按类别分层划分，验证集比例为 0.1。验证指标为分类准确率 Accuracy：

Accuracy = 正确预测样本数 / 总样本数

本地验证结果：

Best epoch: 187
Best val acc: 86.59%

线上成绩与本地验证集准确率可能存在差异，原因包括测试集分布差异、随机采样点差异以及验证集划分方式不同。

8. 可复现说明

代码中通过以下方式固定随机性：

np.random.seed(args.seed)
jt.set_global_seed(args.seed)

训练参数全部通过命令行传入，并在训练日志中打印。建议保留 outputs/train.log、outputs/history.csv、outputs/loss_curve.png 和 outputs/acc_curve.png 作为复现实验记录。

9. 第三方引用与声明

PCT 模型结构和基础训练流程参考比赛提供的示例代码。本仓库在示例代码基础上补充了验证集划分、数据增强、最佳模型保存、训练曲线绘制、独立推理脚本和提交打包脚本。

数据集由比赛提供，本仓库不包含数据文件、模型权重和训练产物。