课堂行为ST自动分析软件：Python+OpenCV实现学生行为识别与统计

简介：课堂行为ST自动分析软件面向教育技术、计算机视觉方向的学习者与毕业设计选题学生，提供一套可运行的课堂行为智能分析项目源码。软件结合AI与计算机视觉技术，通过视频或智能设备采集课堂数据，对学生的课堂行为进行检测与量化分析，为教学效果评估和参与度统计提供参考依据，适合作为需求分析、编码实现到测试维护的完整实践样本。压缩包共760个文件，以631个Python源码为主体，辅以pyc编译文件、png与jpg界面素材、ui界面文件、xml配置及少量音频与说明文档，整体约28.71MB，目录涵盖分析模块与客户相关文件，便于按模块研读与二次开发。目前已有885人学习下载。需注意代码中调用的腾讯语音识别接口已过期，读者可借此练习接口替换与功能修复，在理解行为识别算法、前后端交互与项目结构的同时积累技术迭代的应对经验。

1. 课堂行为ST自动分析软件：从一段课堂录像到一份行为统计表

上学期帮一位做教务的朋友看晚自习录像，四十分钟的视频，他要一帧一帧数谁在低头、谁在讲话、谁在发呆，数完两节课就过去了。后来我拿到这套「课堂行为ST自动分析软件」，把视频丢进去，几分钟后出来一张按时间轴排好的行为分布表，哪个时间段学生状态集中、哪几个座位异常频繁，一眼就能看出来。这项目属于典型的毕业设计软件类作品，定位很明确：面向课堂场景的学生行为自动识别与统计，适合两类人——正在找毕设选题、想直接拿一套能跑通的完整工程改一改的学生，以及需要快速验证课堂行为分析思路的一线开发者。它不追求工业级精度，但链路完整：视频输入、目标检测、行为分类、统计导出，每一环都有对应代码，改起来有抓手。

2. 技术栈与目录结构：这套工程到底由哪几块拼起来

2.1 技术选型：为什么是 Python + OpenCV + 轻量检测模型

这类课堂行为分析项目，常见做法是 Python 打底，OpenCV 负责视频解码和帧处理，深度学习部分用 PyTorch 或 TensorFlow 跑一个目标检测模型，再叠一层行为分类逻辑。这套工程基本遵循这个路子，选型理由很实在：Python 生态里视频处理和模型推理的库最全，OpenCV 的VideoCapture能直接吃 mp4、avi 甚至部分摄像头流，省掉自己写解码器的麻烦；检测模型选轻量级的原因也简单——课堂录像往往分辨率不低、时长不短，用大模型逐帧推理，普通笔记本根本扛不住，毕设场景下跑得动比跑得准更重要。

行为分类这块，工程里没有硬上复杂的时序模型，而是采用「检测框 + 规则/轻量分类器」的组合：先定位到人，再根据人体框的宽高比、头部位置、帧间位移等特征判断是低头、举手还是走动。这种做法的好处是可解释性强，调参直观，坏处是对遮挡和侧身场景不够鲁棒。我在实际拆的时候发现，这套逻辑对固定机位的教室录像效果最好，换到手持拍摄或者大角度俯拍，误判会明显上升，这一点后面避坑章节会细说。

依赖层面，除了opencv-python、numpy、torch，通常还会用到pandas做统计表导出、matplotlib画行为分布图。如果你的环境里没有 GPU，工程默认走 CPU 推理，速度会慢一些，但功能不受影响。

2.2 目录结构：按「输入—处理—输出」三段切分

拿到源码包，第一件事是看目录。这套工程的结构不算复杂，但分层清晰，我按实际拆解整理成下面这张表：

这个结构的好处是职责边界清楚：想换检测模型只动detector.py，想改行为判定规则只动behavior.py，统计口径变了只碰stats.py。我一般建议二次开发时先别急着改main.py，从config/里的参数入手，把阈值调到自己数据上能接受的水平，再动核心逻辑。

2.3 运行环境搭建：三条命令把依赖装齐

环境准备这块，工程一般会带一个requirements.txt。我习惯先建虚拟环境再装依赖，避免和系统里的其他包打架：

# 创建并激活虚拟环境（Windows 用 venv\Scripts\activate） python -m venv venv source venv/bin/activate # 安装依赖，国内网络慢可以加 -i 指定镜像源 pip install -r requirements.txt # 确认关键库版本，OpenCV 和 torch 版本不匹配是最常见的翻车点 python -c "import cv2, torch; print(cv2.__version__, torch.__version__)"

这里有个血泪经验：opencv-python和opencv-contrib-python不要同时装，两者会互相覆盖，导致某些函数莫名其妙找不到。工程里如果只用到基础视频读写，装opencv-python就够了。另外 torch 的 CPU 版和 GPU 版安装命令不同，没有独立显卡的话直接装 CPU 版，别硬上 CUDA 版，否则启动就报错。

模型权重文件通常放在models/下，如果源码包里没带，需要按config/里写的文件名自行准备，或者把配置里的路径改成你手头已有的模型。这一步是新手最容易卡住的地方——程序跑起来第一行就报「模型文件不存在」，八成是路径没对上。

3. 核心链路拆解：一帧画面是怎么变成一条行为记录的

3.1 视频读取与帧采样：不是每一帧都值得算

课堂录像动辄几十分钟，逐帧推理既慢又没必要。工程里在utils/video.py做了帧采样，常见做法是每隔 N 帧取一帧送进检测器，N 由配置里的frame_skip控制。下面是我按工程逻辑还原的核心代码：

import cv2 def read_frames(video_path, frame_skip=5): """按固定间隔抽帧，返回 (帧序号, 帧图像) 生成器""" cap = cv2.VideoCapture(video_path) if not cap.isOpened(): raise IOError(f"无法打开视频: {video_path}") fps = cap.get(cv2.CAP_PROP_FPS) # 原始帧率，用于换算时间戳 idx = 0 while True: ret, frame = cap.read() if not ret: break # 只处理满足间隔的帧，其余直接跳过 if idx % frame_skip == 0: yield idx, frame idx += 1 cap.release()

frame_skip是最值得先调的参数：设成 1 就是逐帧，精度最高但最慢；设成 5 到 10，在课堂这种行为变化不剧烈的场景下，统计结果差别不大，速度却能快好几倍。fps拿来做时间戳换算，后面统计表里「第几分钟到第几分钟」就靠它。注意cap.read()返回的ret为 False 时要及时 break，否则会陷入死循环读空帧。

3.2 目标检测与跟踪：给每个学生一个稳定编号

检测器负责在每帧里找出人，跟踪器负责把跨帧的同一个人串起来。没有跟踪的话，统计表里会出现「第 1 帧 30 个人、第 2 帧 28 个人」这种没法解释的抖动。工程里core/tracker.py用的是简易的 IoU 匹配思路，核心逻辑如下：

def match_by_iou(prev_boxes, cur_boxes, iou_thresh=0.3): """用 IoU 把当前帧检测框和上一帧轨迹做匹配""" matches = {} for i, cb in enumerate(cur_boxes): best_iou, best_j = 0, -1 for j, pb in enumerate(prev_boxes): iou = compute_iou(cb, pb) if iou > best_iou: best_iou, best_j = iou, j # 只有重叠度够高才认为是同一个人 if best_iou >= iou_thresh: matches[i] = best_j return matches

iou_thresh是匹配门槛，调高会让跟踪更保守（同一个人容易被判成新目标），调低则容易把相邻两个人串成一个。课堂场景学生坐得比较密，我一般会把它设在 0.3 到 0.4 之间，再配合检测框中心点的位移做二次校验。compute_iou就是标准的交并比计算，两个框交集面积除以并集面积，工程里放在utils下。

跟踪稳定之后，每个学生就有了固定 ID，后续所有行为记录都挂在这个 ID 上，统计表才能按人汇总。

3.3 行为判定：从检测框特征到行为标签

这是整套工程最核心也最需要改的部分。core/behavior.py里把检测框的几何特征映射成行为标签，常见判定逻辑大致是这样：

def classify_behavior(box, prev_box=None, frame_h=1080): """根据检测框宽高比和帧间位移判定行为""" x1, y1, x2, y2 = box w, h = x2 - x1, y2 - y1 ratio = w / max(h, 1) # 宽高比，站立时通常更瘦长 # 帧间位移大，判为走动 if prev_box is not None: cx, cy = (x1 + x2) / 2, (y1 + y2) / 2 px, py = (prev_box[0] + prev_box[2]) / 2, (prev_box[1] + prev_box[3]) / 2 if ((cx - px) ** 2 + (cy - py) ** 2) ** 0.5 > frame_h * 0.02: return "走动" # 宽高比偏大且框体偏矮，判为低头/趴桌 if ratio > 1.2: return "低头" return "正常"

这段逻辑的参数含义要讲清楚：ratio阈值 1.2 是经验值，坐姿正常时人体框偏竖长，低头趴桌时框会变扁；位移阈值用frame_h * 0.02做归一化，避免换分辨率后阈值失效。这套规则简单直接，但边界情况多——举手和伸懒腰在框特征上很像，侧身坐和低头也容易混。我的建议是先把判定结果可视化出来，人工抽检几十帧，看哪类误判最多，再针对性加特征（比如头部区域的颜色或位置），别一上来就换模型。

3.4 统计导出：把逐帧结果压成一张能看的表

逐帧记录只是中间产物，真正交付的是统计结果。utils/stats.py负责把行为序列按学生 ID 和时间窗口聚合：

import pandas as pd def build_report(records, window_sec=60): """records: [(student_id, timestamp, behavior), ...]""" df = pd.DataFrame(records, columns=["student_id", "ts", "behavior"]) # 按分钟窗口切分，统计每个学生在每个窗口内各行为的帧数占比 df["window"] = (df["ts"] // window_sec).astype(int) pivot = df.groupby(["student_id", "window", "behavior"]).size().unstack(fill_value=0) pivot["total"] = pivot.sum(axis=1) for col in pivot.columns[:-1]: pivot[col + "_pct"] = (pivot[col] / pivot["total"] * 100).round(1) return pivot.reset_index()

window_sec控制统计粒度，设成 60 就是按分钟出表，设成 300 就是五分钟一段。unstack把行为标签转成列，后面算占比方便。导出的表可以直接用 Excel 打开，也可以再接matplotlib画堆叠柱状图。这里要注意时间戳ts的单位要和window_sec一致，工程里统一用秒，如果上游传的是帧号，记得先除以 fps 换算。

4. 避坑与常见问题：跑不起来时先看这几条

4.1 模型加载报错：路径和格式两头查

现象是程序启动即退出，日志里写着模型文件找不到或加载失败。原因通常有两个：一是config/里的路径是相对路径，而你在别的目录下执行python main.py，工作目录不对；二是模型权重和推理代码的框架版本不匹配，比如权重是用新版 torch 存的，本地装的是旧版。解决办法是把配置里的模型路径改成绝对路径，或者统一在工程根目录下执行；版本问题则对照requirements.txt把 torch 升到对应版本，别图省事直接pip install torch装最新版。

4.2 视频读出来是空：编码格式的锅

现象是cap.isOpened()返回 True，但一帧都读不到，或者读几帧就断。原因是 OpenCV 自带的解码器对某些编码（尤其是 H.265 或某些手机直出的 mp4）支持不好。解决思路是先确认视频能正常播放，再用 ffmpeg 转成 H.264 编码的 mp4 再喂给程序：

ffmpeg -i input.mp4 -c:v libx264 -preset fast -crf 23 output.mp4

转码后体积可能变大，但兼容性最好。这条我踩过不止一次，尤其是从手机或录播设备导出的素材。

4.3 统计结果人数对不上：跟踪 ID 频繁切换

现象是统计表里学生数量远多于实际人数，同一个人被拆成好几个 ID。原因是跟踪的 IoU 阈值设得太高，或者检测框在相邻帧之间抖动太大。解决办法是把iou_thresh适当调低，同时在跟踪逻辑里加一个「轨迹存活帧数」过滤，只保留连续出现超过若干帧的 ID，短暂闪现的误检自然被滤掉。这个过滤阈值一般设 5 到 10 帧，按帧率换算就是零点几秒。

4.4 CPU 推理慢到无法接受：先降采样再谈优化

现象是跑一分钟视频要等十几分钟。原因多半是帧采样间隔太小加上输入分辨率太高。解决办法分两步：先把frame_skip调到 5 以上，再把送进模型的帧缩放到固定尺寸（比如 640 宽），检测完再把框映射回原图坐标。这两步做完，速度通常能提升一个数量级，精度损失在课堂统计场景下可以接受。如果还慢，再考虑换更轻的模型，别一上来就折腾多进程，收益不成正比。

5. 二次开发改造：从「能跑」到「敢用」的几个抓手

5.1 换检测模型：接口不变，只换实现

工程把检测封装在core/detector.py里，对外只暴露「输入一帧、输出框列表」的接口。想换模型，保持这个接口签名不变，内部实现随便换。我一般会先写一个适配层，把新模型的输出统一成[x1, y1, x2, y2, score]的格式，这样上层的行为判定和跟踪代码一行都不用动。验证方法是拿同一段视频分别跑新旧模型，对比检测框数量和统计表差异，差异在可解释范围内再切换。

5.2 行为判定规则化：把阈值搬进配置

behavior.py里的阈值硬编码是二次开发的大障碍。改造思路是把ratio阈值、位移阈值、窗口长度全部提到config/里，用字典或 yaml 管理。这样换一个教室、换一种机位，只改配置不改代码，调参效率高很多。下面是一个配置化的示意：

# config/behavior.yaml 读取后得到的字典 BEHAVIOR_CFG = { "ratio_thresh": 1.2, # 宽高比超过此值判低头 "move_ratio": 0.02, # 位移超过画面高度此比例判走动 "min_track_frames": 8, # 轨迹存活帧数下限，过滤误检 "window_sec": 60, # 统计窗口长度 }

改完之后，每次调参只动 yaml，代码库保持干净，也方便把不同教室的参数存成多份配置切换。

5.3 验证方法：别只看总数，要看时间轴

改造完怎么验证？我的习惯是抽三段视频：一段正常课堂、一段有学生频繁走动、一段光线偏暗。每段都人工标出几个关键时间点，看程序在这些时间点的行为判定是否吻合。只看总人数和总占比容易被平均掉，时间轴上的局部错误才是真问题。另外统计表导出后，用 Excel 画个折线图，异常尖峰往往对应误判集中区，顺着尖峰回去看原始帧，定位效率比盲翻高得多。

5.4 一个具体技巧：用「行为热力图」快速定位问题座位

在stats.py里加一个按座位区域聚合的维度，把每个学生 ID 的平均检测框中心点映射到画面网格上，统计每个网格内「低头」行为的占比，输出成一张热力图。这个改动不大，但排查问题时特别好用——如果某个角落低头占比异常高，要么是那个位置真有学生趴桌，要么是检测框在那个区域系统性偏移，一眼就能区分。实现上就是把中心点坐标除以网格尺寸取整，再groupby聚合，最后用matplotlib的imshow出图。

从那以后我每次拿到这类行为分析工程，都强制先跑一遍可视化抽检再谈调参，因为黑匣子式的数字最会骗人。希望这套拆解能帮到你，把这份毕设工程真正跑成自己手里的东西。

本文还有配套的精品资源，点击获取