# YOLO数字识别系统 使用YOLOv8模型识别图片中的4位阿拉伯数字。经过图片预处理优化，识别准确率显著提升。 ## 🎯 项目亮点 - ✅ **高准确率**: 经过CLAHE对比度增强预处理后，识别准确率显著提升 - ✅ **完整流程**: 从数据预处理到模型训练再到批量识别的完整pipeline - ✅ **易于使用**: 提供交互式脚本和一键运行工具 - ✅ **可视化结果**: 自动生成带标注的可视化图片 ## 📁 项目结构 ``` digit_cracker/ ├── digit-validation/ # COCO格式训练数据集 │ ├── coco.json # 标注文件 │ └── images/ # 训练图片（文件名为4位数字） ├── valid/ # 待识别图片（文件名与内容无关） ├── yolo_dataset/ # 转换后的YOLO格式数据集 │ ├── dataset.yaml # 数据集配置 │ ├── images/ │ │ ├── train/ # 训练集图片 │ │ └── val/ # 验证集图片 │ └── labels/ │ ├── train/ # 训练集标注 │ └── val/ # 验证集标注 ├── runs/ # 训练输出 │ └── digit_yolo/ │ └── exp1/ │ ├── weights/ # 模型权重 │ │ ├── best.pt # 最佳模型 │ │ └── last.pt # 最后一轮模型 │ └── results.csv # 训练指标 ├── results/ # 预测结果 │ ├── predictions.txt # 识别结果文本 │ └── visualizations/ # 可视化结果图片 └── scripts/ # Python脚本 ├── prepare_yolo_dataset.py # 数据集准备 ├── train_yolo.py # 模型训练 ├── predict_digits.py # 数字识别 └── run_all.py # 一键运行 ``` ## 🚀 快速开始 ### 方法1：使用交互式脚本（推荐） **最简单的方式**，适合日常使用： ```bash ./run.sh ``` 会显示交互式菜单，提供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 ``` 这将自动执行： 1. 从COCO格式转换为YOLO格式数据集 2. 训练YOLOv8模型（100轮） 3. 在valid文件夹上进行识别 ### 安装依赖 ```bash pip install ultralytics opencv-python ``` ## 📖 详细使用指南 ### 分步执行 #### 步骤1：准备数据集 ```bash python scripts/prepare_yolo_dataset.py \ --root digit-validation \ --out yolo_dataset \ --val-ratio 0.2 \ --seed 20240305 ``` 参数说明： - `--root`: COCO数据集根目录 - `--out`: YOLO数据集输出目录 - `--val-ratio`: 验证集比例（默认0.2） - `--seed`: 随机种子（用于可重复划分） #### 步骤2：训练模型 ```bash python scripts/train_yolo.py \ --data yolo_dataset/dataset.yaml \ --model yolov8n.pt \ --epochs 100 \ --batch 16 \ --imgsz 320 \ --project runs/digit_yolo \ --name exp1 ``` 参数说明： - `--data`: 数据集配置文件 - `--model`: 预训练模型（yolov8n.pt为最小模型） - `--epochs`: 训练轮数 - `--batch`: 批次大小 - `--imgsz`: 输入图片大小 - `--project`: 输出项目目录 - `--name`: 实验名称 训练完成后，最佳模型保存在：`runs/digit_yolo/exp1/weights/best.pt` #### 步骤3：识别数字（使用最佳模型） ```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 ``` 参数说明： - `--model`: 训练好的模型路径 - `--source`: 待识别图片文件夹 - `--conf`: 置信度阈值（默认0.25） - `--output`: 结果输出文件 - `--save-vis`: 保存可视化结果 ## 📊 查看结果 ### 训练结果 训练指标保存在 `runs/digit_yolo/exp1/results.csv`，包括： - mAP50, mAP50-95 - Precision, Recall - 训练损失和验证损失 可以使用以下命令查看训练曲线： ```python from ultralytics import YOLO model = YOLO('runs/digit_yolo/exp1/weights/best.pt') model.val() # 在验证集上评估 ``` ### 识别结果 识别结果保存在 `results/predictions.txt`，格式： ``` 文件名 识别结果 置信度 数字个数 YZM.jpeg 0106 0.856 4 YZM-2.jpeg 0367 0.892 4 ... ``` 可视化结果保存在 `results/visualizations/`，每张图片会标注检测框和识别的数字。 ## 🔧 高级用法 ### 使用交互式脚本的不同选项 ```bash ./run.sh # 根据图片质量选择： # - 标准图片：选项1（默认，速度快） # - 模糊/低对比度：选项2（降低阈值） # - 小数字/高精度：选项3（提高分辨率） ``` ### 图片预处理（提升识别率） 对于低质量图片，可以先进行预处理： ```bash python scripts/preprocess_images.py \ --input valid \ --output valid-processed \ --method clahe \ --keep-color ``` 然后对预处理后的图片进行识别。 ### 仅使用已训练模型进行识别 如果已经有训练好的模型，可以跳过训练步骤： ```bash python scripts/run_all.py --skip-train --skip-prepare ``` ### 调整训练参数 ```bash # 使用更大的模型 python scripts/train_yolo.py --model yolov8s.pt --epochs 200 # 调整批次大小和图片大小 python scripts/train_yolo.py --batch 32 --imgsz 640 ``` ### 批量预测自定义文件夹 ```bash python scripts/predict_digits.py \ --model runs/digit_yolo/exp1/weights/best.pt \ --source /path/to/your/images \ --conf 0.3 \ --save-vis ``` ## 📈 模型性能 ### 数据集规模 - **类别**: 10个（数字0-9） - **训练集**: 39张图片（每张包含4个数字，~156个标注框） - **验证集**: 10张图片（~40个标注框） - **测试集**: 15张valid图片 ### 性能对比 | 模型 | 预处理方法 | 训练轮数 | mAP50 | valid准确率 | 说明 | |------|-----------|---------|-------|------------|------| | exp1 | 无 | 100 | 0.95+ | 20% (3/15) | 基础模型 | | exp_preprocessed_color_150 | CLAHE对比度增强 | 150 | 0.995 | **显著提升** | ✨ 推荐使用 | **最佳模型**: `runs/digit_yolo/exp_preprocessed_color_150/weights/best.pt` ## 🐛 常见问题 ### Q1: 运行 `./run.sh` 提示权限错误 A: 添加执行权限： ```bash chmod +x run.sh ``` ### Q2: 导入错误 `ModuleNotFoundError: No module named 'ultralytics'` A: 安装ultralytics库： ```bash pip install ultralytics ``` 建议使用虚拟环境： ```bash python -m venv venv source venv/bin/activate # macOS/Linux pip install ultralytics opencv-python ``` ### Q3: 识别结果不是4位数字 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` ### 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格式（输入） ```json { "images": [ { "id": 0, "file_name": "0106.jpeg", "width": 84, "height": 35 } ], "annotations": [ { "id": 0, "image_id": 0, "bbox": [12.1, 1.4, 19.1, 22.4], // [x, y, width, height] "property_info": "0" // 数字类别 } ] } ``` ### YOLO格式（转换后） 标注文件（.txt）格式，每行一个检测框： ``` 0 0.264706 0.342857 0.227451 0.640000 1 0.559524 0.628571 0.194048 0.625714 0 0.845238 0.382857 0.224405 0.617143 6 0.906548 0.645714 0.200119 0.645714 ``` 格式：`类别 x_center y_center width height`（所有值归一化到0-1） ## 🎯 优化建议 1. **增加训练数据**: 当前数据集较小，可以增加更多标注数据 2. **数据增强**: 在训练时使用更多数据增强（旋转、缩放、亮度变化等） 3. **模型选择**: 根据精度要求选择不同大小的模型（n/s/m/l/x） 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) ## 📄 许可证 MIT License