简介面向线下课堂的智慧课堂项目基于PyQt5与深度学习技术构建了一套学生专注度自动分析与评估系统可辅助教学管理者实时了解课堂学习状态并为进一步的教学改进提供数据参考。该方案包含完整Python源码、设计文档和模型文件代码经过验证可稳定运行并留有清晰的界面交互逻辑适合计算机、人工智能、数据科学等专业学生用于毕业设计、课程设计或初期项目演示也适合初学者系统学习PyQt5与深度学习融合开发有基础者还可基于此二次开发扩展考勤、情绪识别等功能。资源共218个文件压缩包仅17.02MB以Python源码py、编译文件pyc、界面设计ui、配置与图标文件为主同时包含少量CUDA扩展cu/hpp、数据文件及文档说明目录结构清晰便于按模块查阅。目前已有150人学习下载适合希望快速上手完整桌面应用深度学习项目的开发者。1. 教室摄像头真正能测出什么这个标题在解决的现实问题线下课堂的场景里老师站在讲台上永远只能看到一小部分学生的脸。一节课四十分钟有人低头玩手机、有人盯着窗外、有人假装记笔记其实在走神靠人力去统计这些行为几乎不可行。而这个标题的核心是把两件事拼在一起用深度学习的检测和姿态模型从摄像头画面里判断每个学生的头部朝向和眼睛状态再用 PyQt5 做一套本地运行的桌面程序把“这个学生在专注还是走神”的结果实时显示在屏幕上。它不是读心术测的是一系列和专注度强相关的行为指标但这套方案在教务督导、课堂分析和课设毕设里确实用得最多。适合谁看要复现这个项目的人、想把它改造成自研系统的工程师以及正在做课堂行为分析选型的产品和技术负责人。2. 专注度分析为什么能成立拆开深度学习模型和 PyQt5 各自的分工2.1 专注度在工程上到底怎么定义行为代理指标做专注度分析的第一步不是选模型而是先回答一个问题什么行为算专注工程上没人能直接读学生的心理状态我们能拿到的只有摄像头画面。所以所有专注度系统用的都是行为代理指标即用可测量的外在行为去近似内在注意力状态。把这个指标定义清楚整个系统的深度学习和评分逻辑才有依据。常见的代理指标有四个头部朝向是否长时间低头或侧头、眼睛开合程度是否闭眼、是否频繁眨眼、离座/遮挡是否完全脱离画面比如趴在桌上或走出座位、手部靠近面部大概率在玩手机或遮挡视线。落到代码里前两个指标是主流因为头部姿态和眼睛状态可以直接从人脸图像里提取模型成熟、开源权重多做起来的性价比最高。这个环节我一般会提醒自己一句系统测的是行为不是心理。一个学生全程盯着黑板也可能走神但工程上这种误差可以被接受因为行为特征在统计意义上和成绩、课堂参与度确实有相关性。把指标定义成规则写进项目文档后面调参和验收才不会跑偏。2.2 深度学习模型的分工人脸检测、头部姿态估计和眼部状态分析标题里写了“深度学习”但专注度分析不是一个模型包打天下而是三个模型各管一段。第一个是人脸检测模型负责在画面里找到每个人脸的位置输出边界框和置信度。常见做法用 YOLO 系或 RetinaFace它们的共同点是速度快能在一帧画面里同时框出几十个人这正好匹配教室场景。第二个是头部姿态估计模型输入人脸图像输出三个欧拉角yaw左右转头、pitch点头/抬头、roll歪头这三个角度是判断专注与否的核心数据。第三个是眼睛状态分析用来计算眼睛的开合度这个任务用关键点检测就能完成典型方案是检测眼睛六点坐标后算 EAR 值。下面用伪代码展示一帧画面在系统里的完整流转路径import cv2 import numpy as np def analyze_frame(frame, det_model, pose_model, eye_model): 单帧分析主流程 det_model: 人脸检测模型, 返回 bboxes 和置信度 pose_model: 头部姿态模型, 返回欧拉角 eye_model: 眼睛关键点模型, 返回左右眼开合度 # 第一步: 人脸检测, conf 阈值过滤低质量框 boxes, scores det_model.detect(frame, conf_threshold0.5) results [] for box, score in zip(boxes, scores): x1, y1, x2, y2 [int(v) for v in box] face frame[y1:y2, x1:x2] # 第二步: 头部姿态估计, 得到欧拉角 yaw, pitch, roll pose_model.estimate(face) # 第三步: 眼睛状态分析, 得到左眼和右眼 EAR eye_left, eye_right eye_model.ear(face) # 第四步: 按规则打分, 0~1 之间, 1 代表完全专注 attention_score compute_attention_score(yaw, pitch, roll, eye_left, eye_right) results.append({ box: box, yaw: yaw, pitch: pitch, roll: roll, ear: (eye_left eye_right) / 2, score: attention_score, conf: score }) return results这段代码展示的核心是分层解耦检测、姿态、眼部三个模型互不依赖任何一层都可以单独替换。比如你不想用 YOLO可以把 det_model 换成 MediaPipe主流程不用改。参数说明里最值得关注的是conf_threshold0.5它过滤掉低质量的人脸框在教室场景中后排小脸或侧脸很容易低于这个值。如果你检测的是前排特写这个值可以提到 0.7如果是全景教室建议降到 0.4避免漏掉太多后排名额。2.3 为什么用 PyQt5 而不是 Web 前端本地部署的现实考量这个问题在方案评审时大概率会被问一次。标题选择了 PyQt5本质上是因为这类课堂分析系统对部署方式有硬约束。教室里的网络不稳定摄像头画面如果推流到服务端再回传结果延迟和带宽都不可控而 PyQt5 做的桌面程序可以在教室本地跑摄像头直接连到本机全部计算在本地完成不依赖外网。另一个原因是摄像头权限在浏览器里限制多WebRTC 采集教室摄像头经常要求 HTTPS 和授权弹窗落地时会被现场的老师嫌弃而 PyQt5 配合 OpenCV 的 VideoCapture 只在系统层面申请一次权限使用上顺滑得多。在 PyQt5 的架构设计上有一个重要原则GUI 主线程绝不能做推理。OpenCV 的cap.read()是阻塞式的而深度学习模型的推理在 CPU 上可能要 50ms 到 100ms直接放主线程会让界面卡成 PPT。常见做法是开两个线程一个CaptureThread负责读帧一个DetectThread负责跑模型两个线程通过 PyQt5 的信号与槽机制把结果传回界面刷新。from PyQt5.QtCore import QThread, pyqtSignal import cv2 class CaptureThread(QThread): 摄像头采集线程: 只做读帧, 不跑模型 QThread 里不能直接操作界面控件, 必须用信号传帧 frame_ready pyqtSignal(object) def __init__(self, source0): super().__init__() self.cap cv2.VideoCapture(source) self.cap.set(cv2.CAP_PROP_FRAME_WIDTH, 1280) self.cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 720) self.running True def run(self): while self.running: ret, frame self.cap.read() if ret: self.frame_ready.emit(frame) self.msleep(30) # 限制采集帧率, 约 30fps def stop(self): self.running False self.cap.release()msleep(30)这个参数容易被忽略但它实际上决定了采集线程的负载。不加这个延时摄像头会把所有空闲 CPU 都吃满风扇狂转而模型推理根本跟不上这个帧率多余的帧只会被丢弃。我一般会把它控制在 25ms 到 40ms 之间对应 25 到 40 帧的实际采集频率。1280x720是教室场景的折中选择太低看不清后排人脸太高推理耗时翻倍720P 在高清和性能之间最平衡。3. 从零跑通项目环境搭建、项目结构和首次启动3.1 环境准备Python 版本、虚拟环境和 PyQt5 安装跑整个项目之前环境是第一道门槛。这个系统依赖深度学习框架和桌面 GUI 库对 Python 版本有兼容性要求我一般直接用 conda 创建独立环境避免把系统 Python 弄乱。Python 版本建议选 3.8 或 3.9这两个版本对 PyQt5、OpenCV 和深度学习框架的兼容性最稳太新的 3.11 偶尔会遇到预编译包缺失的问题。PyQt5 的安装是很多人的第一个坑因为默认源下载慢、容易超时。常见做法是直接用清华源安装装完立刻验证导入是否正常conda create -n class_analysis python3.9 -y conda activate class_analysis # PyQt5 装 5.15.x 系列, 兼容性和稳定性最好 pip install -i https://pypi.tuna.tsinghua.edu.cn/simple PyQt55.15.9 # 深度学习相关依赖 pip install -i https://pypi.tuna.tsinghua.edu.cn/simple torch torchvision --index-url https://download.pytorch.org/whl/cpu pip install -i https://pypi.tuna.tsinghua.edu.cn/simple opencv-python numpy # 验证四件套是否可用 python -c import PyQt5; import cv2; import torch; import numpy; print(env ok)最后一行验证命令很重要它能在一分钟内暴露所有环境问题。如果import PyQt5报错说明 PyQt5 和 Python 版本不兼容如果import cv2报错多半是 OpenCV 装成了不匹配的版本。深度学习框架按 CPU 版本先装因为大多数教室机器没有独立显卡代码上用 CPU 推理能正常走通整个流程就够了。3.2 项目结构每个文件和目录在做什么标题里明确写了“python源码设计文档模型”解压后你会看到一套完整的分层目录。我按常见做法梳理这套结构它能让新接手的人 10 分钟内找到对应模块目录/文件作用重要性main.py程序入口负责启动 PyQt5 应用启动看它ui/PyQt5 界面文件包括主窗口和状态栏设计改界面看它core/深度学习核心逻辑检测、姿态、注意力评分改算法看它models/放置预训练权重的目录跑不起来先看它data/保存检测结果的 CSV 或日志查数据看它design_doc/系统设计文档包含需求和架构入门看它启动入口是main.py它做的事情很传统创建 QApplication、加载主窗口、启动采集线程然后进入事件循环。首次启动前建议先读design_doc里的需求分析你会看到注意力评分的规则定义和接口约定这比直接读代码效率高得多。3.3 首次启动最小可运行命令和界面清单环境装好后直接从入口文件启动。如果你买的摄像头恰好是免驱 USB 摄像头系统默认索引是 0如果是笔记本自带摄像头索引多半也是 0但部分机器内置和外接同时存在时外接可能是 1。最省事的做法是启动后右下角显示画面如果没有画面再按下一小节的排查方法处理。conda activate class_analysis # 在项目根目录执行 python main.py启动成功你会看到主窗口分三块区域左侧是实时视频画面每一帧根据检测结果在对应人脸位置画框框的颜色从绿到红渐变绿色表示专注度高红色表示走神预警右侧是当堂课的专注度统计列表按学生 ID 聚合底部是时间轴和实时曲线用来观察整堂课的专注度波动。这套界面布局是课堂分析项目里最常见的样子也是标题里 PyQt5 界面设计最直接的体现。如果界面起不来报错信息是关键线索。最常见的两种情况缺少模块会告诉你ModuleNotFoundError模型文件路径不对会告诉你FileNotFoundError。前者回到 3.1 用 pip 补装后者把模型文件放到models/目录并检查配置文件中的路径是否指向它。4. 参数配置与调优影响专注度判断的四个关键旋钮4.1 头部姿态阈值yaw、pitch、roll 怎么设才不误报专注度评分系统里姿态角阈值是决定准确率的头号参数。yaw 表示左右转头pitch 表示点头或仰头roll 表示歪头。默认规则通常写的是 yaw 绝对值小于 30 度且 pitch 小于 25 度算专注但这个参数必须在真实场景里校准因为摄像头安装位置直接改变角度分布。比如说摄像头装在黑板正上方学生会自然俯视课本和桌面这时 pitch 角整体偏移一个专注记笔记的学生可能 pitch 是 -20 度如果阈值写死为小于 15 度就会把这个学生误判成走神。所以我不建议直接用默认阈值而是先录 3 分钟正常课堂视频把每个学生的姿态角分布导出来看专注状态和走神状态在角度上的分界线在哪里再回填到配置文件。# config.py 中注意力评分的核心参数 ATTENTION_CONFIG { yaw_threshold: 30, # 左右转头阈值, 超过认为注意力偏移 pitch_threshold: 25, # 低头抬头阈值, 超过认为不在看前方 roll_threshold: 20, # 歪头阈值, 超过认为姿态异常 ear_threshold: 0.22, # 眼睛开合度阈值, 低于认为闭眼 consecutive_frames: 15, # 连续多少帧触发状态变更 detect_interval: 5, # 每隔多少帧跑一次模型 }consecutive_frames是防抖的关键它代表一个状态持续多久才被确认。如果置为 1学生一次短暂的低头系鞋带就会被标记成走神整节课会产生大量误报。我一般调到 10 到 20对应约 0.5 到 1 秒的持续时间既不会漏掉真实走神也不会被短暂动作干扰。detect_interval是性能参数每隔 5 帧跑一次模型GPU 上可以改成 2CPU 上反而是 8 到 10 更流畅。4.2 置信度阈值与人脸框过滤逻辑模型输出的置信度不是越高越好。在教室全景画面里后排人脸可能只有 24x24 像素检测模型的置信度普遍在 0.3 到 0.5 之间。把阈值设成 0.7后排学生基本全被过滤掉了设成 0.3前排清晰的人脸确实会保留但也会混入不少误检的背景噪声。合理的做法是把置信度作为一项配置而不是写死在代码里。下面是一段实际的过滤逻辑包含置信度和人脸尺寸两个条件def filter_boxes(boxes, scores, frame_height): 过滤低置信度和小尺寸人脸框 frame_height 用于动态计算最小人脸尺寸 min_conf 0.45 # 动态最小人脸尺寸: 画面高度的 1/10, 小于这个值的人脸无法做姿态估计 min_face_h frame_height * 0.1 valid [] for box, score in zip(boxes, scores): x1, y1, x2, y2 [int(v) for v in box] face_h y2 - y1 if score min_conf and face_h min_face_h: valid.append((box, score)) return validmin_face_h这个参数容易被忽略但极其重要。人脸框选出来了姿态模型也一样会对小图产生误差因为姿态模型训练时用的输入图普遍是 64x64 以上。一个 20 像素高的人脸塞进姿态模型输出的角度基本是噪声。所以业界一般的经验是丢弃小于画面高度十分之一的人脸宁可漏检也不误判因为在课堂这种多人场景里误报的维护成本远高于漏检。4.3 注意力评分公式的设计加权和与时间窗口拿到姿态角和眼睛数据后最终要合成一个 0 到 1 的专注度分数。常见做法是加权求和加时间窗口平滑。加权规则是我在调参时最花心思的地方因为它直接决定业务上好不好用。默认权重是 yaw 占 0.4、pitch 占 0.3、roll 占 0.1、眼睛状态占 0.2原因在于左右转头对专注度的破坏最强低头次之歪头和闭眼共占比三成。平滑时间的处理上有一个经验值采用 3 秒窗口的移动平均而不是只用当前帧。单一的某一帧姿态可能因为学生捡笔等动作出现突变但 3 秒平均后这些噪声会被磨平。如果窗口太长比如 10 秒系统会对走神行为的反应极度迟钝老师已经提醒学生两次了界面还显示绿色体验会非常糟糕。def compute_attention_score(yaw, pitch, roll, ear, look_straight_cnt): 注意力评分: 加权和 时间窗口修正 look_straight_cnt: 连续朝前方的帧数 # 基础评分: 角度越接近 0 越好, 得分越高 score 1.0 score - abs(yaw) / 90 * 0.4 # yaw 权重 0.4 score - abs(pitch) / 90 * 0.3 # pitch 权重 0.3 score - abs(roll) / 90 * 0.1 # roll 权重 0.1 score - (1 - ear) * 0.2 # 眼睛闭合程度, 权重 0.2 # 修正: 如果连续长时间朝前, 认为专注度向好 if look_straight_cnt 50: score min(1.0, score 0.1) return max(0.0, min(1.0, score))注意这个评分公式是典型的可解释规则不是黑匣子模型。它的好处是教务老师在看到某个学生得分低时我们能明确说出是因为转头、低头还是闭眼这是深度学习模型做不到的可解释性。在校园场景里老师的信任感往往比模型准确率更重要。5. 避坑指南从环境到部署的 5 个高频问题5.1 问题一PyQt5 装不上或者装完界面起不来现象pip install PyQt5 长时间卡住或者装完运行import PyQt5报ModuleNotFoundError。原因默认 PyPI 源在国外网络不稳定导致下载超时另外pip版本太低无法正确解析 Qt 的二进制包。解决换国内源安装然后升级 pip。CLI 命令如下pip install --upgrade pip pip install -i https://pypi.tuna.tsinghua.edu.cn/simple PyQt5提示如果你在同一环境里还要用 labelme 做数据标注PyQt5 和 PyQt5-sip 的版本必须匹配否则 labelme 会报 sip 相关错误。常见的搭配是 PyQt5 5.15.9 搭配 PyQt5-sip 12.12 以上版本。5.2 问题二摄像头打不开画面黑色或程序直接崩溃现象cv2.VideoCapture(0)返回值是 None或者界面能打开但画面全黑过几秒程序崩溃。原因摄像头被其他程序占用比如微信、腾讯会议或者系统分配的摄像头索引不是 0。在一些多摄像头笔记本上内置摄像头索引可能是 1 而不是 0。解决先释放摄像头占用再写一段独立的扫描代码找出可用索引import cv2 def find_camera(): 扫描 0~4 号摄像头, 找到能正常打开的 for index in range(5): cap cv2.VideoCapture(index) if cap.isOpened(): ret, frame cap.read() if ret and frame is not None: print(f摄像头可用: 索引 {index}) cap.release() return index cap.release() print(未找到可用摄像头) return None注意cap.isOpened()返回 True 不代表摄像头能出图一定要加上一次cap.read()验证。我遇到过摄像头索引被占用但isOpened()依然返回 True 的情况只有真正读到帧才算可用。5.3 问题三模型文件加载失败报路径错误现象程序运行到加载权重文件时崩溃报FileNotFoundError或者AttributeError。原因路径写的是相对路径而当前工作目录不是项目根目录。很多新手直接从 IDE 里运行工作目录变成了src/子目录自然找不到上级目录的模型文件。解决在项目入口文件最上方用绝对路径定位项目根目录import os import sys # 获取项目根目录的绝对路径, 无论从哪里启动都能正确加载 PROJECT_ROOT os.path.dirname(os.path.abspath(__file__)) MODEL_DIR os.path.join(PROJECT_ROOT, models) # 拼出权重文件的完整路径 det_weight os.path.join(MODEL_DIR, face_det.pt) pose_weight os.path.join(MODEL_DIR, pose_model.onnx) # 加载后顺手打印一次, 确认路径没有拼错 print(模型目录:, MODEL_DIR)os.path.abspath(__file__)是解决路径问题的万能方案它永远指向当前文件所在的目录不受启动位置影响。顺手打印一次模型目录是我的习惯这样启动时一眼就能看出是不是路径问题。5.4 问题四界面卡顿掉帧严重CPU 占用拉满现象摄像头画面像幻灯片拖动窗口非常卡CPU 使用率 100%电脑风扇狂转。原因整个检测流程跑在主线程里cap.read()和模型推理都是耗时操作阻塞了 GUI 事件循环。另一个原因是没控制检测频率每帧都跑模型。解决把采集和推理放到独立线程用信号回传结果同时降低检测频率。线程分离的代码可以参考 2.3 小节的 CaptureThread这里补充一个关键实践——不要把整个视频帧通过信号传太多次否则队列堆积界面照样卡。class DetectThread(QThread): 检测线程: 接收原始帧, 输出标注帧 注意: 每隔 detect_interval 帧推理一次, 其余帧直接复用上次结果 result_ready pyqtSignal(object, object) # 标注后的帧, 统计结果 def __init__(self, interval5): super().__init__() self.interval interval self.frame None self.running True def update_frame(self, frame): self.frame frame def run(self): frame_count 0 while self.running: if self.frame is None: self.msleep(10) continue # 每隔 interval 帧才跑一次模型, 其余帧用 last_result if frame_count % self.interval 0: annotated, stats self.analyze(self.frame) self.result_ready.emit(annotated, stats) frame_count 1 self.msleep(10)检测线程和采集线程之间靠共享变量传帧代替信号机制减少一次昂贵的对象拷贝。interval5意味着实际推理帧率只有采集帧率的五分之一如果采集 30fps推理只有 6fps但画面观感不会明显变差因为人脸框在短时间内的移动很小。这是性能与流畅度的最佳平衡点我把它视作课堂系统的默认配置。5.5 问题五中文路径导致 OpenCV 读不到图片现象把项目放在D:\课堂项目\这种带中文的路径下摄像头画面正常但保存截图或加载本地图片时失败程序不报错只是输出的图片是黑的。原因OpenCV 的cv2.imread不支持中文和特殊字符路径这是底层 C 实现的历史遗留问题在 Windows 上尤其明显。解决用np.fromfile绕开这个问题读取后用cv2.imdecode解码保存时用cv2.imencode配合tofileimport cv2 import numpy as np def imread_chinese(path): 兼容中文路径的图片读取 data np.fromfile(path, dtypenp.uint8) img cv2.imdecode(data, cv2.IMREAD_COLOR) return img def imwrite_chinese(path, img): 兼容中文路径的图片保存 ext path.split(.)[-1] _, encoded cv2.imencode(f.{ext}, img) encoded.tofile(path)提示顺手把项目整个复制到纯英文路径下能少很多麻烦。虽然提供了兼容方案但 PyQt5 的setWindowTitle、日志模块的编码问题同样可能在中文路径下出现我没有精力在每个环节都做兼容所以最终我的项目文件夹永远叫class_analysis固定在英文路径下。6. 进阶用法用录制视频验证系统、数据落盘与课堂报告项目跑通后下一步不是急着部署到教室而是先用录制视频做回归验证。直接连摄像头调试的问题是真实课堂不可控你在现场很难复现同一个学生的同一组动作问题排查效率很低。常见做法是准备两段标准测试视频一段为正常上课场景一段为多人趴桌和玩手机的走神场景把CaptureThread里的摄像头源替换成视频路径然后整节课跑一遍。替换方法特别简单实例化时传视频路径即可cv2.VideoCapture(test_video.mp4)。跑完后对比标注框和人工标注的差异看两个指标命中率即真实走神行为被系统检出的比例误报率即正常行为被标出走神的比例。我给自己定的验收线是命中率不低于 0.8、误报率不高于 0.15达不到就先调 4.1 节的阈值而不是急着换模型。数据落盘是另一个被很多人忽略但实际很关键的环节。课堂专注度分析如果不保存历史数据它就是一个实时监控工具价值远低于积累成教学分析数据。我习惯把每帧结果写入 SQLite一句话总结就是按学生 ID、时间戳、专注度分数、状态标签四列组织数据。整节课跑完用一句 SQL 就能算出全班平均专注度、每个学生的专注度分布和按时间段的趋势曲线-- 按时间段聚合专注度, 可直观看到课堂后段注意力衰减 SELECT strftime(%H:%M, timestamp) AS time_slice, AVG(attention_score) AS avg_score, COUNT(CASE WHEN status distracted THEN 1 END) AS distracted_cnt FROM attention_records GROUP BY time_slice ORDER BY time_slice;SQLite 相比 CSV 的最大优势是并发安全和支持条件聚合。课堂系统运行时一直在写数据如果同时用 pandas 读文件做分析CSV 会大概率出现写冲突而 SQLite 可以一边写一边读。如果后续要生成周报或学期报告直接把这个 SQL 接上图表库即可不用重复造轮子。最后分享一个我的个人习惯每次改完参数我会先跑一遍录好的标准视频把整节课的专注度曲线打印出来对比上一次的结果差异。因为有些阈值调整会对个别动作产生连锁反应肉眼在实时画面上很难发现但对比曲线能立刻看出一节课后段的注意力衰减趋势是否合理。这个习惯帮我避免了很多次改了 A 参数却让 B 场景误报增多的翻车情况。希望这篇笔记能帮你把课堂专注度分析系统稳稳跑起来少走一点我走过的弯路。本文还有配套的精品资源点击获取
