Point Cloud Transformer (PCT) for ModelNet40 Classification

基于 Jittor 框架的 Point Cloud Transformer (PCT) 实现，用于 ModelNet40 三维点云形状分类任务。本项目支持配置化实验管理、多种数据增强策略、优化器与学习率调度器的灵活切换，以及训练过程的可视化。

Features
Project Structure
Installation
Usage
Experimental Results
Contributing
License

Features

配置驱动：所有超参集中管理于 YAML 配置文件，无需修改代码即可切换实验策略
数据增强策略：支持 rotate_y、jitter、scale、jitter_scale 及其组合，参数可控
优化器切换：支持 SGD、Adam、AdamW，通过配置一键切换
学习率调度：支持 CosineAnnealingLR 和 StepLR
训练可视化：基于 Matplotlib 自动绘制 Loss / Accuracy / LR 曲线
实验归档：每个实验自动归档到独立文件夹（模型、预测结果、配置、训练曲线）
进度显示：基于 tqdm 的实时进度条

Project Structure

.
├── pct.py                  # 主训练与推理脚本
├── configs/
│   ├── default.yaml        # 默认基线配置
│   ├── aug_jitter.yaml     # 数据增强实验配置
│   ├── opt_adam.yaml       # 优化器实验配置
│   ├── sched_step.yaml     # 调度器实验配置
│   ├── exp08_jitter_v2.yaml
│   └── phase1/             # Phase 1: 优化器与学习率搜索（8组）
│   └── phase2/             # Phase 2: 数据增强搜索（6组）
├── utils/
│   └── visualize.py        # 训练曲线可视化工具
├── docs/
│   ├── DESIGN.md           # 实验设计文档
│   └── REPORT.md           # 实验报告模板
├── data/                   # 数据集（已忽略）
│   ├── train_points.npy
│   ├── train_labels.npy
│   └── test_points.npy
└── exp/                    # 实验输出目录（已忽略）

Installation

Requirements

Python >= 3.8
Jittor
NumPy
Matplotlib
PyYAML
tqdm

Setup

# 克隆项目
git clone <your-repo-url>
cd PointCloud

# 安装依赖
pip install jittor numpy matplotlib pyyaml tqdm

# 准备数据
# 将 data.zip 解压到 ./data/ 目录，确保包含：
#   data/train_points.npy
#   data/train_labels.npy
#   data/test_points.npy

Usage

Quick Start

使用默认配置直接训练：

python pct.py

Configuration

所有实验参数通过 YAML 配置文件管理。默认配置位于 configs/default.yaml：

wandb:
  name: "exp001"           # 实验名，决定输出文件夹名

training:
  epochs: 200
  batch_size: 32
  lr: 0.01
  seed: 42

augment:
  strategy: "rotate_y"     # none | rotate_y | jitter | scale | jitter_scale
  params:
    jitter_std: 0.01
    scale_min: 0.9
    scale_max: 1.1

optimizer:
  type: "sgd"              # sgd | adam | adamw

scheduler:
  type: "cosine"           # cosine | step

Running Experiments

单实验运行

python pct.py --config configs/default.yaml
python pct.py --config configs/phase1/exp08.yaml
python pct.py --config configs/phase2/exp01.yaml

批量运行 Phase 1

bash run_phase1.sh

批量运行 Phase 2

bash run_phase2.sh

输出说明

每个实验的结果自动归档到 exp/{实验名}/ 目录下：

pct_model.pkl — 训练好的模型权重
result.json — 测试集预测结果
config.yaml — 该实验的完整配置快照
training_curves.png — Loss / Acc / LR 训练曲线

Experimental Results

本实验分为两个阶段：

Phase 1：优化器与学习率搜索（8组实验）
- 最优配置：AdamW + lr=5e-4 + CosineAnnealingLR
Phase 2：数据增强策略搜索（6组实验）
- 最优配置：无数据增强

详细实验过程与结果填写见 docs/REPORT.md。

最终提交模型：exp/phase2_exp01_no_aug/

Contributing

欢迎提交 Issue 和 Pull Request。如有问题，请在项目仓库中开启讨论。

License

本项目仅供学术交流与课程作业使用。