做安全帽检测的练手项目很多,但大多数只给一个 train.py 和一个 detect.py,真正把它做成「能点、能存、能看」的桌面软件的资料并不多。这篇文章按工程真实的文件顺序往下拆:先讲清楚这个任务到底难在哪、方案为什么这么分层,再把 YOLOv8 的网络结构与损失讲透,然后是数据集组织、训练超参、训练日志里那条曲线到底说明了什么,接着逐段读核心代码,最后给出部署步骤、常见报错排查表和一份老实的效果分析。读完你应该能独立复现这套流程,也能判断别人博客里那些「准确率 98%」到底靠不靠谱。
一、项目背景
施工现场的安全帽佩戴检查,本质是一个双类别检测问题:既要找到「人」,也要判断「人头上有没有安全帽」。注意这里不是分类任务——分类只能回答「这张图里有没有人没戴帽子」,一旦画面里有五个人、三个戴了、两个没戴,分类就彻底失效。检测才能给出「哪一个人没戴、在画面哪个位置」,这也是后续要输出坐标、要联动报警、要给巡检留证据的前提。
这个项目把它落成一套桌面工具:
- 输入:单张图片、图片文件夹、视频文件、USB 摄像头
- 输出:带框的结果图/结果视频、逐目标的类别/置信度/坐标表格
- 交互:下拉框选中某个目标后,右侧面板回填它的具体坐标与置信度
界面标题就是「基于Yolov8安全帽检测与识别系统」,检测类别只有两类:
| 0 | hat | 安全帽 |
| 1 | person | 人 |
从业务角度看,这两个类别其实是配套关系:只检测「人」,你不知道他戴没戴;只检测「安全帽」,画面里没人时你无法判断是「没人」还是「有人没戴」。所以正确用法是把 person 框和 hat 框做空间比对——如果某个 person 框的头部区域内不存在 hat 框,就判定为未佩戴。这个比对逻辑工程里没有实现(属于功能缺口),但它恰恰是这类系统最有价值的延伸方向,后面「可优化方向」里会展开。
坑点提醒 1:Config.py 里又把 0 类写成 helmet,和 data.yaml 的 hat 不一致。界面显示统一用 CH_names = ['安全帽', '人'],所以不影响使用,但你重新训练后一定要把三处(data.yaml 的 names、Config.names、Config.CH_names)对齐,否则 yaml 里改类名、界面还在按旧索引取中文名,就会出现「检测出 person 却显示成安全帽」的经典错位。
二、整体技术方案
整个工程可以分成三层,职责非常清晰:
| 模型层 | train.py、yolov8n.pt、models/best.pt | 训练与权重管理,推理统一走 Ultralytics 的 YOLO.predict |
| 推理/工具层 | MainProgram.py、detect_tools.py | 图片/视频/摄像头统一调度,画框、中文渲染、坐标转换、视频写出 |
| 界面层 | UIProgram/UiMain.py、style.css、QssLoader.py | Qt Designer 生成的界面 + QSS 皮肤 + 信号槽绑定 |
几个关键设计选择,都是踩过坑之后才会这么写的:
先看一张这个工程的真实输出,后面所有的代码都是为了复现这张图:

图 9 单图检测效果 1
以上为工程 save_data 目录中保存的实际检测结果(由 MainProgram.py 的图片检测流程输出,带类别与置信度标签)。
三、算法原理:YOLOv8 是怎么把"找框"和"分类"一次做完的
很多人会用 model.train(),但说不清 backbone 里到底发生了什么。这一节把与本项目直接相关的部分讲清楚,不涉及论文里那些与本任务无关的消融细节。
3.1 整体结构:Backbone + Neck + Head
YOLOv8 是典型的单阶段(one-stage)、Anchor-Free 检测器,一次前向就同时输出「框的位置」和「框的类别」,不像 Faster R-CNN 那样先出候选区域再逐个分类,所以延迟低、适合视频与摄像头这种连续推理场景。
- Backbone(主干):由若干 Conv 与 C2f 模块堆叠,再加一个 SPPF。C2f 是 YOLOv8 相对 YOLOv5 的主要改动之一:它在跨层连接上做了更充分的分支与拼接,让梯度流动更顺、特征复用更充分;SPPF 用串联的多个最大池化等效扩大感受野,代价远低于大核卷积。这两个模块共同决定了「特征提得准不准」。
- Neck(颈部):PAN-FPN 结构,自顶向下传语义、自底向上传定位细节。对安全帽这种「小目标 + 密集遮挡」的场景,Neck 里的高分辨率支路尤其关键——安全帽在远景图里可能只有 20×15 像素,全靠 P3 这类浅层高分辨率特征图才抓得住。
- Head(头部):解耦头(decoupled head),分类分支和回归分支分成两条独立的小卷积通路,各自学各自的,避免「分类与定位目标不一致」的相互干扰。输出是 anchor-free 的,直接回归到网格中心到框边的距离,再用 DFL(Distribution Focal Loss) 把距离建模成一个离散分布取期望,这样边界回归更平滑,对小目标的亚像素级偏差更友好。
3.2 损失函数:三个部分各管一件事
训练时总损失由三项加权构成,results.csv 里也正好对应三列,读日志时必须分清楚:
| 框回归损失 | train/box_loss、val/box_loss | 预测框与真值框的位置偏差(CIoU 一类) | 一直高 → 定位学不动,检查标注框是否错位/归一化错误 |
| 分类损失 | train/cls_loss、val/cls_loss | 类别判对没有(BCE) | 高且不降 → 类名映射错、类别不平衡 |
| 分布焦点损失 | train/dfl_loss、val/dfl_loss | 边界距离分布的精细程度 | 高 → 小目标多、边界模糊 |
理解这三项的意义在于:当你的 mAP 卡住不动时,先看是哪一项在拖后腿,而不是盲目加轮数。本项目的日志里 train/box_loss 从 1.5328 一路降到 1.255,而 val/box_loss 在 1.38~1.47 之间反复横跳,这个「训练降、验证不降」的剪刀差就是典型的轻微过拟合信号,后面第六节会用真实数字展开。
3.3 推理后处理:置信度阈值 + NMS
模型原始输出是成千上万个候选框,真正变成我们能看到的几个框,靠两步:
另外,输入图会先经过 letterbox 缩放到 imgsz=640(保持长宽比、灰边填充),推理完再把框坐标反向映射回原图尺寸。这一层在工程里由 results.plot() 自动完成,不需要手写,但你要知道框坐标为什么和原图尺寸对得上。
四、数据集构建与标注细节
数据集放在 datasets/helmetData,标准 YOLO 结构(图片与同名 txt 标签分目录):
datasets/helmetData/
├── data.yaml
├── train/{images, labels}
├── valid/{images, labels}
└── test/{images, labels}
实际规模(逐文件统计):
| train | 6026 | 6017 |
| valid | 763 | 762 |
| test | 792 | 792 |
| 合计 | 7581 | 7571 |
train/valid 里有少量「有图无标签」的样本(train 差 9、valid 差 1),这通常是负样本(画面里既没帽子也没人),YOLO 允许这种空标签文件缺失或为空,属于正常现象,不要手贱去补。
data.yaml 原文:
train: F:\\Mlwork\\YOLOv8hat-helmet\\datasets\\helmetData\\train
val: F:\\Mlwork\\YOLOv8hat-helmet\\datasets\\helmetData\\valid
test: F:\\Mlwork\\YOLOv8hat-helmet\\datasets\\helmetData\\test
nc: 2
names: ['hat', 'person']
两个必须注意的点:
- 绝对路径:这是原作者本机路径,你搬到自己机器上必须改,否则一启动训练就报 Dataset not found。建议改成相对 path + train/val 组合,可移植性更好。
- 文档滞后:项目里的 程序运行说明文档.txt 在「模型训练」章节还写着另一个项目 FireSmokeData 的示例路径,那是作者复制模板时漏改的。以 data.yaml 为准。
4.1 标注格式与坐标换算
YOLO 的标签是「一行一个目标」,格式为 class cx cy w h,后四个都是相对图像宽高的归一化值(0~1)。这种写法的好处是标签与分辨率无关,图片随便缩放都不用重标;坏处是人眼不可读,画图验证时必须换算。
工程在 detect_tools.py 里就内置了这一对互逆函数,是排查标注问题最实用的工具:
def yolo_to_location(w, h, yolo_data):
# yolo文件转两点坐标,注意画图坐标要转换成int格式
x_, y_, w_, h_ = yolo_data
x1 = int(w * x_ – 0.5 * w * w_)
x2 = int(w * x_ + 0.5 * w * w_)
y1 = int(h * y_ – 0.5 * h * h_)
y2 = int(h * y_ + 0.5 * h * h_)
return [x1, y1, x2, y2]
def location_to_yolo(w, h, locations):
x1, y1, x2, y2 = locations
x_ = float('%.5f' % ((x1 + x2) / 2 / w))
y_ = float('%.5f' % ((y1 + y2) / 2 / h))
w_ = float('%.5f' % ((x2 – x1) / w))
h_ = float('%.5f' % ((y2 – y1) / h))
return [x_, y_, w_, h_]
配套的 draw_yolo_data(img_path, yolo_file_path) 会把某张图的 txt 标注画成红框并 imshow,标注错位、漏标、类标反了这三类问题,用它跑一遍 20 张就能发现。
坑点提醒 2:location_to_yolo 保留 5 位小数是够用的(1/100000 的图像宽度,远小于视觉可辨差异),但千万别自己改成 2 位——归一化值 0.37 与 0.375 差的是整张图 0.5% 的宽度,密集小目标场景会直接把框推到隔壁目标身上。
4.2 数据分布与增强策略
训练前必看的一张图是 Ultralytics 自动生成的数据集统计图,它把标注框的尺寸分布、中心点分布、长宽比分布画在一起,能一次性暴露「小目标占比多少」「框都挤在画面中间」这类问题:

图 2 数据集标注分布统计
从这张图可以直接读出两件事:一是标注框尺寸分布较宽(说明数据里既有近景大目标也有远景小目标),二是中心点分布集中在画面中部(符合工地上「人站在画面中」的拍摄习惯)。这类分布如果严重偏离训练场景,就该补数据而不是调超参。
YOLOv8 默认开启的训练增强里,对本项目影响最大的是 Mosaic:把 4 张图随机缩放、裁剪、拼接成一张,相当于在不增加显存的前提下把 batch 内样本数翻了 4 倍,还顺带造出大量「小目标 + 新背景组合」。工程 args.yaml 里 mosaic=1.0(始终开启)、close_mosaic=10(最后 10 轮关闭)。最后 10 轮关掉 Mosaic 是必要的——Mosaic 造出来的拼接图与真实场景分布不一致,关掉它让模型在真实分布上收尾,指标通常会有一次明显抬升。

图 3 Mosaic 数据增强后的训练批次样本
上图是训练批次第 0 批的真实样本,可以看到四图拼接的边界、灰边填充,以及部分目标被裁掉只剩半个框——这些都是 Mosaic 的正常产物,不是标注错误。
五、训练超参与训练环境
训练脚本非常短,但每一行参数都值得逐项说:
#coding:utf-8
from ultralytics import YOLO
model = YOLO("yolov8n.pt") # 加载预训练模型
if __name__ == '__main__':
results = model.train(data='datasets/helmetData/data.yaml',
epochs=150, batch=4, patience=300)
# 将模型转为onnx格式
# success = model.export(format='onnx')
- yolov8n.pt:n 是最小的 YOLOv8,参数量小、推理快,适合桌面端 + 实时视频这种对延迟敏感的场景。工程内没有记录具体参数量与 FLOPs(待补充)。
- epochs=150、batch=4:batch 只有 4,说明训练机器显存很紧张(4GB 级别的卡)。显存够的话建议 16~32,训练更稳。
- patience=300:早停耐心值设得比总轮数还大,等于早停实际永远不会触发,一定会跑满 150 轮。如果你希望早停生效,patience 要明显小于 epochs。
- if __name__ == '__main__'::Windows 上 DataLoader 多进程必须加这一句,否则容易报 freeze_support 相关错误。
更完整的超参不在 train.py 里,而在训练输出目录自动留存的 args.yaml。工程里保留了三轮训练的痕迹,results.csv 实际存在于 train2、train4、train5。把两份 args.yaml 摊开对比,能看出作者两次训练的思路变化:
| model | yolov8n.pt | yolov8n.pt | n 尺度不变 |
| data | datasets/helmetData/data.yaml | 同左 | 同一份数据 |
| epochs | 200 | 150 | 把轮数砍下来了 |
| batch | 32 | 4 | 显存受限后的妥协 |
| patience | 50 | 300 | train2 是真的会早停,train4 等于关掉早停 |
| workers | 32 | 8 | 进程数同步下调 |
| imgsz | 640 | 640 | 默认分辨率 |
| optimizer | auto | auto | 由框架自动选(SGD/AdamW 择一并调 lr) |
| lr0 | 0.01 | 0.01 | 初始学习率 |
| warmup_epochs | 3.0 | 3.0 | 前三轮预热,防早期梯度爆炸 |
| close_mosaic | 10 | 10 | 末 10 轮关 Mosaic |
| mosaic / fliplr | 1.0 / 0.5 | 1.0 / 0.5 | 拼接 + 水平翻转 |
| degrees / translate / scale | 0.0 / 0.1 / 0.5 | 0.0 / 0.1 / 0.5 | 不旋转,平移 10%,缩放 50% |
| mixup | 0.0 | 0.0 | 未启用 |
| device | null | null | 自动选择 |
| cache | false | false | 未缓存到内存 |
一个很容易被忽略的细节:train.py 里的参数和 train4 完全一致,而 train2 的 epochs=200 / batch=32 / patience=50 显然来自另一次手动传入。所以你在博客或论文里写「本系统训练参数为 epochs=150, batch=4」时,说的其实只是 train.py 当前版本 + train4 那一次;train2 那次是用更大的 batch 跑的,两者不能混着引用。
训练环境方面,工程没有留存环境快照或 nvidia-smi 输出,因此显卡型号、CUDA 版本、单轮耗时、总训练时长均(待补充)。从 batch=4 与 workers=8 这组偏保守的配置反推,训练机器显存大概率在 4~6 GB 区间,但这只是推断,不能当结论写进文档。
坑点提醒 3:requirements.txt 里列了 31 项依赖,但 pillow 没有写进去,而主程序在处理检测结果时会用到 PIL;同时 torch==1.9.0 与 ultralytics==8.0.199 这个组合偏老,新装环境时建议直接装新版本 torch,别按 requirements 硬装——旧版 torch 在新驱动上经常报 sm_xx is not compatible。装完先跑一句 from ultralytics import YOLO 验证,比训练到一半才崩要省时间。
六、训练过程与指标分析
先把三次训练的真实记录摆出来(全部取自 runs/detect/*/results.csv 的末行与最佳行):
| train2 | epochs=200, batch=32 | 到第 177 轮 | 第 162 轮 | 0.90749 | 0.87476 | 0.93273 | 0.60291 |
| train4 | epochs=150, batch=4 | 跑满 150 轮 | 第 82 轮 | 0.91713 | 0.85287 | 0.92972 | 0.60259 |
| train5 | epochs=150, batch=4 | 第 3 轮中断 | 第 2 轮 | 0.83633 | 0.73238 | 0.80050 | 0.47195 |
这张表是训练日志的原始记录,统一标注为「对应轮次训练日志记录值」。models/best.pt 到底来自哪一轮、在验证集上的真实精度是多少,工程里没有标注,属于信息缺口。要在论文或博客里写准确率,正确做法是拿 models/best.pt 重新跑一次 model.val() 取值,而不是从 csv 里挑一个最好看的数字。
下面这条曲线是 train2 全程 177 轮的可视化,三行分别是 box/cls/dfl 损失,两列是训练集与验证集:

图 1 YOLOv8 安全帽检测训练曲线(train2,共 177 轮)
光看图看不出精确数值,所以把关键轮次从 csv 里抽出来对齐看:
| 1 | 0.66489 | — | — | — | — |
| 10 | 0.85001 | 0.87199 | 0.79009 | 1.5328 | 1.4758 |
| 25 | 0.89816 | 0.89599 | 0.83095 | 1.4514 | 1.4230 |
| 50 | 0.91088 | 0.89627 | 0.83393 | 1.4087 | 1.3982 |
| 75 | 0.92608 | 0.90903 | 0.85711 | 1.3861 | 1.3842 |
| 100 | 0.92994 | 0.89605 | 0.87355 | 1.3426 | 1.3852 |
| 125 | 0.93129 | 0.89625 | 0.87581 | 1.3147 | 1.3834 |
| 150 | 0.93066 | 0.89981 | 0.87864 | 1.2883 | 1.3908 |
| 175 | 0.93214 | 0.90906 | 0.87593 | 1.2550 | 1.3935 |
从这张表能读出四个结论,都是数字直接支撑的:
验证集的真值与模型预测放在一起对比,能直观看出漏检与误检发生在什么位置:

图 4 验证集标注真值

图 5 同一批验证图的模型预测结果
对比这两张图(同一批验证图、左真值右预测),可以看到小目标和遮挡目标的差异最明显——这也是 recall 上不去的主要原因。
混淆矩阵给出了更细的粒度:不只是「对了几成」,而是「错成了什么」:

图 6 混淆矩阵
两类别场景的混淆矩阵只有 3×3(hat / person / background),读法很简单:对角线是判对的,右上三角是「把 hat 判成 person」这类类别互换错误,最后一列是「真实存在但没检出来」,最后一行是「凭空多检出来的框」。安全帽与人的混判在理论上不该出现(两者尺寸、位置差异巨大),如果这两格数值偏高,第一嫌疑就是类名映射错位——也就是第一节那个 hat vs helmet 的坑。
PR 曲线展示的是不同置信度阈值下 Precision 与 Recall 的权衡,曲线下面积(AUC)就是 AP;F1 曲线则是把两者合成一个指标,峰值点对应「综合最优的置信度阈值」:

图 7 PR 曲线

图 8 F1 值随置信度阈值变化
这两张图的实际用法:F1 曲线的峰值横坐标,就是这套模型在部署时最该设置的 conf 值。工程里用的是库默认 0.25,如果你希望现场误报更少,就往峰值右侧挪;希望不漏人,就往左挪。这是把「指标」翻译成「产品决策」的关键一步,比在博客里写一句「mAP 0.93」有用得多。
七、核心代码逐段解读
7.1 启动与初始化:把贵的东西放在最前面
class MainWindow(QMainWindow):
def __init__(self):
super().__init__()
self.ui = Ui_MainWindow()
self.ui.setupUi(self)
self.initMain()
self.signalconnect()
__init__ 只做三件事:搭界面、初始化资源、绑信号。顺序不能换——initMain() 里要操作 self.ui 的表格控件,必须等 setupUi 之后。
def initMain(self):
self.show_width = 770
self.show_height = 480
self.org_path = None
self.is_camera_open = False
self.cap = None
self.device = 0 if torch.cuda.is_available() else 'cpu'
self.model = YOLO(Config.model_path, task='detect')
self.model(np.zeros((48, 48, 3))) # 预先加载推理模型
self.fontC = ImageFont.truetype("Font/platech.ttf", 25, 0)
self.ui.tableWidget.verticalHeader().setSectionResizeMode(QHeaderView.Fixed)
self.ui.tableWidget.verticalHeader().setDefaultSectionSize(40)
self.ui.tableWidget.setColumnWidth(0, 80)
self.ui.tableWidget.setColumnWidth(1, 200)
self.ui.tableWidget.setColumnWidth(2, 150)
self.ui.tableWidget.setColumnWidth(3, 90)
self.ui.tableWidget.setColumnWidth(4, 230)
self.ui.tableWidget.setSelectionBehavior(QAbstractItemView.SelectRows)
self.ui.tableWidget.verticalHeader().setVisible(False)
self.ui.tableWidget.setAlternatingRowColors(True)
- self.model(np.zeros((48,48,3))) 就是前面说的空图预热。注意这行不是「多余的推理」——它触发了 Ultralytics 内部的模型 fuse、设备搬运与首次前向,省掉的就是用户第一次点按钮时那两三秒。
- ImageFont.truetype("Font/platech.ttf", 25, 0) 用相对路径读字体,所以必须在项目根目录启动程序,否则 drawRectBox 会抛 OSError: cannot open resource。这是新手最常见的启动失败原因之一。
- 表格那七行是把 Qt 表格「调成人能看的样子」的标准配方:行高 40 不挤、隐藏左侧行号栏、整行选中而不是单格选中、奇偶行交替配色便于横向读。后五项(列宽)与业务字段一一对应,改动列顺序时必须同步改这里。
7.2 信号绑定:一处集中,便于维护
def signalconnect(self):
self.ui.PicBtn.clicked.connect(self.open_img) # 单图
self.ui.FilesBtn.clicked.connect(self.detact_batch_imgs) # 文件夹批量
self.ui.VideoBtn.clicked.connect(self.vedio_show) # 视频
self.ui.CapBtn.clicked.connect(self.camera_show) # 摄像头(开关式)
self.ui.SaveBtn.clicked.connect(self.save_detect_video) # 保存结果
self.ui.ExitBtn.clicked.connect(QCoreApplication.quit) # 退出
self.ui.comboBox.activated.connect(self.combox_change) # 目标下拉选择
把所有 connect 集中在一个方法里,好处是「界面有哪些能力」可以一眼看完,不用在几千行里翻。这也是 Qt 项目的推荐写法。
7.3 单图推理:从路径到像素,再到表格
def open_img(self):
if self.cap:
self.video_stop()
self.is_camera_open = False
self.ui.CaplineEdit.setText('摄像头未开启')
file_path, _ = QFileDialog.getOpenFileName(None, '打开图片', './',
"Image files (*.jpg *.jepg *.png)")
if file_path:
self.ui.comboBox.setDisabled(False)
self.org_path = file_path
self.org_img = tools.img_cvread(self.org_path)
t1 = time.time()
self.results = self.model(self.org_path)[0]
t2 = time.time()
self.ui.time_lb.setText('{:.3f} s'.format(t2 – t1))
location_list = self.results.boxes.xyxy.tolist()
self.location_list = [list(map(int, e)) for e in location_list]
cls_list = self.results.boxes.cls.tolist()
self.cls_list = [int(i) for i in cls_list]
conf_list = self.results.boxes.conf.tolist()
self.conf_list = ['%.2f %%' % (each * 100) for each in self.conf_list]
now_img = self.results.plot()
self.draw_img = now_img
self.img_width, self.img_height = self.get_resize_size(now_img)
resize_cvimg = cv2.resize(now_img, (self.img_width, self.img_height))
pix_img = tools.cvimg_to_qpiximg(resize_cvimg)
self.ui.label_show.setPixmap(pix_img)
self.ui.label_show.setAlignment(Qt.AlignCenter)
self.ui.PiclineEdit.setText(self.org_path)
self.tabel_info_show(self.location_list, self.cls_list,
self.conf_list, path=self.org_path)
这段是全工程信息密度最高的地方,值得逐句拆:
- 先刹车再开新任务:进入方法第一件事是判断摄像头是否开着,开着就先 video_stop()。否则摄像头线程继续往同一个 label_show 刷帧,你刚显示的检测图会在几十毫秒后被摄像头画面覆盖,表现为「点了检测但图闪一下就没了」。
- 计时只包住推理:t1 放在模型调用前、t2 紧跟在后面,所以界面上的「用时」是纯推理耗时,不含读盘、画框、缩放、刷新 QT 控件。这个口径要说清楚,否则别人拿它当端到端延迟会误判。
- 三类结果分开取:坐标 boxes.xyxy(左上+右下,绝对值像素)、类别 boxes.cls(float,要转 int 当索引)、置信度 boxes.conf(0~1,乘 100 再格式化成百分比)。三者是按同一顺序排列的,索引对齐,所以后面 draw_rect_and_tabel 才能按下标把「框、类、分」拼成一行。
- results.plot() 是省事但不灵活的选择:它直接把框、标签画好返回 BGR 图,代价是你没法自定义颜色、字体大小、标签位置。想完全控制样式就自己用 detect_tools.drawRectBox 逐框画——工程里两套都留了,draw_rect_and_tabel 走的是自定义路径。
- 显示前必须缩放:get_resize_size() 按 770×480 的显示区做等比缩放,返回缩放后的宽高,再 cv2.resize + 转 QPixmap。不缩放直接 setPixmap,大图会把整个布局撑变形。
- img_cvread 而不是 cv2.imread:前者用 np.fromfile + cv2.imdecode,绕开 OpenCV 对中文路径的编码问题。凡是界面允许用户自己选文件的项目,这一步都不能省。
7.4 视频与摄像头:用 QTimer 代替 while
def vedio_show(self):
if self.is_camera_open:
self.is_camera_open = False
self.ui.CaplineEdit.setText('摄像头未开启')
video_path = self.get_video_path()
if not video_path:
return None
self.cap = cv2.VideoCapture(video_path)
self.video_start()
self.ui.comboBox.setDisabled(True)
def camera_show(self):
self.is_camera_open = not self.is_camera_open
if self.is_camera_open:
self.ui.CaplineEdit.setText('摄像头开启')
self.cap = cv2.VideoCapture(0)
self.video_start()
self.ui.comboBox.setDisabled(True)
else:
self.ui.CaplineEdit.setText('摄像头未开启')
if self.cap:
self.cap.release()
cv2.destroyAllWindows()
self.ui.label_show.clear()
video_start() 里起的是 QTimer,每次超时读一帧、推理一帧、刷一次界面。这是 PyQt 做实时画面的标准套路:绝不能在主线程写 while cap.isOpened(),那个循环会把 Qt 事件循环饿死,窗口直接「未响应」。摄像头按钮做成开关式(is_camera_open = not is_camera_open),且打开前先停掉正在播的视频,避免两个来源抢同一个画面控件。
7.5 保存视频:为什么要开线程二次推理
def save_detect_video(self):
if self.cap is None and not self.org_path:
QMessageBox.about(self, '提示', '当前没有可保存信息,请先打开图片或视频!')
return
if self.is_camera_open:
QMessageBox.about(self, '提示', '摄像头视频无法保存!')
return
if self.cap:
res = QMessageBox.question(self, '提示',
'保存视频检测结果可能需要较长时间,请确认是否继续保存?',
QMessageBox.Yes | QMessageBox.No)
if res == QMessageBox.Yes:
self.video_stop()
com_text = self.ui.comboBox.currentText()
self.btn2Thread_object = btn2Thread(self.org_path, self.model, com_text)
self.btn2Thread_object.start()
self.btn2Thread_object.update_ui_signal.connect(self.update_process_bar)
btn2Thread 是一个 QThread 子类,run() 里重新 cv2.VideoCapture 打开源视频,逐帧 model(frame)[0] → results.plot() → out.write(frame),每帧 emit(cur_num, total) 更新进度条。写文件用 fourcc = cv2.VideoWriter_fourcc(*'XVID'),文件名规则是 原名_detect_result.avi。
这个设计有一个必须承认的代价:保存一次视频 = 推理两遍。第一遍是播放时的实时预览,第二遍是保存时的重跑。为什么不用「播放时顺手存帧」?因为播放用的是 QTimer(1ms),实际刷新率受推理速度制约,掉帧是常态,顺手存出来的视频会卡顿、时长短于原视频。重跑一遍虽然慢,但能保证帧率与源视频一致、帧数完整。这是「正确性优先于速度」的取舍,也是本工程最值得学的一处工程判断。
7.6 工具层:三个必须自己写的函数
- drawRectBox(image, rect, addText, fontC, color):先 cv2.rectangle 画框,再在框上方画一个实心背景条(thickness=-1)当标签底色,最后 Image.fromarray → ImageDraw.text → np.array 转回,实现中文标签。背景条宽度硬编码 rect[0] + 60,标签长于 4 个汉字就会溢出,属于已知小瑕疵。
- cvimg_to_qpiximg(cvimg):cv2.cvtColor(BGR2RGB) → 构造 QImage(注意 step 参数要传 width * depth,否则图像会斜切)→ QPixmap。这个函数是 OpenCV 与 Qt 之间的唯一桥,BGR/RGB 顺序错了就是蓝脸红人。
- insert_rows(path, lines, header):把检测结果追加写进 csv,文件不存在时先写表头,每行自动加自增序号。这是「检测留痕」能力的实现,比只存图片更有价值——半年后要查某天检出了多少未戴帽,靠的就是这个 csv。
八、系统功能与界面实现
界面上半区是「文件导入」和「检测结果」两块,下半区是「检测结果与位置信息」表格 + 右侧信息面板(目标位置 / 目标数目 / 目标选择 / 用时 / 置信度),右下角「保存」「退出」。
功能对应关系:
| 单图检测 | open_img() | 推理前后取 time.time() 差值,格式化 '{:.3f} s' 显示在「用时」 |
| 文件夹批量 | detact_batch_imgs() | 遍历目录逐张推理,结果命名为 xxx_detect_result.jpg |
| 视频检测 | vedio_show() | cv2.VideoCapture + QTimer 逐帧读取,替代 while 循环,避免阻塞 UI |
| 摄像头 | camera_show() | 开关式设计:打开时若已有视频在播先 video_stop(),再 cv2.VideoCapture(0) |
| 结果表格 | tabel_info_show() | 五列:序号 / 文件路径 / 类别 / 置信度 / 坐标位置,自动滚到最后一行 |
| 目标明细 | combox_change() | 下拉框默认「全部」,选中某一目标后回填 xmin/ymin/xmax/ymax、类别、置信度 |
| 结果保存 | save_detect_video() | 图片直接 cv2.imwrite 到 save_data;视频交给 btn2Thread 线程重跑一遍并写 xxx_detect_result.avi(XVID 编码),同时弹出 ProgressBar 可取消 |
combox_change() 这个交互值得单独说:它把「表格里的一行」变成「画面上某一个框」,实现方式是按下标从 self.location_list / self.cls_list / self.conf_list 里同步取值。三个列表必须严格同长同序,一旦有一处过滤掉了背景框而另一处没过滤,就会出现「下拉框选第 3 个,画面上框的是第 4 个」的错位。这也是为什么 results.plot() 和自定义绘图两条路径不能混用——它们的框集合不一样。
九、系统部署与运行步骤
工程提供了一键安装脚本,环境配置就三步:
# 1) 建 Python 3.9 环境
conda create -n py39 python=3.9
conda activate py39
# 2) 进入项目根目录后安装依赖(二选一)
python installPackages.py
# 或
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
# 3) 启动(必须在项目根目录,否则找不到 Font/ 与 models/)
python MainProgram.py
关键依赖版本(requirements.txt 共 31 项,节选):
| ultralytics | 8.0.199 |
| torch | 1.9.0 |
| opencv-python | 4.8.1.78 |
| PyQt5 | 5.15.2 |
| pyqt5-tools | 5.15.2.3.1 |
| matplotlib | 3.8.0 |
| numpy | 1.26.1 |
完整的迁移清单(换一台机器照这个顺序做,基本不会卡):
十、常见报错与排查
部署阶段最容易卡住的几个点(都是这个工程里真实存在的):
坑点提醒 4:models/best.pt 与 runs/detect/train2、train4、train5/weights/best.pt 的字节数完全一致(均为 6240025 字节)。这说明 models/ 下那份是复制而来的副本,但从文件本身看不出是哪一次训练的产物。三次训练的最佳 mAP@0.5 分别是 0.93273 / 0.92972 / 0.80050,差别不小,写论文时必须先跑一次 model.val() 反查,不能默认 models/best.pt 就是最好的那次。
十一、检测效果展示与分析
单目标场景下,模型对「人 + 头顶安全帽」的组合框得很紧,标签与置信度也清晰:

图 10 单图检测效果 2
多人场景才是真实考验。下图同一画面里出现多个工人,模型的取舍很能说明问题:

图 11 多人场景检测效果
从这三张实际输出可以归纳出几条规律(都是肉眼可核对的,不含推断性的精度声明):
- 近景大目标几乎不漏:占画面 1/4 以上的人与帽,框都稳定,置信度也高。
- 远景小目标是主要短板:站在画面深处的人,帽子的像素面积小,偶尔只框到人不框到帽,或者帽子框偏小。这与 mAP@0.5-0.95 只有 0.60 左右是同一个问题的两种表现——阈值 0.5 时算对,框得不够紧就掉到 0.5 以下。
- 密集遮挡会合并框:人挤人时 NMS 更容易把相邻两个人抑制成一个框,这是后处理参数问题,不是模型没学到。
- 逆光与夜间未覆盖:工程自带测试图都是白天场景,夜间/逆光效果无法从现有材料判断(待补充实测)。
一个必须强调的认知:这些截图是「挑选过的成功案例」,不能反推整体精度。要给出可信的效果分析,得在验证集 763 张上统计漏检/误检分布,而工程里没有留存这类统计。这也是第八节「要点总结」里反复说的那句——日志指标 ≠ 模型指标 ≠ 真实场景表现,三者要分开引用。
十二、可优化方向
按「投入产出比」从高到低排,给后续接手的人一份施工图:
十三、目录结构
YOLOv8hat-helmet/
├── MainProgram.py # 主程序:界面逻辑 + 检测调度 + 结果保存
├── Config.py # 模型路径 / 保存目录 / 中英文类名
├── train.py # YOLOv8n 训练脚本
├── detect_tools.py # 画框、中文渲染、坐标转换、视频写出
├── installPackages.py # 一键装依赖
├── requirements.txt # 31 项依赖
├── datasets/helmetData/ # 数据集(train/valid/test + data.yaml)
├── models/best.pt # 系统默认权重(约 5.95 MB)
├── UIProgram/ # 界面代码、QSS、图标资源
├── Font/platech.ttf # 中文绘制字体
├── TestFiles/ # 测试图片与测试视频
├── save_data/ # 检测结果输出目录
└── runs/detect/ # 训练输出(train2 / train4 / train5 保留有 results.csv 与 args.yaml)
十四、要点总结
网硕互联帮助中心




评论前必须登录!
注册