ModelNet40 点云分类（Jittor / PCT）

计图挑战赛（赛道二热身赛）参赛代码：基于 Jittor 框架的 PCT（Point Cloud Transformer）模型，完成 ModelNet40 数据集 40 类三维点云分类。

默认配置（configs/pct.yaml，seed=42）训练 200 epochs，在 10% 留出验证集上 **Best Val Acc = 92.58%**，远超线上 0.80 的通过线。

目录结构

.
├── configs/            # 训练/推理配置（yaml）
│   └── pct.yaml
├── src/                # 核心代码
│   ├── dataset.py      # ModelNet40 数据集加载与增强
│   ├── model.py        # PCT 模型定义
│   ├── engine.py       # 训练/评测/推理核心循环
│   └── utils.py        # 种子、日志、配置、调度器、损失
├── scripts/            # 运行入口
│   ├── train.py        # 训练（训练完成后自动生成提交结果）
│   └── predict.py      # 推理（加载已有权重生成提交结果）
├── data/               # 数据目录（仅含说明，数据文件不提交）
├── outputs/            # 日志/权重/结果（不提交）
└── docs/               # 赛题说明与开源规范

1. 环境安装

Python ≥ 3.7（实测环境：WSL2 Ubuntu + conda + Python 3.7.16 + NVIDIA GPU）
依赖安装：

conda create -n jittor python=3.7 -y
conda activate jittor
pip install -r requirements.txt

GPU 训练需要 CUDA 环境，Jittor 可自动安装 CUDA 依赖（可选）：

python -m jittor_utils.install_cuda

验证安装：python -c "import jittor as jt; print(jt.has_cuda)"。更多安装方式见 Jittor 官方文档。

2. 数据准备

从比赛页面下载数据集压缩包，解压到仓库根目录的 data/ 文件夹：

data/
├── train_points.npy   # (9843, 2048, 3) 训练集点云
├── train_labels.npy   # (9843,)         训练集标签（0-39）
├── test_points.npy    # (2468, 2048, 3) 测试集点云（无标签）
└── categories.txt     # 40 个类别名称

若解压产生 data/data/ 嵌套目录，代码会自动识别。数据根目录通过 configs/pct.yaml 的 data_dir 字段或命令行 --data_dir 配置（命令行优先级更高）。详见 data/README.md。

3. 训练

python scripts/train.py --config configs/pct.yaml

单张消费级 GPU 约 2 小时（200 epochs，每 epoch 约 35 s；首个 epoch 因 Jittor 即时编译较慢）。命令行参数可覆盖配置文件，例如快速试跑：

python scripts/train.py --config configs/pct.yaml --epochs 1 --n_votes 1 --exp_name debug

每次运行的产物保存在 outputs/<exp_name>/ 下：

文件	说明
`config.yaml` / `command.txt`	本次运行实际使用的配置与命令（复现用）
`train.log`	训练日志
`pct_best.pkl` / `pct_model.pkl`	验证集最优权重 / 最后一个 epoch 权重
`result.json` / `result.zip`	测试集预测结果（训练结束自动生成，`result.zip` 可直接提交）

4. 评测 / 推理

使用训练好的权重单独生成提交结果：

python scripts/predict.py --config configs/pct.yaml --ckpt outputs/pct/pct_best.pkl

结果（result.json / result.zip）与推理日志（eval.log）默认输出到 ckpt 同目录，可用 --out_dir 修改。result.json 为 {"样本编号": 预测类别} 格式的字典（编号为字符串，类别为 0-39 整数），result.zip 可直接在比赛页面提交。

5. 结果说明

指标：分类准确率 Accuracy = 预测正确的样本数 / 测试集样本总数（2468）。线上评测程序将提交的 result.json 与测试集真实标签对比计算，Accuracy ≥ 0.80 即通过。
本仓库结果：默认配置训练 200 epochs，10% 留出验证集 Best Val Acc = 92.58%（epoch 112），推理使用该最优权重。
与线上成绩的差异说明：本地验证集是从训练集划出的 984 个样本，与线上测试集分布不完全相同，线上成绩通常有 1~2 个百分点的波动；推理采用 10 次随机采样投票（TTA）以降低波动。此外 GPU 上部分算子的归约顺序具有非确定性，即使固定随机种子，完全复现也可能存在 ≤0.5 个百分点的合理差异。

6. 方法说明（相对官方 baseline 的主要改动）

数据增强：随机各向异性缩放（2/3 ~ 3/2）+ 随机平移（±0.2）；不做整周随机旋转（ModelNet40 姿态对齐，旋转反而损害精度）
损失函数：label smoothing = 0.2 的交叉熵
优化策略：SGD（momentum 0.9，weight decay 1e-4）+ 余弦退火（0.01 → 1e-5）
模型选择：划出 10% 验证集，每个 epoch 评测并保存最优权重用于最终推理
推理增强：10 次随机点采样投票（TTA），对 softmax 概率取平均后再 argmax

7. 可复现性

随机种子通过 --seed（默认 42）统一设置 numpy 与 jittor
每次运行自动将实际配置（config.yaml）、运行命令（command.txt）与日志（train.log / eval.log）落盘到输出目录
数据或权重文件缺失时脚本会报出明确的错误信息与修复方法

8. 第三方代码与数据声明

模型与训练代码基于比赛官方提供的 PCT baseline 示例代码修改
PCT 模型出自：Guo et al., PCT: Point Cloud Transformer, Computational Visual Media, 2021（官方 Jittor 实现：https://github.com/MenghaoGuo/PCT）
数据集：ModelNet40（比赛官方预处理的点云版本，从比赛页面下载；本仓库不包含数据文件）
未使用任何预训练权重

License

MIT