294 lines
8.9 KiB
Markdown
294 lines
8.9 KiB
Markdown
# 项目结构说明
|
||
|
||
## 📁 目录结构
|
||
|
||
```
|
||
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*
|