# 项目结构说明

## 📁 目录结构

```
digit_cracker/
├── README.md                              # 完整项目文档
├── QUICKSTART.md                          # 快速开始指南
├── FINAL_REPORT.md                        # 项目完成报告
├── PROJECT_STRUCTURE.md                   # 本文件
├── run.sh                                 # 交互式运行脚本
├── .gitignore                             # Git忽略文件配置
│
├── scripts/                               # Python脚本目录
│   ├── prepare_yolo_dataset.py            # [1] COCO→YOLO数据集转换
│   ├── train_yolo.py                      # [2] YOLO模型训练
│   ├── predict_digits.py                  # [3] 基础数字识别
│   ├── predict_digits_improved.py         # [4] 改进版数字识别 ⭐推荐
│   ├── preprocess_images.py               # [5] 图片预处理工具
│   ├── train_with_preprocessing.py        # [6] 预处理+训练流程
│   ├── compare_results.py                 # [7] 结果对比工具
│   └── run_all.py                         # [8] 完整流程自动化
│
├── digit-validation/                      # 原始训练数据（COCO格式）
│   ├── coco.json                          # COCO标注文件
│   └── images/                            # 训练图片（49张）
│
├── valid/                                 # 待识别图片（15张）
│   ├── YZM.jpeg
│   ├── YZM-2.jpeg
│   └── ...
│
├── yolo_dataset/                          # YOLO格式数据集
│   ├── dataset.yaml                       # 数据集配置文件
│   ├── images/                            # 图片（训练集+验证集）
│   │   ├── train/                         # 训练集图片（39张）
│   │   └── val/                           # 验证集图片（10张）
│   └── labels/                            # YOLO格式标注
│       ├── train/                         # 训练集标注（.txt）
│       └── val/                           # 验证集标注（.txt）
│
├── runs/                                  # 训练输出目录
│   └── digit_yolo/                        # YOLO训练实验
│       ├── exp1/                          # 基础模型（100轮，无预处理）
│       │   ├── weights/
│       │   │   ├── best.pt                # 最佳权重
│       │   │   └── last.pt                # 最后权重
│       │   ├── results.csv                # 训练指标
│       │   └── args.yaml                  # 训练参数
│       │
│       └── exp_preprocessed_color_150/    # 优化模型（150轮，CLAHE预处理）⭐最佳
│           ├── weights/
│           │   ├── best.pt                # 最佳权重（5.9MB）⭐⭐⭐
│           │   └── last.pt                # 最后权重（5.9MB）
│           ├── results.csv                # 训练指标
│           └── args.yaml                  # 训练参数
│
├── results/                               # 识别结果目录
│   ├── predictions.txt                    # 最新识别结果
│   ├── predictions_improved.txt           # 改进版识别结果
│   └── visualizations/                    # 可视化标注图片
│
└── yolov8n.pt                             # YOLOv8n预训练模型（6.2MB）
```

## 📝 文件说明

### 核心脚本

#### 1. `prepare_yolo_dataset.py` - 数据集准备
**功能**: 将COCO格式数据集转换为YOLO格式
**输入**: `digit-validation/coco.json`
**输出**: `yolo_dataset/` (包含images和labels)
**用法**:
```bash
python scripts/prepare_yolo_dataset.py
```

#### 2. `train_yolo.py` - 模型训练
**功能**: 训练YOLO模型
**参数**:
- `--data`: 数据集配置文件（dataset.yaml）
- `--model`: 预训练模型（yolov8n.pt）
- `--epochs`: 训练轮数
- `--batch`: 批次大小
- `--name`: 实验名称
**用法**:
```bash
python scripts/train_yolo.py --epochs 150 --name my_experiment
```

#### 3. `predict_digits.py` - 基础识别
**功能**: 基础版数字识别（无智能过滤）
**参数**:
- `--model`: 模型路径
- `--source`: 图片目录
- `--conf`: 置信度阈值（默认0.25）
- `--save-vis`: 保存可视化结果
**用法**:
```bash
python scripts/predict_digits.py --model runs/digit_yolo/exp1/weights/best.pt
```

#### 4. `predict_digits_improved.py` - 改进版识别 ⭐
**功能**: 带智能过滤的数字识别（推荐使用）
**特性**:
- 置信度过滤
- 位置异常检测
- 数量异常处理（<4或>4个数字）
- 从左到右排序
**用法**:
```bash
python scripts/predict_digits_improved.py \
    --model runs/digit_yolo/exp_preprocessed_color_150/weights/best.pt \
    --source valid \
    --conf 0.2 \
    --save-vis
```

#### 5. `preprocess_images.py` - 图片预处理
**功能**: 对图片进行预处理以提升识别效果
**预处理方法**:
- `auto`: 自动增强（去噪+锐化）
- `clahe`: 对比度限制自适应直方图均衡化 ⭐推荐
- `binary`: 自适应二值化
- `denoise`: 去噪
- `sharpen`: 锐化
- `combined`: 组合方法
**参数**:
- `--input-dir`: 输入图片目录
- `--output-dir`: 输出目录
- `--method`: 预处理方法
- `--keep-color`: 保持彩色（重要！）
**用法**:
```bash
python scripts/preprocess_images.py \
    --input-dir digit-validation/images \
    --output-dir digit-validation-processed \
    --method clahe \
    --keep-color
```

#### 6. `train_with_preprocessing.py` - 完整训练流程 ⭐
**功能**: 自动化预处理+训练+测试流程
**流程**:
1. 预处理训练图片
2. 准备YOLO数据集
3. 训练模型
4. 测试识别效果
**用法**:
```bash
python scripts/train_with_preprocessing.py \
    --preprocess-method clahe \
    --keep-color \
    --epochs 150 \
    --exp-name my_experiment
```

#### 7. `compare_results.py` - 结果对比
**功能**: 对比不同模型的识别效果
**输出**: Markdown格式的对比报告
**用法**:
```bash
python scripts/compare_results.py \
    --original results/predictions_improved.txt \
    --preprocessed results/predictions_exp_preprocessed_150.txt
```

#### 8. `run_all.py` - 完整流程自动化
**功能**: 一键运行完整训练+识别流程
**用法**:
```bash
python scripts/run_all.py --epochs 100
```

### 配置文件

#### `yolo_dataset/dataset.yaml`
YOLO数据集配置文件，定义了：
- 数据集路径
- 类别数量（10个，0-9）
- 类别名称

#### `runs/digit_yolo/*/args.yaml`
每次训练的参数记录

### 输出文件

#### 训练输出
- `runs/digit_yolo/*/weights/best.pt`: 最佳模型权重
- `runs/digit_yolo/*/weights/last.pt`: 最后轮次权重
- `runs/digit_yolo/*/results.csv`: 训练指标（loss, mAP等）

#### 识别输出
- `results/predictions*.txt`: 识别结果（制表符分隔）
- `results/visualizations*/`: 带标注的可视化图片

## 🚀 使用流程

### 场景1: 直接使用最佳模型识别

```bash
# 1. 激活环境
source ~/venv/bin/activate

# 2. 运行识别
python scripts/predict_digits_improved.py \
    --model runs/digit_yolo/exp_preprocessed_color_150/weights/best.pt \
    --source valid \
    --conf 0.2 \
    --save-vis

# 3. 查看结果
cat results/predictions_improved.txt
```

### 场景2: 重新训练模型

```bash
# 使用CLAHE预处理 + 150轮训练
python scripts/train_with_preprocessing.py \
    --preprocess-method clahe \
    --keep-color \
    --epochs 150 \
    --exp-name my_retrain
```

### 场景3: 使用交互式脚本

```bash
./run.sh
# 然后根据菜单选择操作
```

## 📊 数据流向

```
原始COCO数据
    ↓
[prepare_yolo_dataset.py]
    ↓
YOLO格式数据 (yolo_dataset/)
    ↓
[preprocess_images.py] (可选)
    ↓
预处理数据
    ↓
[train_yolo.py]
    ↓
训练好的模型 (runs/digit_yolo/)
    ↓
[predict_digits_improved.py]
    ↓
识别结果 (results/)
```

## 🎯 关键文件

1. **最佳模型**: `runs/digit_yolo/exp_preprocessed_color_150/weights/best.pt`
2. **推荐脚本**: `scripts/predict_digits_improved.py`
3. **完整流程**: `scripts/train_with_preprocessing.py`
4. **快速运行**: `run.sh`

## 💡 文件命名规范

- **训练实验**: `exp_<方法>_<轮数>` (如 `exp_preprocessed_color_150`)
- **识别结果**: `predictions_<配置>.txt` (如 `predictions_improved.txt`)
- **可视化**: `visualizations_<配置>/` (如 `visualizations_improved/`)

## 🧹 已清理文件

以下文件已被清理（不再需要）：
- ❌ 失败的灰度预处理实验数据
- ❌ 早期验证实验（exp1_val, exp1_valid）
- ❌ 过时的预测结果
- ❌ 临时预处理文档
- ❌ 初始待办清单

## 📦 依赖安装

```bash
pip install ultralytics opencv-python numpy tqdm matplotlib
```

## 🔗 相关文档

- [完整文档](README.md)
- [快速开始](QUICKSTART.md)
- [项目报告](FINAL_REPORT.md)

---

*最后更新: 2025-10-30*