gavin/digit-cracker

Fork 0

Files

douboer 69adb01567 update at 2025-10-30 15:45:34

2025-10-30 15:45:34 +08:00

11 KiB

Raw Permalink Blame History

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：使用交互式脚本（推荐）

最简单的方式，适合日常使用：

./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.sh

Q2: 导入错误 `ModuleNotFoundError: No module named 'ultralytics'`

A: 安装ultralytics库：

pip install ultralytics

建议使用虚拟环境：

python -m venv venv
source venv/bin/activate  # macOS/Linux
pip install ultralytics opencv-python

Q3: 识别结果不是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位数字）进行后处理

<EFBFBD> 项目文档

README.md: 完整使用文档（本文件）
QUICKSTART.md: 5分钟快速上手指南
FINAL_REPORT.md: 项目完成报告和性能分析
PROJECT_STRUCTURE.md: 详细的项目结构说明
CODE_CLEANUP_DONE.md: 代码清理和优化记录

11 KiB Raw Permalink Blame History Unescape Escape

YOLO数字识别系统

🎯 项目亮点

📁 项目结构

🚀 快速开始

方法1：使用交互式脚本（推荐）

方法2：命令行直接识别

方法3：完整训练流程

安装依赖

📖 详细使用指南

分步执行

步骤1：准备数据集

步骤2：训练模型

步骤3：识别数字（使用最佳模型）

📊 查看结果

训练结果

识别结果

🔧 高级用法

使用交互式脚本的不同选项

图片预处理（提升识别率）

仅使用已训练模型进行识别

调整训练参数

批量预测自定义文件夹

📈 模型性能

数据集规模

性能对比

🐛 常见问题

Q1: 运行 ./run.sh 提示权限错误

Q2: 导入错误 ModuleNotFoundError: No module named 'ultralytics'

Q3: 识别结果不是4位数字

Q4: 训练速度慢

Q5: 显存不足

💡 使用建议

识别策略选择

工作流程建议

📝 数据集格式

COCO格式（输入）

YOLO格式（转换后）

🎯 优化建议

<EFBFBD> 项目文档

👨‍💻 作者

<EFBFBD>📚 参考资料

📄 许可证

11 KiB

Raw Permalink Blame History

Q1: 运行 `./run.sh` 提示权限错误

Q2: 导入错误 `ModuleNotFoundError: No module named 'ultralytics'`