项目简介
本项目基于 YOLOv8 实现口罩佩戴状态检测，已从原 PyQt6 桌面程序扩展为本机 Web 系统。系统支持图片识别、视频识别、浏览器摄像头识别、检测历史、模型管理和训练指标查看。
Web 端采用本机单机部署方式，后端继续复用 Python 检测能力，前端通过浏览器访问，适合在 Windows 本机环境下直接使用。
功能模块
1. 登录 / 注册
-
保留本地账号登录与注册能力
-
账号数据保存在项目本地文件中
-
登录成功后进入 Web 后台
2. 图片识别
-
支持上传常见图片格式
-
调用当前 YOLO 模型完成识别
-
在网页画布中绘制检测框、类别和置信度
-
展示检测总数、平均置信度、最高置信度和类别分布
-
支持导出结果图和 CSV 明细
-
历史中只保存检测记录和统计信息，不保存原始图片
3. 视频识别
-
支持上传本地视频文件
-
支持按抽帧步长执行检测
-
后端以任务形式处理视频，前端展示处理进度
-
处理完成后展示结果视频、统计摘要和类别分布
-
历史中只保存检测记录和统计信息，不保存原始视频
4. 摄像头识别
-
浏览器直接调用本机摄像头
-
支持开始检测、暂停检测和截图
-
实时在网页端叠加识别框和检测统计
-
摄像头会话可归档为历史记录
5. 检测历史
-
使用 SQLite 保存检测历史
-
支持图片、视频、摄像头三类记录
-
支持关键词查询、详情查看、CSV 导出和清空历史
-
不保存原始上传图片和原始上传视频
6. 模型管理
-
默认加载
train_result/train/weights/best.pt -
支持发现项目内已有模型
-
支持上传并加载新的模型文件
-
支持调整
conf、iou、max_det -
图片、视频、摄像头共用同一套当前模型配置
7. 训练指标
-
读取
train_result/train/results.csv -
展示 Precision、Recall、mAP 等训练指标
-
读取
train_result/train/charts/下的训练图表 -
Web 端只查看训练结果，不在网页中启动训练
类别说明
本项目口罩检测为二分类任务：
| class_id | 类别名称 | 含义 |
|---|---|---|
| 0 | without_mask |
未佩戴口罩 |
| 1 | with_mask |
已佩戴口罩 |
说明：当前检测器已在 utils/detector.py 中对本项目二分类模型做统一类别顺序校正，避免模型元信息与实际识别语义不一致导致 Web 端显示反向。
技术栈
| 层次 | 技术 | 用途 |
|---|---|---|
| 检测模型 | ultralytics / YOLOv8 |
口罩目标检测 |
| Web 后端 | FastAPI |
登录、检测、模型、历史和指标接口 |
| Web 服务 | uvicorn |
本机 Web 服务启动 |
| 前端 | 原生 HTML / CSS / JavaScript | 单页后台界面 |
| 计算机视觉 | opencv-python |
图片、视频读写与绘制 |
| 数值计算 | numpy |
图像数据与统计处理 |
| 数据分析 | pandas |
训练日志读取 |
| 桌面端 | PyQt6 |
原桌面版界面保留 |
| 数据存储 | SQLite |
检测历史 |
| 配置文件 | PyYAML |
数据集配置生成 |
| 开发语言 | Python 3.9 | 项目运行环境 |
项目结构
c213/
├── web_main.py # Web 版启动入口
├── main.py # PyQt6 桌面版启动入口
├── login_window.py # 桌面版登录窗口
├── main_window.py # 桌面版主窗口
├── train.py # 模型训练入口
├── visualize.py # 训练图表生成入口
├── requirements.txt # 项目依赖
│
├── webapp/ # Web 版主体
│ ├── app.py # FastAPI 应用入口
│ ├── api/ # Web API 路由
│ │ ├── auth.py # 登录注册接口
│ │ ├── detect.py # 图片、视频、摄像头检测接口
│ │ ├── history.py # 历史记录接口
│ │ ├── metrics.py # 训练指标接口
│ │ ├── model.py # 模型管理接口
│ │ └── overview.py # 概览接口
│ ├── core/ # Web 核心配置与运行状态
│ ├── services/ # 业务服务层
│ └── static/ # 前端页面、样式和脚本
│
├── pages/ # PyQt6 桌面版页面
│ ├── image_page.py
│ ├── video_page.py
│ ├── camera_page.py
│ ├── history_page.py
│ ├── model_page.py
│ └── metrics_page.py
│
├── utils/ # 公共工具模块
│ ├── detector.py # 统一检测器，Web / 桌面共用
│ ├── db.py # SQLite 历史数据库
│ ├── data_prepare.py # 数据集划分与 data.yaml 生成
│ └── users.json # 本地账号数据
│
├── datasets/ # 原始图片与 YOLO 标注
├── train_result/ # 训练产物、模型、历史数据库和图表
│ ├── train/weights/best.pt # 默认检测模型
│ ├── train/results.csv # 训练日志
│ ├── train/charts/ # 训练图表
│ └── detection_history.db # 检测历史数据库
│
└── 数据集说明.md启动方式
Web 版
python web_main.py启动后浏览器访问：
http://127.0.0.1:8000桌面版
python main.py模型训练
python train.py训练结果保存到 train_result/train/，默认最优模型为 train_result/train/weights/best.pt。
训练图表生成
python visualize.py图表保存到 train_result/train/charts/。
路径与中文兼容说明
-
项目内部尽量使用
pathlib.Path和相对路径，便于项目移动位置后继续运行。 -
Windows 中文路径下，PyTorch 模型加载不能直接依赖底层 C++ 处理中文路径。
-
utils/detector.py已对模型加载做兼容处理：先通过 Python 原生open()读取模型，再写入 ASCII 临时路径供 YOLO 加载。 -
涉及目录创建时优先使用
Path.mkdir(parents=True, exist_ok=True)。
环境说明
-
Python 版本：3.9
-
推荐虚拟环境：
yolo -
系统环境：Windows 10 / 11
-
GPU：可选，使用 GPU 推理和训练速度更快
依赖见 requirements.txt。
注意事项
-
Web 版当前按本机单机使用设计。
-
Web 端摄像头由浏览器直接调用，需要允许浏览器摄像头权限。
-
Web 端不执行训练，只查看已有训练结果和管理模型。
-
检测历史只保存统计与明细，不保存上传的原始图片和原始视频。
-
修改模型或类别顺序后，需要重启 Web 服务让已加载模型重新生效。
作者信息
| 项目 | 详情 |
|---|---|
| 作者 | Jay |
| 定制联系 | vx：Jay8059 |
| 开发年份 | 2026 年 |
| 项目定位 | 基于 YOLOv8 的口罩佩戴检测 Web 系统 |
