From 69adb01567205e0f9d1bf632c4647875a0bec8e8 Mon Sep 17 00:00:00 2001
From: douboer <douboer@gmail.com>
Date: Thu, 30 Oct 2025 15:45:34 +0800
Subject: [PATCH] update at 2025-10-30 15:45:34

---
 README.md | 152 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 139 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 2bfff49..cdf7c31 100644
--- a/README.md
+++ b/README.md
@@ -44,13 +44,43 @@ digit_cracker/
 
 ## 🚀 快速开始
 
-### 1. 安装依赖
+### 方法1：使用交互式脚本（推荐）
+
+**最简单的方式**，适合日常使用：
 
 ```bash
-pip install ultralytics opencv-python
+./run.sh
 ```
 
-### 2. 一键运行（完整流程）
+会显示交互式菜单，提供5个常用功能：
+- **选项 1**：标准识别（conf=0.2, imgsz=320）
+- **选项 2**：低阈值识别（conf=0.15，适合模糊图片）
+- **选项 3**：高分辨率识别（imgsz=640，适合小数字）
+- **选项 4**：查看已有结果（模型、识别结果、可视化）
+- **选项 0**：退出
+
+**特点**：
+- ✅ 自动检测虚拟环境
+- ✅ 彩色输出和友好提示
+- ✅ 智能错误处理
+- ✅ 详细的使用说明
+
+### 方法2：命令行直接识别
+
+使用最佳模型进行识别：
+
+```bash
+python scripts/predict_digits_improved.py \
+    --model runs/digit_yolo/exp_preprocessed_color_150/weights/best.pt \
+    --source valid \
+    --conf 0.2 \
+    --output results/predictions.txt \
+    --save-vis
+```
+
+### 方法3：完整训练流程
+
+如需重新训练模型：
 
 ```bash
 python scripts/run_all.py
@@ -61,7 +91,15 @@ python scripts/run_all.py
 2. 训练YOLOv8模型（100轮）
 3. 在valid文件夹上进行识别
 
-### 3. 分步执行
+### 安装依赖
+
+```bash
+pip install ultralytics opencv-python
+```
+
+## 📖 详细使用指南
+
+### 分步执行
 
 #### 步骤1：准备数据集
 
@@ -154,6 +192,30 @@ YZM-2.jpeg          0367        0.892     4
 
 ## 🔧 高级用法
 
+### 使用交互式脚本的不同选项
+
+```bash
+./run.sh
+# 根据图片质量选择：
+# - 标准图片：选项1（默认，速度快）
+# - 模糊/低对比度：选项2（降低阈值）
+# - 小数字/高精度：选项3（提高分辨率）
+```
+
+### 图片预处理（提升识别率）
+
+对于低质量图片，可以先进行预处理：
+
+```bash
+python scripts/preprocess_images.py \
+    --input valid \
+    --output valid-processed \
+    --method clahe \
+    --keep-color
+```
+
+然后对预处理后的图片进行识别。
+
 ### 仅使用已训练模型进行识别
 
 如果已经有训练好的模型，可以跳过训练步骤：
@@ -201,34 +263,86 @@ python scripts/predict_digits.py \
 
 ## 🐛 常见问题
 
-### Q1: 导入错误 `ModuleNotFoundError: No module named 'ultralytics'`
+### Q1: 运行 `./run.sh` 提示权限错误
+
+A: 添加执行权限：
+```bash
+chmod +x run.sh
+```
+
+### Q2: 导入错误 `ModuleNotFoundError: No module named 'ultralytics'`
 
 A: 安装ultralytics库：
 ```bash
 pip install ultralytics
 ```
 
-### Q2: 识别结果不是4位数字
+建议使用虚拟环境：
+```bash
+python -m venv venv
+source venv/bin/activate  # macOS/Linux
+pip install ultralytics opencv-python
+```
 
-A: 可能的原因：
-1. 置信度阈值太高，尝试降低 `--conf` 参数（如0.1）
-2. 模型训练不足，增加训练轮数
-3. 图片质量问题，检查图片清晰度
+### Q3: 识别结果不是4位数字
 
-### Q3: 训练速度慢
+A: 可能的原因和解决方法：
+1. **置信度阈值太高** → 使用 `./run.sh` 选项2（低阈值识别）
+2. **图片质量差** → 先用 `preprocess_images.py` 进行CLAHE预处理
+3. **数字太小** → 使用 `./run.sh` 选项3（高分辨率识别）
+4. **光照不均** → 使用CLAHE预处理增强对比度
+
+推荐组合：预处理 + 低阈值识别
+
+### Q4: 训练速度慢
 
 A: 建议：
 1. 使用GPU加速（自动检测CUDA）
 2. 减小批次大小 `--batch 8`
 3. 使用更小的图片尺寸 `--imgsz 256`
 
-### Q4: 显存不足
+### Q5: 显存不足
 
 A: 降低批次大小：
 ```bash
 python scripts/train_yolo.py --batch 8
 ```
 
+## 💡 使用建议
+
+### 识别策略选择
+
+根据图片特点选择合适的识别方式：
+
+| 图片特点 | 推荐方法 | run.sh选项 | 命令行参数 |
+|---------|---------|-----------|-----------|
+| 标准清晰 | 标准识别 | 选项 1 | conf=0.2, imgsz=320 |
+| 模糊/暗淡 | 低阈值 | 选项 2 | conf=0.15, imgsz=320 |
+| 数字很小 | 高分辨率 | 选项 3 | conf=0.2, imgsz=640 |
+| 低对比度 | 预处理+标准 | 先预处理 | CLAHE增强 |
+| 严重模糊 | 预处理+低阈值 | 先预处理 | CLAHE + conf=0.15 |
+
+### 工作流程建议
+
+**日常识别**：
+```bash
+./run.sh  # 选择选项1，快速识别
+```
+
+**困难图片**：
+```bash
+# 步骤1：预处理
+python scripts/preprocess_images.py --input valid --output valid-processed --method clahe
+
+# 步骤2：识别预处理后的图片
+python scripts/predict_digits_improved.py --source valid-processed --conf 0.15
+```
+
+**查看结果**：
+```bash
+./run.sh  # 选择选项4，查看所有结果文件
+```
+
 ## 📝 数据集格式
 
 ### COCO格式（输入）
@@ -274,7 +388,19 @@ python scripts/train_yolo.py --batch 8
 4. **超参数调优**: 调整学习率、优化器等参数
 5. **后处理优化**: 根据业务规则（必须4位数字）进行后处理
 
-## 📚 参考资料
+## � 项目文档
+
+- **README.md**: 完整使用文档（本文件）
+- **QUICKSTART.md**: 5分钟快速上手指南
+- **FINAL_REPORT.md**: 项目完成报告和性能分析
+- **PROJECT_STRUCTURE.md**: 详细的项目结构说明
+- **CODE_CLEANUP_DONE.md**: 代码清理和优化记录
+
+## 👨‍💻 作者
+
+Gavin Chan
+
+## �📚 参考资料
 
 - [Ultralytics YOLOv8 文档](https://docs.ultralytics.com/)
 - [YOLO目标检测原理](https://arxiv.org/abs/2305.09972)