# Toukui

**Repository Path**: wang-zi10/toukui

## Basic Information

- **Project Name**: Toukui
- **Description**: 基于YOLOv8深度学习的安全帽佩戴检测系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-10
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于深度学习的安全帽佩戴检测系统

## 项目简介

本项目是基于深度学习的安全帽佩戴检测系统，使用YOLOv8n模型实现实时、准确的安全帽佩戴状态检测。系统能够在复杂施工场景中识别和判断工人是否佩戴安全帽，为安全管理提供技术支持。

## 主要功能

- ✅ **模型训练**: 支持从VOC格式数据集自动转换为YOLO格式并训练
- ✅ **模型评估**: 支持验证集和测试集评估，计算mAP等指标
- ✅ **Web界面**: 基于Gradio的交互式Web界面，支持：
  - 📷 摄像头实时检测（流式处理）
  - 🖼️ 图像上传检测
  - 📹 视频文件检测
  - 📊 实时统计显示
- ✅ **数据转换**: 自动将VOC格式数据集转换为YOLO格式

## 技术指标

### 模型性能
- **检测准确率**: 系统在测试集上的平均精度均值（mAP50）达到94.23%
- **实时性**: 检测速度FPS ≥ 118.90（GPU） / ~10-20（CPU）
- **鲁棒性**: 系统能在不同光照、角度、遮挡等复杂环境下稳定工作
- **数据集规模**: 训练集5447张、验证集605张、测试集1516张，共7581张标注图像

### 模型架构
- **基础模型**: YOLOv8n（轻量级版本，适合实时检测）
- **输入尺寸**: 640x640
- **类别数**: 2（hat: 安全帽, person: 人员）
- **优化**: 使用预训练权重（迁移学习）、余弦学习率调度

### 数据增强策略
- 旋转（±10度）
- 等比例缩放（0.5-1.5倍）
- 高斯噪声添加
- 马赛克增强
- 色调、饱和度、明度调整

## 环境配置

### 系统要求
- Python 3.8+
- PyTorch 2.0+（推荐使用GPU版本）
- CUDA（可选，但强烈推荐使用GPU训练）
- NVIDIA RTX系列GPU（推荐）

### 安装依赖

```bash
# 1. 安装PyTorch（GPU版本，推荐）
# 访问 https://pytorch.org/get-started/locally/ 查看对应CUDA版本的安装命令
# 例如，CUDA 11.8版本：
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

# 2. 安装其他依赖包
pip install -r requirements.txt
```

### 主要依赖
- `ultralytics>=8.0.0,<8.1.0` - YOLOv8官方实现（限制版本确保使用YOLOv8而非YOLOv11）
- `torch>=2.0.0` - PyTorch深度学习框架
- `opencv-python>=4.6.0` - 图像处理
- `gradio>=4.0.0` - Web界面框架
- `numpy>=1.21.0,<2.0.0` - 数值计算（限制版本避免兼容性问题）
- `pyyaml>=6.0` - 配置文件解析

完整依赖列表请查看 `requirements.txt`

## 快速开始

### 1. 准备数据集

确保数据集按照以下结构组织（VOC格式）：

```
VOC2028/
├── Annotations/      # XML标注文件
│   ├── 000001.xml
│   ├── 000002.xml
│   └── ...
├── JPEGImages/       # 图像文件
│   ├── 000001.jpg
│   ├── 000002.jpg
│   └── ...
└── ImageSets/
    └── Main/
        ├── train.txt
        ├── val.txt
        └── test.txt
```

**注意**: 训练脚本会自动将VOC格式转换为YOLO格式。如果已有YOLO格式数据集，可以直接使用。

### 2. 配置参数

编辑 `config.yaml` 文件，根据实际情况调整参数：
- 数据集路径
- 训练参数（epochs, batch_size等）
- 模型配置
- 数据增强参数

### 3. 开始训练

```bash
# 基础训练命令
python train.py --config config.yaml

# 从检查点恢复训练（如果中断）
python train.py --config config.yaml --resume
```

训练过程会自动：
- 检查并转换VOC格式数据集为YOLO格式（如果需要）
- 加载预训练权重（迁移学习）
- 应用数据增强（旋转、缩放、高斯噪声、马赛克等）
- 使用余弦学习率调度
- 保存最佳模型和训练日志

### 4. 评估模型

```bash
# 在验证集上评估
python evaluate.py --weights runs/helmet_detection/weights/best.pt --split val

# 在测试集上评估
python evaluate.py --weights runs/helmet_detection/weights/best.pt --split test
```

### 5. 使用Web界面

```bash
# 启动Gradio Web界面
python gradio_app.py
```

启动后，在浏览器中打开 `http://127.0.0.1:7860` 即可使用：

#### 使用步骤：

1. **加载模型**
   - 系统会自动查找模型文件（优先使用 `best.pt`）
   - 如果路径不正确，可以手动输入模型路径
   - 点击"加载模型"按钮

2. **调整参数**
   - 使用滑块调整置信度阈值（建议0.25-0.5）

3. **选择检测模式**
   - **摄像头实时检测**: 点击摄像头标签页，允许访问摄像头后即可实时检测
   - **图像检测**: 上传一张图片进行检测
   - **视频检测**: 上传视频文件，系统会处理并生成带检测框的视频

#### Web界面功能说明：

- **摄像头实时检测**: 使用设备摄像头进行实时安全帽检测（流式处理，10 FPS）
- **图像上传检测**: 上传单张图像进行检测
- **视频文件检测**: 上传视频文件，自动处理并生成检测结果视频（保存在 `output_detection.mp4`）
- **实时统计**: 实时显示检测到的安全帽和人员数量

## 项目结构

```
.
├── config.yaml                    # 配置文件
├── requirements.txt               # 依赖包列表
├── README.md                      # 项目说明文档（本文件）
│
├── train.py                       # 训练脚本
├── evaluate.py                    # 评估脚本
├── gradio_app.py                  # Gradio Web界面
│
├── convert_voc_to_yolo.py         # VOC格式转YOLO格式脚本
├── dataset.py                     # 数据集加载器（VOC格式支持）
├── download_pretrained_model.py   # 下载预训练模型脚本（可选）
├── analyze_training_results_simple.py  # 训练结果分析脚本（简化版）
│
├── VOC2028/                       # VOC格式数据集目录
│   ├── Annotations/
│   ├── JPEGImages/
│   └── ImageSets/
│
├── YOLO_dataset/                  # YOLO格式数据集目录（自动生成）
│   ├── dataset.yaml
│   ├── train/
│   ├── val/
│   └── test/
│
├── runs/                          # 训练输出目录（自动生成）
│   └── helmet_detection/
│       ├── weights/
│       │   ├── best.pt            # 最佳模型权重
│       │   └── last.pt            # 最后一个epoch的权重
│       ├── results.png            # 训练曲线图
│       └── ...
│
└── fonts/                         # 字体文件（用于Web界面显示中文）
    └── aa.ttf
```

## 训练配置说明

### 模型配置（config.yaml）

主要配置项：

```yaml
model:
  name: yolov8n          # 使用YOLOv8n模型
  pretrained: true       # 使用预训练权重（迁移学习）

train:
  epochs: 300           # 训练轮数
  batch_size: 16        # 批次大小（根据GPU显存调整）
  imgsz: 640            # 输入图像尺寸
  device: 0             # GPU设备ID（0表示第一块GPU，cpu表示使用CPU）
  scheduler: cosine     # 余弦学习率调度
  
  augmentation:
    degrees: 10         # 旋转角度（±10度）
    scale: 0.5          # 缩放范围（0.5-1.5倍）
    mosaic: 1.0         # 马赛克增强概率
    gaussian_noise: 0.1 # 高斯噪声概率
```

详细配置说明请查看 `config.yaml` 文件中的注释。

## 训练输出

训练完成后，会在 `runs/helmet_detection/` 目录下生成：

```
runs/helmet_detection/
├── weights/
│   ├── best.pt         # 最佳模型权重（mAP最高）
│   └── last.pt         # 最后一个epoch的权重
├── results.png         # 训练曲线图
├── confusion_matrix.png # 混淆矩阵
├── args.yaml           # 训练参数配置
├── results.csv         # 训练日志（CSV格式）
└── ...
```

## 性能评估

### 评估指标
- **mAP50**: 平均精度均值（IoU阈值=0.5）
- **mAP50-95**: 平均精度均值（IoU阈值=0.5:0.95）
- **FPS**: 每秒帧数（实时性指标）
- **准确率（Precision）**: 检测为正例中实际为正例的比例
- **召回率（Recall）**: 实际正例中被检测出的比例

### 实际性能（测试集）
- **mAP@0.5**: 94.23%
- **FPS**: 118.90 (GPU) / ~10-20 (CPU)
- **精确率**: 93.3%
- **召回率**: 88.6%

## 常见问题

### 1. 训练相关

**Q: 内存不足怎么办？**
- 减小 `batch_size` 或 `imgsz`
- 建议：batch_size=16, imgsz=640（根据GPU显存调整）

**Q: 训练速度慢？**
- 检查是否使用GPU（`device: 0`）
- 确认CUDA和PyTorch版本匹配
- 增加 `workers` 数量（数据加载线程数）

**Q: mAP不达标？**
- 检查数据集标注质量
- 增加训练轮数
- 调整数据增强参数

**Q: 为什么下载的是yolov11而不是yolov8？**
- 确保 `requirements.txt` 中 `ultralytics` 版本限制为 `<8.1.0`
- 运行：`pip install "ultralytics>=8.0.0,<8.1.0" --force-reinstall`

### 2. Web界面相关

**Q: 模型加载失败？**
- 确认模型文件路径正确
- 确认模型文件存在（`best.pt`或`last.pt`）
- 查看错误信息，可能是模型文件损坏

**Q: 摄像头无法访问？**
- 检查浏览器是否已授予摄像头权限
- 尝试使用不同的浏览器（推荐Chrome、Edge或Firefox）
- 确认没有其他程序占用摄像头

**Q: 检测结果不准确？**
- 调整置信度阈值（尝试0.3-0.5）
- 确保光照充足
- 确保目标清晰可见
- 检查模型是否是最佳权重（使用`best.pt`）

**Q: 视频处理很慢？**
- 视频处理需要逐帧检测，需要一定时间
- 可以尝试处理较短的视频片段
- 如果使用CPU，处理会较慢（建议使用GPU）

### 3. 数据集相关

**Q: 如何转换数据集？**
- 训练脚本会自动转换VOC格式为YOLO格式
- 或手动运行：`python convert_voc_to_yolo.py --voc-dir ./VOC2028 --output-dir ./YOLO_dataset`

**Q: 可以直接使用YOLO格式数据集吗？**
- 可以，确保数据集结构正确，并在 `YOLO_dataset/dataset.yaml` 中配置路径

## 开发进度

- [x] 项目结构搭建
- [x] 配置文件创建
- [x] VOC数据集加载器
- [x] YOLOv8n基础训练脚本
- [x] 模型评估脚本
- [x] VOC转YOLO格式转换脚本
- [x] Gradio Web界面（摄像头、图像、视频检测）
- [x] 训练结果分析脚本
- [ ] 坐标注意力机制实现（可选）
- [ ] 系统集成与部署优化

## 工具脚本说明

### convert_voc_to_yolo.py
将VOC格式数据集转换为YOLO格式，用于YOLOv8训练。

```bash
python convert_voc_to_yolo.py --voc-dir ./VOC2028 --output-dir ./YOLO_dataset
```

### download_pretrained_model.py
下载YOLOv8n预训练模型（可选，训练时会自动下载）。

```bash
python download_pretrained_model.py
```

### analyze_training_results_simple.py
分析训练结果，生成训练报告（简化版，不依赖pandas和matplotlib）。

```bash
python analyze_training_results_simple.py --results-dir runs/helmet_detection
```