Files

douboer 2fb4b22328 first commit

2025-10-30 15:40:56 +08:00

8.9 KiB

Raw Blame History

项目结构说明

📁 目录结构

digit_cracker/
├── README.md                              # 完整项目文档
├── QUICKSTART.md                          # 快速开始指南
├── FINAL_REPORT.md                        # 项目完成报告
├── PROJECT_STRUCTURE.md                   # 本文件
├── run.sh                                 # 交互式运行脚本
├── .gitignore                             # Git忽略文件配置
│
├── scripts/                               # Python脚本目录
│   ├── prepare_yolo_dataset.py            # [1] COCO→YOLO数据集转换
│   ├── train_yolo.py                      # [2] YOLO模型训练
│   ├── predict_digits.py                  # [3] 基础数字识别
│   ├── predict_digits_improved.py         # [4] 改进版数字识别 ⭐推荐
│   ├── preprocess_images.py               # [5] 图片预处理工具
│   ├── train_with_preprocessing.py        # [6] 预处理+训练流程
│   ├── compare_results.py                 # [7] 结果对比工具
│   └── run_all.py                         # [8] 完整流程自动化
│
├── digit-validation/                      # 原始训练数据（COCO格式）
│   ├── coco.json                          # COCO标注文件
│   └── images/                            # 训练图片（49张）
│
├── valid/                                 # 待识别图片（15张）
│   ├── YZM.jpeg
│   ├── YZM-2.jpeg
│   └── ...
│
├── yolo_dataset/                          # YOLO格式数据集
│   ├── dataset.yaml                       # 数据集配置文件
│   ├── images/                            # 图片（训练集+验证集）
│   │   ├── train/                         # 训练集图片（39张）
│   │   └── val/                           # 验证集图片（10张）
│   └── labels/                            # YOLO格式标注
│       ├── train/                         # 训练集标注（.txt）
│       └── val/                           # 验证集标注（.txt）
│
├── runs/                                  # 训练输出目录
│   └── digit_yolo/                        # YOLO训练实验
│       ├── exp1/                          # 基础模型（100轮，无预处理）
│       │   ├── weights/
│       │   │   ├── best.pt                # 最佳权重
│       │   │   └── last.pt                # 最后权重
│       │   ├── results.csv                # 训练指标
│       │   └── args.yaml                  # 训练参数
│       │
│       └── exp_preprocessed_color_150/    # 优化模型（150轮，CLAHE预处理）⭐最佳
│           ├── weights/
│           │   ├── best.pt                # 最佳权重（5.9MB）⭐⭐⭐
│           │   └── last.pt                # 最后权重（5.9MB）
│           ├── results.csv                # 训练指标
│           └── args.yaml                  # 训练参数
│
├── results/                               # 识别结果目录
│   ├── predictions.txt                    # 最新识别结果
│   ├── predictions_improved.txt           # 改进版识别结果
│   └── visualizations/                    # 可视化标注图片
│
└── yolov8n.pt                             # YOLOv8n预训练模型（6.2MB）

📝 文件说明

核心脚本

1. `prepare_yolo_dataset.py` - 数据集准备

功能: 将COCO格式数据集转换为YOLO格式输入: digit-validation/coco.json 输出: yolo_dataset/ (包含images和labels) 用法:

python scripts/prepare_yolo_dataset.py

2. `train_yolo.py` - 模型训练

功能: 训练YOLO模型参数:

--data: 数据集配置文件（dataset.yaml）
--model: 预训练模型（yolov8n.pt）
--epochs: 训练轮数
--batch: 批次大小
--name: 实验名称用法:

python scripts/train_yolo.py --epochs 150 --name my_experiment

3. `predict_digits.py` - 基础识别

功能: 基础版数字识别（无智能过滤）参数:

--model: 模型路径
--source: 图片目录
--conf: 置信度阈值（默认0.25）
--save-vis: 保存可视化结果用法:

python scripts/predict_digits.py --model runs/digit_yolo/exp1/weights/best.pt

4. `predict_digits_improved.py` - 改进版识别 ⭐

功能: 带智能过滤的数字识别（推荐使用）特性:

置信度过滤
位置异常检测
数量异常处理（<4或>4个数字）
从左到右排序用法:

python scripts/predict_digits_improved.py \
    --model runs/digit_yolo/exp_preprocessed_color_150/weights/best.pt \
    --source valid \
    --conf 0.2 \
    --save-vis

5. `preprocess_images.py` - 图片预处理

功能: 对图片进行预处理以提升识别效果 预处理方法:

auto: 自动增强（去噪+锐化）
clahe: 对比度限制自适应直方图均衡化 ⭐推荐
binary: 自适应二值化
denoise: 去噪
sharpen: 锐化
combined: 组合方法参数:
--input-dir: 输入图片目录
--output-dir: 输出目录
--method: 预处理方法
--keep-color: 保持彩色（重要！）用法:

python scripts/preprocess_images.py \
    --input-dir digit-validation/images \
    --output-dir digit-validation-processed \
    --method clahe \
    --keep-color

6. `train_with_preprocessing.py` - 完整训练流程 ⭐

功能: 自动化预处理+训练+测试流程流程:

预处理训练图片
准备YOLO数据集
训练模型
测试识别效果用法:

python scripts/train_with_preprocessing.py \
    --preprocess-method clahe \
    --keep-color \
    --epochs 150 \
    --exp-name my_experiment

7. `compare_results.py` - 结果对比

功能: 对比不同模型的识别效果输出: Markdown格式的对比报告用法:

python scripts/compare_results.py \
    --original results/predictions_improved.txt \
    --preprocessed results/predictions_exp_preprocessed_150.txt

8. `run_all.py` - 完整流程自动化

功能: 一键运行完整训练+识别流程用法:

python scripts/run_all.py --epochs 100

配置文件

`yolo_dataset/dataset.yaml`

YOLO数据集配置文件，定义了：

数据集路径
类别数量（10个，0-9）
类别名称

`runs/digit_yolo/*/args.yaml`

每次训练的参数记录

输出文件

训练输出

runs/digit_yolo/*/weights/best.pt: 最佳模型权重
runs/digit_yolo/*/weights/last.pt: 最后轮次权重
runs/digit_yolo/*/results.csv: 训练指标（loss, mAP等）

识别输出

results/predictions*.txt: 识别结果（制表符分隔）
results/visualizations*/: 带标注的可视化图片

🚀 使用流程

场景1: 直接使用最佳模型识别

# 1. 激活环境
source ~/venv/bin/activate

# 2. 运行识别
python scripts/predict_digits_improved.py \
    --model runs/digit_yolo/exp_preprocessed_color_150/weights/best.pt \
    --source valid \
    --conf 0.2 \
    --save-vis

# 3. 查看结果
cat results/predictions_improved.txt

场景2: 重新训练模型

# 使用CLAHE预处理 + 150轮训练
python scripts/train_with_preprocessing.py \
    --preprocess-method clahe \
    --keep-color \
    --epochs 150 \
    --exp-name my_retrain

场景3: 使用交互式脚本

./run.sh
# 然后根据菜单选择操作

📊 数据流向

原始COCO数据
    ↓
[prepare_yolo_dataset.py]
    ↓
YOLO格式数据 (yolo_dataset/)
    ↓
[preprocess_images.py] (可选)
    ↓
预处理数据
    ↓
[train_yolo.py]
    ↓
训练好的模型 (runs/digit_yolo/)
    ↓
[predict_digits_improved.py]
    ↓
识别结果 (results/)

🎯 关键文件

最佳模型: runs/digit_yolo/exp_preprocessed_color_150/weights/best.pt
推荐脚本: scripts/predict_digits_improved.py
完整流程: scripts/train_with_preprocessing.py
快速运行: run.sh

💡 文件命名规范

训练实验: exp_<方法>_<轮数> (如 exp_preprocessed_color_150)
识别结果: predictions_<配置>.txt (如 predictions_improved.txt)
可视化: visualizations_<配置>/ (如 visualizations_improved/)

🧹 已清理文件

以下文件已被清理（不再需要）：

❌ 失败的灰度预处理实验数据
❌ 早期验证实验（exp1_val, exp1_valid）
❌ 过时的预测结果
❌ 临时预处理文档
❌ 初始待办清单

📦 依赖安装

pip install ultralytics opencv-python numpy tqdm matplotlib

🔗 相关文档

最后更新: 2025-10-30

8.9 KiB Raw Blame History Unescape Escape