# hard-hat-workers

**Repository Path**: TJMSHE/hard-hat-workers

## Basic Information

- **Project Name**: hard-hat-workers
- **Description**: YOLOv8 head detection experiments on Roboflow Hard Hat Workers dataset (6 comparative experiments, best mAP50=0.9828)
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-17
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 👷 HardHatWorkers · YOLOv8 头部检测实验

> 用 YOLOv8 训练一个**头部检测模型**（单类，1 类 `head`）
> 数据集：Roboflow Hard Hat Workers v14（4916/1413/706 张，273 MB）

🔗 **项目仓库**：https://gitee.com/TJMSHE/hard-hat-workers （私有，按需开放）

📚 **完整教程**：[`GUIDE.md`](./GUIDE.md)

---

## 🎯 项目概览

| 项目 | 值 |
|------|-----|
| **任务** | 单类目标检测（检测图片中的所有人头）|
| **应用场景** | 工地安全监控、未戴安全帽预警、人群计数 |
| **类别数** | 1（`head`）|
| **数据集规模** | 训练 4916 / 验证 1413 / 测试 706 张 |
| **目标指标** | mAP50 ≥ 0.85，mAP50-95 ≥ 0.65 |
| **训练耗时** | 30-50 epoch × 6 实验 ≈ 4-5 小时（RTX 5070） |
| **🏆 实际达成** | **mAP50 = 0.9828, mAP50-95 = 0.6763**（exp3_yolov8m）|

## ⚡ 5 分钟上手

```bash
# 0) Clone / cd 到项目目录
cd ~/HardHatWorkers

# 1) 装环境
pip install -r requirements.txt

# 2) 下载数据集并建立软链接（避免复制 273 MB）
#    数据集: https://universe.roboflow.com/joseph-nelson/hard-hat-workers
#    下载 v14-raw_headclassonly 版本，解压到 ~/datasets/HardHatWorkers/
DATA_DIR="$HOME/HardHatWorkers.v14-raw_headclassonly"  # ← 改成你的路径
ln -sfn "$DATA_DIR/train" train
ln -sfn "$DATA_DIR/valid" valid
ln -sfn "$DATA_DIR/test"  test

# 3) 生成配置（自动改 data.yaml 路径，生成 6 个实验 YAML）
python scripts/04_prepare_configs.py

# 4) 跑第一个实验（试水 5 epoch）
python scripts/05_train_exp.py --exp exp1_baseline --epochs 5 --no-resume

# 5) 跑全部 6 个实验（生产训练，约 4 小时；带 watchdog 自动 resume）
bash scripts/99_watchdog_train.sh

# 6) 对比 6 个实验
python scripts/10_compare_experiments.py

# 7) 测试集最终评估
python scripts/11_test_eval.py --weights runs/exp3_yolov8m/weights/best.pt

# 8) 推理 demo (CLI)
python scripts/inference_demo.py --image test/images/your.jpg

# 9) 🚀 Web UI 演示（毕设答辩用，浏览器交互）
pip install -r requirements_streamlit.txt
streamlit run app.py
# 打开 http://localhost:8501
# 支持: 单图 / 批量 / 视频 / 网络流 / 摄像头 5 种模式
# 详细使用手册: STREAMLIT_GUIDE.md
```

> 💡 `train/valid/test` 是符号链接。Windows + WSL 环境下务必确认链接指向真实数据目录（`ls -la train` 应看到 `->`）。

## 📊 6 个对照实验

| # | 实验 | 模型 | imgsz | 核心变化 | 假设 |
|---|------|------|-------|---------|------|
| 1 | exp1_baseline | yolov8n | 640 | — | 基线 |
| 2 | exp2_yolov8s | yolov8s | 640 | 模型 n→s | 大模型更好？ |
| 3 | exp3_yolov8m | yolov8m | 640 | 模型 s→m | 最大模型收益？ |
| 4 | exp4_aug_off | yolov8n | 640 | 关掉增强 | 数据多时是否过拟合？ |
| 5 | exp5_aug_robust | yolov8s | 640 | s+强几何增强 | 极端宽高比需要强增强？ |
| 6 | exp6_best_combo | yolov8s | 640 | 综合最佳 | 决赛 |

## 🏆 实验结果（实际跑完）

| 排名 | 实验 | 模型 | best mAP50 | best mAP50-95 | best P | best R | 最佳 epoch | 训练时长 |
|------|------|------|------------|----------------|--------|--------|------------|----------|
| 🥇 | exp3_yolov8m | yolov8m | **0.9828** | **0.6843** | 0.9542 | 0.9522 | 29 | ~50 min |
| 🥈 | exp2_yolov8s | yolov8s | 0.9827 | 0.6803 | **0.9620** | 0.9436 | 25 | ~38 min |
| 🥉 | exp6_best_combo | yolov8s | 0.9826 | 0.6750 | 0.9556 | 0.9490 | 35 | ~48 min |
| 4 | exp5_aug_robust | yolov8s | 0.9813 | 0.6680 | 0.9527 | 0.9475 | 29 | ~30 min |
| 5 | exp1_baseline | yolov8n | 0.9805 | 0.6742 | 0.9539 | 0.9454 | 28 | ~25 min |
| 6 | exp4_aug_off | yolov8n | 0.9631 | 0.6382 | 0.9418 | 0.9150 | 12 | ~18 min |

### 关键发现

1. **数据增强必要**：`exp4_aug_off`（mAP50=0.9631）比基线低 1.7 个百分点，证实小目标 + 极端长宽比场景下增强不可省。
2. **大模型在 mAP50-95 上有实质收益**：`exp3_yolov8m`（mAP50-95=0.6843）比 `exp2_yolov8s`（0.6803）高 0.4pp，说明更严的 IoU 阈值下大模型优势显现；但 mAP50 差异仅 0.01pp，**只看 mAP50 时 s/m 没区别**。
3. **强增强 ≠ 一定更好**：`exp5_aug_robust`（0.9813）反而比 `exp2_yolov8s`（0.9827）低 0.14%。说明默认增强已足够，过强可能欠拟合。
4. **训练时长翻倍无收益**：`exp6_best_combo` 跑 50 epoch（0.9826）并不比 `exp3_yolov8m` 30 epoch（0.9828）好，说明 30 epoch 已收敛。
5. **绝对水平**：6 个实验 mAP50 全部 > 0.96，反映数据集相对简单（背景固定、人头清晰）。

详细对比图见 `results/comparison/`，测试集评估见 `results/test_eval/`，推理速度基准见 `results/benchmark/`。

## 📊 测试集最终评估（706 张图）

| 实验 | mAP50 | mAP50-95 | P | R | 备注 |
|------|-------|----------|---|---|------|
| **exp3_yolov8m** | **0.9848** | **0.6890** | 0.958 | 0.953 | ✅ 推荐 |
| exp6_best_combo | 0.9848 | 0.6822 | 0.961 | 0.950 | mAP50 并列 |

exp3_yolov8m 在 mAP50-95 上比 exp6 高 0.7pp，说明大模型在严苛 IoU 阈值下优势更明显。可视化对比见 `results/test_eval/pred_vs_gt_visualization.png`。

## 🥇 推荐使用的模型

| 优先级 | 实验 | 理由 |
|--------|------|------|
| 🥇 生产部署 | `exp3_yolov8m` | mAP50=0.9828, mAP50-95=0.6843 双重最高 |
| 🥈 边缘部署 | `exp2_yolov8s` | mAP50 仅低 0.01pp，模型小 1.8 倍，推理更快 |
| 🥉 训练预算紧 | `exp1_baseline` | mAP50=0.9805，yolov8n 仅 6MB，最快训练 |

**默认推理命令**（已写死在 `inference_demo.py`）：
```bash
python scripts/inference_demo.py --image your.jpg \
  --weights runs/exp3_yolov8m/weights/best.pt
```

切换到次优模型：
```bash
python scripts/inference_demo.py --image your.jpg \
  --weights runs/exp2_yolov8s/weights/best.pt
```

## 🌐 Streamlit Web UI（毕设答辩 / 教学演示）

一行命令启动浏览器交互式应用：

```bash
pip install -r requirements_streamlit.txt
streamlit run app.py
# → http://localhost:8501
```

| 页面 | 功能 | 输入 |
|------|------|------|
| 🏠 首页 | 项目指标 / 实验对比 / 功能导航 | — |
| 🖼️ 单图检测 | 上传 1 张图，秒级返回 | jpg/png/webp |
| 📁 批量检测 | 上传多张图，ZIP 打包下载 | 多图 |
| 🎬 视频检测 | 上传视频，输出标注视频 | mp4/avi/mov |
| 📡 实时流 | HTTP(S)/RTSP/RTMP 链接 + 浏览器摄像头 | URL / WebRTC |

**设计要点**（教学展示加分项）：
- 硬黑黄配色（工地安全帽主题）
- 置信度颜色编码（绿/橙/红）
- 实测速度显示（ms + FPS）
- 一键示例图、ZIP 批量下载、Docker 部署

详细使用手册与答辩话术：[`STREAMLIT_GUIDE.md`](./STREAMLIT_GUIDE.md)

## 🔧 硬件需求

| 模式 | 要求 |
|------|------|
| **训练** | NVIDIA GPU（>= 4GB 显存，建议 RTX 3060+）|
| **训练（云平台）** | 见 [GUIDE 第 3.9 节](./GUIDE.md) |
| **推理（CPU）** | 任意电脑，ONNX 加速 |

## 📁 项目结构

```
HardHatWorkers/
├── README.md                  ← 项目首页
├── GUIDE.md                   ← 📚 主教程
├── DEPLOY_TO_GITEE.md         ← Git 上传教程（复用）
├── YOLOV8_PROJECT_STARTER.md  ← 新数据集项目启动模板（复用）
├── data.yaml                  ← 数据集配置
├── data_local.yaml            ← 自动生成（绝对路径版本）
├── requirements.txt
├── configs/                   ← 6 个实验 YAML 配置
├── scripts/                   ← 训练/评估/推理脚本
├── notebooks/                 ← Jupyter 版（可选）
├── train/ valid/ test/        ← 数据集
└── runs/                      ← 训练输出
```

## 🆚 与蘑菇项目的对比

| 维度 | 蘑菇 | HardHatWorkers |
|------|------|----------------|
| 类别数 | 2 | **1** |
| 训练集 | 41 | **4916**（120×）|
| 总数 | 51 | **7035**（138×）|
| 难度 | 数据少，易过拟合 | 数据多，可上大模型 |
| 实验数 | 5 | **6**（增加少增强 vs 强增强对比）|

## 📦 数据集

来源：https://universe.roboflow.com/joseph-nelson/hard-hat-workers

- 许可证：Public Domain
- 原数据集有 75/25 train-test split
- 本数据集（v14-raw_headclassonly）只保留 "head" 类

## 🙏 致谢

- 数据集：[Roboflow Universe](https://universe.roboflow.com/joseph-nelson/hard-hat-workers)
- 算法：[Ultralytics YOLOv8](https://github.com/ultralytics/ultralytics)
- 项目模板：[NorthAmericanMushrooms](../NorthAmericanMushrooms)

## 📄 License

Public Domain (data) + MIT (code)