-
v1.0.0 Stable
gavin released this
2025-10-30 15:47:21 +08:00 | 1 commits to main since this releaseYOLO数字识别系统，使用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：使用交互式脚本（推荐）
最简单的方式，适合日常使用：
./run.sh会显示交互式菜单，提供5个常用功能：
- 选项 1：标准识别（conf=0.2, imgsz=320）
- 选项 2：低阈值识别（conf=0.15，适合模糊图片）
- 选项 3：高分辨率识别（imgsz=640，适合小数字）
- 选项 4：查看已有结果（模型、识别结果、可视化）
- 选项 0：退出
特点：
- ✅ 自动检测虚拟环境
- ✅ 彩色输出和友好提示
- ✅ 智能错误处理
- ✅ 详细的使用说明
方法2：命令行直接识别
使用最佳模型进行识别：
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：完整训练流程
如需重新训练模型：
python scripts/run_all.py这将自动执行：
- 从COCO格式转换为YOLO格式数据集
- 训练YOLOv8模型（100轮）
- 在valid文件夹上进行识别
安装依赖
pip install ultralytics opencv-python详细使用指南
分步执行
步骤1：准备数据集
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：训练模型
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：识别数字（使用最佳模型）
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
- 训练损失和验证损失
可以使用以下命令查看训练曲线：
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/，每张图片会标注检测框和识别的数字。高级用法
使用交互式脚本的不同选项
./run.sh # 根据图片质量选择： # - 标准图片：选项1（默认，速度快） # - 模糊/低对比度：选项2（降低阈值） # - 小数字/高精度：选项3（提高分辨率）图片预处理（提升识别率）
对于低质量图片，可以先进行预处理：
python scripts/preprocess_images.py \ --input valid \ --output valid-processed \ --method clahe \ --keep-color然后对预处理后的图片进行识别。
仅使用已训练模型进行识别
如果已经有训练好的模型，可以跳过训练步骤：
python scripts/run_all.py --skip-train --skip-prepare调整训练参数
# 使用更大的模型 python scripts/train_yolo.py --model yolov8s.pt --epochs 200 # 调整批次大小和图片大小 python scripts/train_yolo.py --batch 32 --imgsz 640批量预测自定义文件夹
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: 添加执行权限：
chmod +x run.shQ2: 导入错误
ModuleNotFoundError: No module named 'ultralytics'A: 安装ultralytics库：
pip install ultralytics建议使用虚拟环境：
python -m venv venv source venv/bin/activate # macOS/Linux pip install ultralytics opencv-pythonQ3: 识别结果不是4位数字
A: 可能的原因和解决方法：
- 置信度阈值太高 → 使用
./run.sh选项2（低阈值识别） - 图片质量差 → 先用
preprocess_images.py进行CLAHE预处理 - 数字太小 → 使用
./run.sh选项3（高分辨率识别） - 光照不均 → 使用CLAHE预处理增强对比度
推荐组合：预处理 + 低阈值识别
Q4: 训练速度慢
A: 建议：
- 使用GPU加速（自动检测CUDA）
- 减小批次大小
--batch 8 - 使用更小的图片尺寸
--imgsz 256
Q5: 显存不足
A: 降低批次大小：
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 工作流程建议
日常识别：
./run.sh # 选择选项1，快速识别困难图片：
# 步骤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查看结果：
./run.sh # 选择选项4，查看所有结果文件数据集格式
COCO格式（输入）
{ "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）优化建议
- 增加训练数据: 当前数据集较小，可以增加更多标注数据
- 数据增强: 在训练时使用更多数据增强（旋转、缩放、亮度变化等）
- 模型选择: 根据精度要求选择不同大小的模型（n/s/m/l/x）
- 超参数调优: 调整学习率、优化器等参数
- 后处理优化: 根据业务规则（必须4位数字）进行后处理
� 项目文档
- README.md: 完整使用文档（本文件）
- QUICKSTART.md: 5分钟快速上手指南
- FINAL_REPORT.md: 项目完成报告和性能分析
- PROJECT_STRUCTURE.md: 详细的项目结构说明
- CODE_CLEANUP_DONE.md: 代码清理和优化记录
作者
Gavin Chan
� 参考资料
Downloads