first commit

QUICKSTART.md

@@ -0,0 +1,185 @@
+# 快速开始 - 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`