gavin/digit-cracker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

first commit

Browse Source
This commit is contained in:
douboer
2025-10-30 15:40:56 +08:00
parent fe4a3e7cbf
commit 2fb4b22328
344 changed files with 8595 additions and 567 deletions
Download Patch File Download Diff File Expand all files Collapse all files

293
PROJECT_STRUCTURE.md Normal file
View File

@@ -0,0 +1,293 @@
# 项目结构说明
## 📁 目录结构
```
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*