# 快速开始 - YOLO数字识别

## ✅ 已完成的工作

1. ✅ 数据集准备（COCO → YOLO格式）
2. ✅ 模型训练（基础版100轮 + 优化版150轮）
3. ✅ Valid文件夹识别
4. ✅ 创建多个识别脚本（基础版+改进版）
5. ✅ 图片预处理系统（CLAHE对比度增强）
6. ✅ **优化模型训练完成**（exp_preprocessed_color_150，效果显著提升）

## 🎯 识别结果摘要

**使用优化后的模型**（CLAHE预处理 + 150轮训练）:
- **模型**: `exp_preprocessed_color_150/weights/best.pt`
- **训练集性能**: mAP50 = 0.995（接近完美）
- **推荐配置**: 使用CLAHE对比度增强预处理
- **结果文件**: `results/predictions.txt`
- **可视化**: `results/visualizations/`

## 🚀 快速使用

### 方法1: 使用最佳模型识别（推荐）⭐

```bash
source ~/venv/bin/activate
cd /Users/gavin/lab/digit_cracker

# 使用优化后的模型进行识别
python scripts/predict_digits_improved.py \
    --model runs/digit_yolo/exp_preprocessed_color_150/weights/best.pt \
    --source valid \
    --conf 0.2 \
    --save-vis
```

### 方法2: 使用快捷脚本

```bash
source ~/venv/bin/activate
cd /Users/gavin/lab/digit_cracker
./run.sh
```

然后选择相应的操作即可。

### 方法3: 识别自定义文件夹

```bash
python scripts/predict_digits_improved.py \
    --model runs/digit_yolo/exp_preprocessed_color_150/weights/best.pt \
    --source /path/to/your/images \
    --save-vis
```

## 📊 查看结果

```bash
# 查看识别结果
cat results/predictions_improved.txt

# 查看可视化（macOS）
open results/visualizations_improved/

# 查看训练指标
cat runs/digit_yolo/exp1/results.csv
```

## 🔧 优化选项

### 调整识别参数

```bash
# 降低置信度阈值（检测更多数字）
python scripts/predict_digits_improved.py --conf 0.15

# 增加图片尺寸（提高精度）
python scripts/predict_digits_improved.py --imgsz 640

# 组合使用
python scripts/predict_digits_improved.py --conf 0.15 --imgsz 640
```

### 重新训练模型

```bash
# 训练更多轮数
python scripts/train_yolo.py --epochs 200 --name exp2

# 使用更大模型
python scripts/train_yolo.py --model yolov8s.pt --epochs 200 --name exp3

# 使用新模型识别
python scripts/predict_digits_improved.py \
    --model runs/digit_yolo/exp2/weights/best.pt \
    --source valid
```

## 📁 项目文件说明

```
digit_cracker/
├── README.md                          # 完整文档
├── RESULTS_SUMMARY.md                 # 结果总结
├── QUICKSTART.md                      # 本文件
├── run.sh                             # 快捷运行脚本
│
├── scripts/                           # Python脚本
│   ├── prepare_yolo_dataset.py        # 数据准备
│   ├── train_yolo.py                  # 模型训练
│   ├── predict_digits.py              # 基础识别
│   ├── predict_digits_improved.py     # 改进版识别 ⭐
│   └── run_all.py                     # 一键运行
│
├── valid/                             # 待识别图片（15张）
├── digit-validation/                  # 训练数据集（COCO格式）
├── yolo_dataset/                      # YOLO格式数据集
│
├── runs/digit_yolo/exp1/              # 训练输出
│   └── weights/best.pt                # 已训练好的模型 ⭐
│
└── results/                           # 识别结果
    ├── predictions_improved.txt       # 识别结果 ⭐
    └── visualizations_improved/       # 可视化结果 ⭐
```

## 💡 常见问题

**Q: 为什么识别率只有20%？**

A: 主要原因：
1. 训练数据量较小（约39张训练图片）
2. valid图片与训练数据风格可能不同
3. 使用的是最小模型yolov8n

**Q: 如何提高识别率？**

A: 建议：
1. 训练更多轮数：`--epochs 200`
2. 使用更大模型：`--model yolov8s.pt`
3. 调整识别阈值：`--conf 0.15`
4. 增加训练数据（需要标注更多图片）

**Q: 如何识别其他文件夹的图片？**

A: 修改 `--source` 参数：
```bash
python scripts/predict_digits_improved.py \
    --source /path/to/your/folder
```

**Q: 识别结果保存在哪里？**

A: 
- 文本结果：`results/predictions_improved.txt`
- 可视化图片：`results/visualizations_improved/`

## 📞 获取帮助

```bash
# 查看完整文档
cat README.md

# 查看详细结果分析
cat RESULTS_SUMMARY.md

# 查看脚本帮助
python scripts/predict_digits_improved.py --help
python scripts/train_yolo.py --help
```

## 🎓 下一步

1. **尝试不同参数**：调整conf、imgsz等参数
2. **重新训练**：使用更多轮数或更大模型
3. **分析失败案例**：查看可视化结果，了解哪些图片识别失败
4. **数据增强**：如果有标注能力，可以标注更多数据

---

**项目位置**: `/Users/gavin/lab/digit_cracker`  
**虚拟环境**: `~/venv/bin/activate`  
**当前状态**: ✅ 可直接使用

更多信息请查看 `README.md` 和 `RESULTS_SUMMARY.md`