Python+OpenCV+PyQt5人脸识别考勤签到系统源码实战与避坑指南

简介这是一套面向计算机相关专业学生与Python初学者的完整人脸识别考勤签到系统源码可直接用于课程设计、毕业设计或自学练手。项目以Python为主语言结合OpenCV实现人脸检测与识别采用Haar级联分类器完成人脸定位并借助LBPH等方法进行特征提取与匹配同时使用PyQt5搭建可视化操作界面涵盖签到、查询等交互功能。压缩包共44个文件包含12个py源码、16个pyc编译文件、10个xml分类器与界面配置、2个ui界面文件及说明文档整体约681KB结构清晰、便于按模块阅读。源码附带详细注释覆盖数据库操作、文件读写、时间处理与异常捕获等环节有助于理解从图像采集到考勤记录落库的完整链路。目前已有266人学习适合希望快速掌握计算机视觉与GUI开发实践的学习者参考。1. 从一份能跑起来的考勤源码说起PythonOpenCVPyQt5 到底解决了什么很多做课程设计或毕业设计的同学卡在的不是算法本身而是「人脸识别怎么和签到业务串起来」。你搜到的大多数 demo 只给你一段cv2.face.LBPHFaceRecognizer_create()的调用跑完控制台打印个名字就结束了没有界面、没有记录、没有异常处理交上去老师第一句就问「签到数据存哪了」。这份基于 PythonOpenCV 人脸识别的考勤签到系统源码把检测、识别、PyQt5 界面、签到记录落盘这几件事拼成了一条完整链路还带详细注释属于那种「下载下来改改就能当课设」的资源。它适合两类人一是刚学完 Python 语法、想找一个能同时练 OpenCV 和 PyQt5 的实战项目的新手二是需要快速交付一个带 GUI 的考勤系统原型、不想从零搭框架的从业者。下面我按「资源结构 → 环境搭建 → 核心模块 → 避坑 → 进阶」的顺序把这份源码拆开讲清楚。2. 拆开压缩包先看结构模块划分与依赖清单2.1 目录树里藏着什么拿到压缩包先别急着运行把目录结构过一遍能省掉后面一半的调试时间。这份源码的顶层是一个code包里面按职责拆成了几个文件我按功能归类给你看文件/目录职责是否要改MainWindow.py主窗口入口PyQt5 界面启动一般不改QtUI.pyUI 逻辑与信号槽绑定改界面时动CamShow.py摄像头画面显示与实时检测调摄像头时动Camo_open.py摄像头开启/关闭控制一般不改face_model.py人脸检测与识别核心换算法时动Functional_function.py签到业务逻辑、记录写入改业务时动upload.py人脸样本录入/上传录入流程相关data/Haar 级联分类器 XML 文件不动ui/.ui设计文件与生成代码用 Designer 改requirements.txt依赖清单按需改data目录里放了三个 Haar 级联文件haarcascade_frontalface_default.xml、haarcascade_frontalface_alt2.xml、haarcascade_eye_tree_eyeglasses.xml。前两个是人脸检测用的第三个是眼睛检测用的常用来做「检测到人脸后再定位眼睛」的二次校验降低误检。ui目录下同时有.ui源文件和生成的.py说明作者是用 Qt Designer 拖的界面改布局时改.ui再重新生成即可不用手写控件坐标。2.2 依赖清单与版本选择requirements.txt是环境复现的第一手依据。这类项目典型依赖是opencv-python、opencv-contrib-python、PyQt5、numpy、Pillow。这里有个关键点人脸识别用的cv2.face模块不在主包opencv-python里而在opencv-contrib-python里。很多人只装了前者运行时报module cv2 has no attribute face这就是血泪经验里最常见的一条。# 建议先建虚拟环境避免和系统里的包打架 python -m venv venv # Windows 激活 venv\Scripts\activate # macOS / Linux 激活 source venv/bin/activate # 安装依赖注意 contrib 包必须装 pip install opencv-python opencv-contrib-python PyQt5 numpy Pillow装完验证一下cv2.face是否可用import cv2 # 这行不报错说明 contrib 装对了 print(hasattr(cv2, face)) # 打印版本方便排查兼容问题 print(cv2.__version__)逻辑说明hasattr(cv2, face)返回True才说明人脸识别模块可用。参数上opencv-python和opencv-contrib-python版本要一致混装不同版本会出现cv2命名空间冲突表现为某些函数莫名找不到。如果项目里用了cv2.face.LBPHFaceRecognizer_create()那 contrib 是硬性依赖没有替代方案。提示PyQt5 在部分 Python 3.10 环境上装完可能缺QtWebEngine之类组件如果界面启动报 DLL 相关错误优先检查 Python 版本和 PyQt5 版本是否匹配别一上来就怀疑代码。3. 从摄像头到签到记录核心链路的实现与参数3.1 人脸检测Haar 级联怎么调才不飘face_model.py里做人脸检测的典型写法是加载 Haar 分类器再调detectMultiScale。这个函数的几个参数直接决定检测效果我把常用取值和含义列出来import cv2 # 加载级联分类器路径指向 data 目录下的 xml face_cascade cv2.CascadeClassifier(data/haarcascade_frontalface_default.xml) def detect_faces(gray_frame): # scaleFactor每次图像缩小的比例1.1~1.3 之间 # minNeighbors每个候选框保留所需的邻居数越大越严格 # minSize最小人脸尺寸过滤掉远处的小噪点 faces face_cascade.detectMultiScale( gray_frame, scaleFactor1.2, minNeighbors5, minSize(80, 80) ) return faces逻辑说明detectMultiScale是在多尺度上滑动窗口做检测。scaleFactor1.2表示每次把图像缩小 20% 再检测一轮值越小检测越细但越慢minNeighbors5是投票机制一个区域被判定为人脸需要周围有足够多的重叠框调大能减少误检但可能漏检minSize(80, 80)把小于 80 像素的框直接丢掉避免把背景纹理当人脸。实际调的时候光线暗就适当降minNeighbors误检多就往上加。检测前一定要转灰度cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)Haar 只吃灰度图喂彩色图会直接报错。3.2 人脸识别LBPH 训练与预测识别部分常见做法是用 LBPH局部二值模式直方图它对光照变化比 Eigenfaces 鲁棒样本量要求也低适合课设这种每人几张图的小数据集。训练流程是「读样本 → 打标签 → 训练 → 预测」import cv2 import numpy as np import os recognizer cv2.face.LBPHFaceRecognizer_create() def train_model(sample_dir): faces [] labels [] # 约定目录名就是人员 ID例如 data/samples/1/、data/samples/2/ for label_name in os.listdir(sample_dir): person_dir os.path.join(sample_dir, label_name) if not os.path.isdir(person_dir): continue for img_name in os.listdir(person_dir): img_path os.path.join(person_dir, img_name) gray cv2.imread(img_path, cv2.IMREAD_GRAYSCALE) if gray is None: continue detected face_cascade.detectMultiScale(gray, 1.2, 5) for (x, y, w, h) in detected: faces.append(gray[y:yh, x:xw]) labels.append(int(label_name)) recognizer.train(faces, np.array(labels)) recognizer.save(data/trainer.yml)逻辑说明labels必须是np.array且为整型传 list 会报类型错误。每张样本图先做一次人脸检测再裁剪保证训练用的是「人脸区域」而不是整张图这一步不做的话识别率会明显下降。recognizer.save(data/trainer.yml)把模型落盘下次启动直接recognizer.read(data/trainer.yml)加载不用每次重训。预测时用recognizer.predict(gray_face)返回(label, confidence)confidence 是距离值越小越像一般小于 50 认为可信超过 80 基本是误识别这个阈值要根据自己样本调。3.3 PyQt5 界面与签到业务怎么串界面部分MainWindow.py负责启动QtUI.py里用信号槽把按钮和业务函数连起来。典型结构是一个QLabel显示摄像头画面一个按钮触发签到一个表格或文本框显示签到记录。摄像头画面刷新用QTimer定时抓帧不能直接在 UI 线程里写while True否则界面会卡死。from PyQt5.QtCore import QTimer from PyQt5.QtGui import QImage, QPixmap import cv2 class CamShow: def __init__(self, label): self.label label self.cap cv2.VideoCapture(0) # 30ms 一帧约 33fps够用且不占满 CPU self.timer QTimer() self.timer.timeout.connect(self.update_frame) def update_frame(self): ret, frame self.cap.read() if not ret: return # OpenCV 是 BGRQt 要 RGB转换顺序不能反 rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) h, w, ch rgb.shape img QImage(rgb.data, w, h, ch * w, QImage.Format_RGB888) self.label.setPixmap(QPixmap.fromImage(img))逻辑说明QTimer的间隔决定刷新率30ms 对应约 33fps调太小 CPU 占用飙升调太大画面卡顿。QImage构造时的ch * w是每行字节数bytesPerLine传错会导致画面花屏或错位这是 PyQt5 显示 OpenCV 图像最经典的坑。签到业务在Functional_function.py里识别成功后拿datetime.now()记时间判断是否迟到再写入记录文件或数据库。记录落盘常见用 CSV 或 SQLiteCSV 简单直观SQLite 方便查询课设用哪个都行关键是写入时加异常处理避免文件被占用时整个程序崩掉。4. 避坑与排查那些让程序跑不起来的细节4.1 摄像头打不开或画面全黑现象程序启动后QLabel一片黑或者cap.read()一直返回False。原因通常是摄像头被其他程序占用比如刚关掉的调试窗口没释放或者VideoCapture(0)的索引不对多摄像头机器上内置摄像头不一定是 0。解决办法是先确认设备索引逐个试VideoCapture(0)、VideoCapture(1)并在程序退出时显式调self.cap.release()别指望 Python 自动回收。4.2 识别总是认错人或置信度乱跳现象同一个人一会儿识别成 A 一会儿识别成 Bconfidence 值忽高忽低。原因多半是训练样本太少或光照差异太大LBPH 对样本质量敏感。解决办法是每人至少录 10~20 张不同角度和光照的样本录入时统一做直方图均衡化cv2.equalizeHist(gray)让亮度分布一致。预测阈值也要卡confidence 超过 80 的直接判为「未知」别硬认。4.3 中文路径导致 imread 返回 None现象cv2.imread()读样本图返回None但文件明明存在。原因是 OpenCV 的imread在 Windows 上对中文路径支持不好。解决办法是用cv2.imdecode(np.fromfile(path, dtypenp.uint8), cv2.IMREAD_GRAYSCALE)替代或者干脆把样本目录和文件名全改成英文数字这也是我一般会建议的做法省事。4.4 PyQt5 界面卡死无响应现象点签到按钮后界面冻结几秒。原因是识别或训练这种耗时操作直接写在了 UI 线程里。解决办法是把耗时逻辑丢进QThread通过信号把结果传回主线程更新界面。课设里如果不想引入线程至少把训练放在程序启动时做一次别放在按钮回调里。4.5 打包或换机器后模块找不到现象本机跑得好好的换台电脑报ModuleNotFoundError: No module named cv2或No module named PyQt5。原因是没在目标环境装依赖或者虚拟环境没激活。解决办法是带着requirements.txt走目标机器上pip install -r requirements.txt并确认装的是opencv-contrib-python而不是只有opencv-python。5. 进阶把签到记录做成可查询、可导出的闭环基础版本跑通后真正拉开差距的是签到数据的处理。原始源码里记录可能只是简单追加到文本我一般会把它升级成 SQLite方便按人、按日期查询也方便导出给老师看。下面是一个最小可用的签到表设计和写入逻辑import sqlite3 from datetime import datetime def init_db(db_pathdata/attendance.db): conn sqlite3.connect(db_path) # 主键自增person_id 关联人员sign_time 存签到时间 conn.execute( CREATE TABLE IF NOT EXISTS attendance ( id INTEGER PRIMARY KEY AUTOINCREMENT, person_id INTEGER NOT NULL, person_name TEXT, sign_time TEXT NOT NULL ) ) conn.commit() return conn def sign_in(conn, person_id, person_name): now datetime.now().strftime(%Y-%m-%d %H:%M:%S) # 同一天同一人只记一次避免重复签到 today now[:10] cur conn.execute( SELECT id FROM attendance WHERE person_id? AND sign_time LIKE ?, (person_id, today %) ) if cur.fetchone(): return False, 今日已签到 conn.execute( INSERT INTO attendance (person_id, person_name, sign_time) VALUES (?, ?, ?), (person_id, person_name, now) ) conn.commit() return True, now逻辑说明sign_time LIKE 2024-01-01%用来判断当天是否已签到避免同一个人反复刷脸重复记录。person_id用整型和 LBPH 的 label 对应识别出 label 后直接拿它查名字。导出时用SELECT * FROM attendance配合csv.writer写文件即可。查询界面可以在 PyQt5 里加一个QTableWidget把查询结果填进去按日期范围过滤。验证方法上我习惯先造几条假数据跑一遍查询和导出确认时间格式、去重逻辑都对再接真实摄像头。这样即使识别模块出问题业务逻辑也是可验证的。从那以后我每次拿到这类课设源码都先把数据层单独跑通再碰界面和摄像头顺序反了就是无尽的玄学调试。希望这份拆解能帮你少走点弯路把这份源码真正用起来。本文还有配套的精品资源点击获取