简介这份资源是面向教育技术方向学生与毕业设计学习者的课堂行为智能分析软件项目通过AI与计算机视觉技术对课堂视频或智能设备采集的数据进行学生行为检测与参与度量化为教学效果评估提供参考。压缩包共760个文件以631个Python源码为核心辅以67个pyc编译文件、22张png与9张jpg界面素材、4个ui界面文件及若干txt、xml配置说明整体约28.71MB目录涵盖分析模块、界面资源与配置数据便于按模块研读。目前已有879人学习下载适合作为完整项目案例参考。读者可从中了解需求分析、行为识别算法集成、后端处理与前端交互的完整开发流程并借助现有代码结构进行二次开发需注意其中腾讯语音识别接口已过期可借此练习接口替换与功能维护积累技术迭代的应对经验。1. 课堂行为ST自动分析软件从一段课堂录像到一份行为统计表带过毕业设计的同学大概都遇到过这种场景导师丢来一段四十分钟的教室监控录像说“你把这个课上学生的行为统计一下看看谁在听、谁在走神、谁在低头”。人工一帧帧看看完眼睛就废了。这个项目就是冲着这个痛点来的——输入一段课堂视频自动识别并统计学生的行为类别输出每类行为的时长占比和分布。它适合两类人一类是正在做毕业设计、需要一套能跑通的行为识别流水线的学生另一类是手里有课堂录像、想快速拿到行为统计结果的一线教师或教研人员。技术栈上走的是 Python OpenCV 深度学习分类模型的组合整体结构不复杂但把“视频解码—目标检测—行为分类—统计输出”这条链路串完整了拿来当毕设骨架或者二次开发底座都够用。2. 项目整体架构一条从视频帧到统计报表的处理流水线2.1 模块划分与数据流向这个软件的核心思路是把“看视频”拆成四个可独立调试的阶段每个阶段只干一件事出了问题能快速定位是哪一环翻车。整体数据流是这样的视频文件先被解码成帧序列帧序列送进检测模块定位出每个学生的人体框人体框裁剪后送进行为分类模型得到行为标签最后统计模块按时间轴汇总每个学生的行为序列并输出报表。模块划分大致如下模块职责关键依赖视频解码模块读取视频、抽帧、时间戳对齐OpenCV目标检测模块定位画面中的学生人体框轻量检测模型行为分类模块对每个人体框判定行为类别图像分类模型统计输出模块按学生 ID 汇总行为时长、生成报表pandas这种拆法的好处是每个模块都能单独替换。比如检测模型换成更轻的版本或者分类模型换成自己训练的权重只要保持输入输出接口一致其他模块不用动。常见做法是把每个模块封装成一个类主流程里按顺序调用模块之间通过 numpy 数组和字典传递数据不搞复杂的消息队列。2.2 技术选型背后的取舍为什么用 OpenCV 而不是别的视频库因为课堂录像大多是 mp4 或 avi 格式OpenCV 的VideoCapture对这两种格式支持最稳而且抽帧时能直接拿到帧率信息方便后面把“第几帧”换算成“第几秒”。检测和分类没有用特别重的模型原因是课堂场景下人体目标密集、遮挡多太重的小模型跑不动太轻的又漏检折中选了能在普通笔记本 CPU 上跑到可接受帧率的轻量方案。统计部分用 pandas 是因为行为序列本质上是带时间戳的表格数据按学生 ID 分组、按时间排序、算时长占比这些操作 pandas 几行就能写完自己手写循环反而容易出错。整个项目没有引入 Web 框架输出就是 CSV 和几张统计图毕设答辩时直接截图放 PPT 里够用了。2.3 目录结构长什么样拿到源码后先别急着跑花两分钟把目录看一遍后面改代码时能少走弯路。典型的目录组织是这样的classroom_behavior/ ├── configs/ │ └── default.yaml # 模型路径、阈值、抽帧间隔等配置 ├── models/ │ ├── detector/ # 检测模型权重与加载代码 │ └── classifier/ # 行为分类模型权重与加载代码 ├── src/ │ ├── video_reader.py # 视频解码与抽帧 │ ├── detector.py # 人体检测封装 │ ├── classifier.py # 行为分类封装 │ ├── tracker.py # 简易目标跟踪给每个学生分配 ID │ └── statistics.py # 行为统计与报表输出 ├── main.py # 主入口串起整条流水线 ├── requirements.txt └── outputs/ # 运行结果默认落这里configs/default.yaml是改参数的第一站模型路径、置信度阈值、抽帧间隔都在这。src/tracker.py容易被忽略但它决定了同一个学生在不同帧里能不能被认成同一个人后面统计时长全靠它。outputs/目录不用手动建主流程里会判断是否存在并自动创建。3. 把项目跑起来环境、配置与第一次推理3.1 环境准备与依赖安装先确认 Python 版本这类项目一般要求 3.8 以上太低的话某些深度学习库的轮子装不上。建议单独建虚拟环境避免和系统里其他项目的依赖打架# 创建并激活虚拟环境 python -m venv venv source venv/bin/activate # Windows 下用 venv\Scripts\activate # 安装依赖 pip install -r requirements.txtrequirements.txt里通常包含 opencv-python、numpy、pandas、torch 或 onnxruntime、pyyaml 这几样。如果装 torch 时卡在下载上常见做法是先装 CPU 版本课堂行为分析对实时性要求没那么高CPU 推理完全能接受。装完后跑一句python -c import cv2, torch; print(cv2.__version__)验证一下能打印出版本号就说明基础环境通了。3.2 配置文件怎么改配置文件是 YAML 格式改之前先备份一份血泪经验是直接改原文件改崩了还得重下。关键字段大概长这样video: path: data/demo_classroom.mp4 # 输入视频路径 frame_interval: 5 # 每 5 帧取 1 帧降低计算量 detector: model_path: models/detector/model.onnx conf_threshold: 0.45 # 检测置信度阈值 classifier: model_path: models/classifier/model.onnx input_size: [224, 224] # 分类模型输入尺寸 output: dir: outputs save_annotated_video: true # 是否输出带标注的视频frame_interval是最值得先调的参数。设成 1 就是逐帧处理精度最高但慢设成 5 到 10 能明显提速行为统计本来就是看趋势丢几帧不影响结论。conf_threshold调低会检出更多人但也更多误检课堂后排小人多一般 0.4 到 0.5 之间比较稳。3.3 主流程代码逐段拆解main.py是整个项目的入口逻辑不复杂但几个关键点值得逐段看。第一段是初始化和读配置import yaml from src.video_reader import VideoReader from src.detector import Detector from src.classifier import BehaviorClassifier from src.tracker import SimpleTracker from src.statistics import BehaviorStatistics # 加载配置 with open(configs/default.yaml, r, encodingutf-8) as f: cfg yaml.safe_load(f) # 初始化各模块 reader VideoReader(cfg[video][path], cfg[video][frame_interval]) detector Detector(cfg[detector][model_path], cfg[detector][conf_threshold]) classifier BehaviorClassifier(cfg[classifier][model_path], cfg[classifier][input_size]) tracker SimpleTracker() stats BehaviorStatistics()这段的作用是把配置里的路径和阈值喂给各个模块的构造函数。注意VideoReader第二个参数是抽帧间隔它内部会在read()时按这个间隔跳帧而不是先把所有帧读进内存再筛这样长视频也不会把内存撑爆。第二段是主循环逐帧检测、分类、跟踪for frame, timestamp in reader.frames(): # 1. 检测人体框 boxes detector.detect(frame) # 2. 给每个框分配跟踪 ID tracked tracker.update(boxes, frame) # 3. 逐个裁剪并分类行为 for obj in tracked: crop frame[obj[y1]:obj[y2], obj[x1]:obj[x2]] label, score classifier.predict(crop) # 4. 记录该学生在该时间点的行为 stats.record(obj[track_id], timestamp, label, score)detector.detect返回的是[x1, y1, x2, y2, conf]格式的列表tracker.update负责把当前帧的框和上一帧的框做匹配匹配上就沿用旧 ID匹配不上就分配新 ID。分类时只裁人体框区域送进模型不送整帧这样模型看到的输入更聚焦准确率会高一些。stats.record每帧记一条最后统一汇总。第三段是收尾输出# 汇总并输出报表 stats.summarize() stats.to_csv(f{cfg[output][dir]}/behavior_report.csv) stats.plot_distribution(f{cfg[output][dir]}/distribution.png) print(处理完成结果已写入 outputs 目录)summarize()会把逐帧记录按track_id分组合并连续相同行为的时间段算出每个学生的各类行为总时长和占比。to_csv输出明细表plot_distribution画一张行为分布柱状图答辩时直接能用。3.4 第一次运行的验证方法跑之前先拿一段短一点的视频试比如一两分钟的片段确认整条链路通了再上完整录像。运行命令就是python main.py如果配置里视频路径写的是相对路径注意要在项目根目录下执行。跑完后看outputs/目录有behavior_report.csv说明统计通了有distribution.png说明画图也通了。如果开了save_annotated_video还会多一个带框和标签的视频拿它肉眼核对几帧看看框有没有框偏、标签有没有明显错得离谱这是最快的验证方式。4. 核心模块拆解检测、跟踪与行为分类的关键实现4.1 视频解码与抽帧的细节VideoReader看起来简单但有两个坑要提前说。第一个是帧率换算OpenCV 拿到的CAP_PROP_FPS有时候不准尤其是经过转码的视频常见做法是用CAP_PROP_FRAME_COUNT除以时长做交叉验证。第二个是时间戳不要用“帧序号除以帧率”硬算最好用CAP_PROP_POS_MSEC拿真实时间戳避免可变帧率视频算出来的时间对不上。import cv2 class VideoReader: def __init__(self, path, interval5): self.cap cv2.VideoCapture(path) self.interval interval self.fps self.cap.get(cv2.CAP_PROP_FPS) def frames(self): idx 0 while True: ret, frame self.cap.read() if not ret: break if idx % self.interval 0: # 用真实时间戳单位毫秒转秒 ts self.cap.get(cv2.CAP_PROP_POS_MSEC) / 1000.0 yield frame, ts idx 1 self.cap.release()interval控制抽帧密度ts是这一帧对应的秒数后面统计时长全靠它。注意yield是生成器写法调用方用for frame, ts in reader.frames()就能边读边处理不会一次性把视频读进内存。4.2 检测与跟踪给每个学生一个稳定 ID检测模块本身是调模型没什么好改的真正影响统计结果的是跟踪。课堂场景下学生基本坐着不动但检测框会抖如果每帧都当新目标统计出来就是一堆碎片。SimpleTracker用 IoU 匹配加位置预测的思路逻辑不复杂但够用class SimpleTracker: def __init__(self, iou_threshold0.3, max_lost10): self.tracks {} # track_id - 最近一次框 self.next_id 0 self.iou_threshold iou_threshold self.max_lost max_lost # 连续多少帧没匹配上就丢弃 def update(self, boxes, frame): matched [] used set() for tid, last_box in list(self.tracks.items()): best_iou, best_idx 0, -1 for i, box in enumerate(boxes): if i in used: continue iou self._iou(last_box, box) if iou best_iou: best_iou, best_idx iou, i if best_iou self.iou_threshold: self.tracks[tid] boxes[best_idx] matched.append({track_id: tid, **self._to_dict(boxes[best_idx])}) used.add(best_idx) # 未匹配的框分配新 ID for i, box in enumerate(boxes): if i not in used: self.tracks[self.next_id] box matched.append({track_id: self.next_id, **self._to_dict(box)}) self.next_id 1 return matchediou_threshold调高会让匹配更严格学生稍微动一下就可能断 ID调低则容易把相邻两个学生匹配混。课堂场景 0.3 左右比较合适。max_lost是给短暂遮挡留的后悔药学生低头捡笔被桌子挡住几帧ID 不会立刻丢。_iou和_to_dict是辅助方法分别算交并比和把框转成字典实现不复杂但建议单独写别塞进主循环里。4.3 行为分类的输入预处理分类模型对输入很敏感裁剪出来的人体框直接 resize 到 224×224 往往效果一般因为长宽比被拉变形了。常见做法是先按比例缩放再补边保持人体不变形import cv2 import numpy as np def preprocess(crop, input_size(224, 224)): h, w crop.shape[:2] scale min(input_size[0] / w, input_size[1] / h) new_w, new_h int(w * scale), int(h * scale) resized cv2.resize(crop, (new_w, new_h)) canvas np.zeros((input_size[1], input_size[0], 3), dtypenp.uint8) # 居中放置空白处补零 top (input_size[1] - new_h) // 2 left (input_size[0] - new_w) // 2 canvas[top:top new_h, left:left new_w] resized # BGR 转 RGB 并归一化 canvas cv2.cvtColor(canvas, cv2.COLOR_BGR2RGB).astype(np.float32) / 255.0 return canvasscale取宽高缩放比例里较小的那个保证整张图都能塞进目标尺寸。补零而不是补灰是因为多数分类模型训练时用的就是零填充保持一致能少踩一个精度坑。归一化到 0 到 1 之后还要不要减均值除方差取决于模型训练时的预处理这个得看模型说明别想当然。4.4 统计模块把逐帧标签变成行为时长统计模块的核心是把“第几秒是什么行为”的流水记录合并成“某学生某行为持续了多少秒”。直接按帧数乘间隔会不准因为抽帧间隔固定但视频帧率可能变所以统一用时间戳算import pandas as pd class BehaviorStatistics: def __init__(self): self.records [] def record(self, track_id, timestamp, label, score): self.records.append({ track_id: track_id, timestamp: timestamp, behavior: label, score: score }) def summarize(self): df pd.DataFrame(self.records).sort_values([track_id, timestamp]) # 相邻记录时间差作为该行为的持续时长 df[duration] df.groupby(track_id)[timestamp].diff().fillna(0) self.summary df.groupby([track_id, behavior])[duration].sum().reset_index() total self.summary.groupby(track_id)[duration].transform(sum) self.summary[ratio] self.summary[duration] / total return self.summarydiff()算的是同一学生相邻两条记录的时间差也就是上一条行为持续了多久。最后一条记录的时长会是 0因为后面没有记录可减这个误差在长视频里可以忽略追求精确的话可以在收尾时补一个视频总时长。ratio是行为占比答辩时最有说服力的就是这个数。5. 避坑与常见问题跑不通时先查这几处5.1 检测框抖动导致 ID 频繁切换现象是统计报表里学生数量远多于实际人数每个“学生”只出现几秒。原因多半是检测框在相邻帧之间位置跳变IoU 低于阈值跟踪器认不出是同一人。解决办法有两个一是把iou_threshold从 0.3 降到 0.2 左右给匹配留点余量二是在检测后加一个简单的框平滑用当前框和上一帧框做加权平均再送进跟踪器。我一般先调阈值不行再加平滑两步都试过基本能压住。5.2 分类结果全是同一类现象是报表里所有学生都是“听讲”其他行为一个没有。先别怀疑模型坏了大概率是预处理和训练时不一致。检查三处输入是不是 RGBOpenCV 默认 BGR、有没有做归一化、补边方式是不是和训练一致。另一个常见原因是裁剪框把学生裁得太紧只剩个脑袋模型看不到手部动作自然分不出“低头写字”。把框往外扩 10% 到 15% 再裁往往就正常了。5.3 长视频跑到一半内存爆掉现象是处理几分钟的视频没事上完整四十分钟录像时进程被系统杀掉。原因是某处把帧或记录全存内存了。检查VideoReader是不是用了read()一次性读完以及records列表是不是无限增长。前者改成生成器逐帧读后者可以每处理一千条就落一次盘再清空。另外save_annotated_video开着的时候视频写入器没及时释放也会占内存确认release()在异常分支里也调用了。5.4 时间戳对不上导致时长算错现象是统计出来的总时长和视频实际长度差很多。原因通常是用了帧序号除以帧率来算时间而视频实际帧率不稳定。改成用CAP_PROP_POS_MSEC拿真实时间戳并且在summarize里用时间差而不是帧数差算时长。还有一个隐蔽的坑抽帧间隔设成 5 时相邻两条记录的时间差是 5 帧对应的秒数这个没问题但如果中间有丢帧时间差会突然变大属于正常现象不用当 bug 修。5.5 模型文件路径在 Windows 下报错现象是 Linux 下跑得好好的换到 Windows 提示找不到模型。原因是配置里写的是正斜杠相对路径而某些加载库对路径分隔符敏感。解决办法是配置里统一用正斜杠加载时用os.path.normpath转一下或者干脆在代码里用pathlib.Path拼路径。另外注意工作目录python main.py和python src/main.py的工作目录不一样相对路径解析结果也不同统一从项目根目录执行最稳。6. 二次开发换模型、加行为类别与验证改造效果拿到这套代码后最常见的改造方向有三个换更准的检测模型、加新的行为类别、把统计结果接到别的系统里。换检测模型时只要新模型的输出能转成[x1, y1, x2, y2, conf]格式detector.py里改一下加载和推理部分就行跟踪和统计完全不用动。加行为类别要动两处分类模型的输出维度以及statistics.py里行为名称的映射表改完记得拿一段标注过的视频重新验证别直接上生产。验证改造效果我一般用一个小脚本抽几十帧人工标一下真实行为和模型输出对比算个简单准确率# 简易验证对比人工标注与模型输出 import pandas as pd gt pd.read_csv(data/manual_labels.csv) # 人工标注frame_id, behavior pred pd.read_csv(outputs/behavior_report.csv) # 按帧对齐后统计一致率 merged gt.merge(pred, onframe_id, suffixes(_gt, _pred)) acc (merged[behavior_gt] merged[behavior_pred]).mean() print(f行为一致率: {acc:.2%})这个脚本不追求严谨的评估指标就是快速看改造有没有把效果改坏。如果一致率比改造前还低先回退再逐项排查别在错误的方向上继续加功能。还有一个容易被忽略的改造点把outputs/里的 CSV 接到可视化看板上。毕设答辩时一张静态柱状图说服力有限如果能按时间轴画出每个学生的行为色带图评委一眼就能看懂。用 matplotlib 的imshow把行为序列转成颜色矩阵就行几十行代码的事但展示效果提升明显。最后说个我自己的习惯。每次改完模型或参数我都会先拿同一段固定视频跑一遍把输出 CSV 存成带日期的备份再和上一版对比。有次调阈值把检出率调高了报表里学生数翻了一倍差点当成效果提升一对比才发现全是重复 ID。从那以后我每次改完都强制走一遍固定视频回归确认学生数、总时长、行为分布三项没异常再往下做。希望这套拆解能帮你少走几步弯路把项目跑起来、改下去。本文还有配套的精品资源点击获取
简介这份资源是面向教育技术方向学生与毕业设计学习者的课堂行为智能分析软件项目通过AI与计算机视觉技术对课堂视频或智能设备采集的数据进行学生行为检测与参与度量化为教学效果评估提供参考。压缩包共760个文件以631个Python源码为核心辅以67个pyc编译文件、22张png与9张jpg界面素材、4个ui界面文件及若干txt、xml配置说明整体约28.71MB目录涵盖分析模块、界面资源与配置数据便于按模块研读。目前已有879人学习下载适合作为完整项目案例参考。读者可从中了解需求分析、行为识别算法集成、后端处理与前端交互的完整开发流程并借助现有代码结构进行二次开发需注意其中腾讯语音识别接口已过期可借此练习接口替换与功能维护积累技术迭代的应对经验。1. 课堂行为ST自动分析软件从一段课堂录像到一份行为统计表带过毕业设计的同学大概都遇到过这种场景导师丢来一段四十分钟的教室监控录像说“你把这个课上学生的行为统计一下看看谁在听、谁在走神、谁在低头”。人工一帧帧看看完眼睛就废了。这个项目就是冲着这个痛点来的——输入一段课堂视频自动识别并统计学生的行为类别输出每类行为的时长占比和分布。它适合两类人一类是正在做毕业设计、需要一套能跑通的行为识别流水线的学生另一类是手里有课堂录像、想快速拿到行为统计结果的一线教师或教研人员。技术栈上走的是 Python OpenCV 深度学习分类模型的组合整体结构不复杂但把“视频解码—目标检测—行为分类—统计输出”这条链路串完整了拿来当毕设骨架或者二次开发底座都够用。2. 项目整体架构一条从视频帧到统计报表的处理流水线2.1 模块划分与数据流向这个软件的核心思路是把“看视频”拆成四个可独立调试的阶段每个阶段只干一件事出了问题能快速定位是哪一环翻车。整体数据流是这样的视频文件先被解码成帧序列帧序列送进检测模块定位出每个学生的人体框人体框裁剪后送进行为分类模型得到行为标签最后统计模块按时间轴汇总每个学生的行为序列并输出报表。模块划分大致如下模块职责关键依赖视频解码模块读取视频、抽帧、时间戳对齐OpenCV目标检测模块定位画面中的学生人体框轻量检测模型行为分类模块对每个人体框判定行为类别图像分类模型统计输出模块按学生 ID 汇总行为时长、生成报表pandas这种拆法的好处是每个模块都能单独替换。比如检测模型换成更轻的版本或者分类模型换成自己训练的权重只要保持输入输出接口一致其他模块不用动。常见做法是把每个模块封装成一个类主流程里按顺序调用模块之间通过 numpy 数组和字典传递数据不搞复杂的消息队列。2.2 技术选型背后的取舍为什么用 OpenCV 而不是别的视频库因为课堂录像大多是 mp4 或 avi 格式OpenCV 的VideoCapture对这两种格式支持最稳而且抽帧时能直接拿到帧率信息方便后面把“第几帧”换算成“第几秒”。检测和分类没有用特别重的模型原因是课堂场景下人体目标密集、遮挡多太重的小模型跑不动太轻的又漏检折中选了能在普通笔记本 CPU 上跑到可接受帧率的轻量方案。统计部分用 pandas 是因为行为序列本质上是带时间戳的表格数据按学生 ID 分组、按时间排序、算时长占比这些操作 pandas 几行就能写完自己手写循环反而容易出错。整个项目没有引入 Web 框架输出就是 CSV 和几张统计图毕设答辩时直接截图放 PPT 里够用了。2.3 目录结构长什么样拿到源码后先别急着跑花两分钟把目录看一遍后面改代码时能少走弯路。典型的目录组织是这样的classroom_behavior/ ├── configs/ │ └── default.yaml # 模型路径、阈值、抽帧间隔等配置 ├── models/ │ ├── detector/ # 检测模型权重与加载代码 │ └── classifier/ # 行为分类模型权重与加载代码 ├── src/ │ ├── video_reader.py # 视频解码与抽帧 │ ├── detector.py # 人体检测封装 │ ├── classifier.py # 行为分类封装 │ ├── tracker.py # 简易目标跟踪给每个学生分配 ID │ └── statistics.py # 行为统计与报表输出 ├── main.py # 主入口串起整条流水线 ├── requirements.txt └── outputs/ # 运行结果默认落这里configs/default.yaml是改参数的第一站模型路径、置信度阈值、抽帧间隔都在这。src/tracker.py容易被忽略但它决定了同一个学生在不同帧里能不能被认成同一个人后面统计时长全靠它。outputs/目录不用手动建主流程里会判断是否存在并自动创建。3. 把项目跑起来环境、配置与第一次推理3.1 环境准备与依赖安装先确认 Python 版本这类项目一般要求 3.8 以上太低的话某些深度学习库的轮子装不上。建议单独建虚拟环境避免和系统里其他项目的依赖打架# 创建并激活虚拟环境 python -m venv venv source venv/bin/activate # Windows 下用 venv\Scripts\activate # 安装依赖 pip install -r requirements.txtrequirements.txt里通常包含 opencv-python、numpy、pandas、torch 或 onnxruntime、pyyaml 这几样。如果装 torch 时卡在下载上常见做法是先装 CPU 版本课堂行为分析对实时性要求没那么高CPU 推理完全能接受。装完后跑一句python -c import cv2, torch; print(cv2.__version__)验证一下能打印出版本号就说明基础环境通了。3.2 配置文件怎么改配置文件是 YAML 格式改之前先备份一份血泪经验是直接改原文件改崩了还得重下。关键字段大概长这样video: path: data/demo_classroom.mp4 # 输入视频路径 frame_interval: 5 # 每 5 帧取 1 帧降低计算量 detector: model_path: models/detector/model.onnx conf_threshold: 0.45 # 检测置信度阈值 classifier: model_path: models/classifier/model.onnx input_size: [224, 224] # 分类模型输入尺寸 output: dir: outputs save_annotated_video: true # 是否输出带标注的视频frame_interval是最值得先调的参数。设成 1 就是逐帧处理精度最高但慢设成 5 到 10 能明显提速行为统计本来就是看趋势丢几帧不影响结论。conf_threshold调低会检出更多人但也更多误检课堂后排小人多一般 0.4 到 0.5 之间比较稳。3.3 主流程代码逐段拆解main.py是整个项目的入口逻辑不复杂但几个关键点值得逐段看。第一段是初始化和读配置import yaml from src.video_reader import VideoReader from src.detector import Detector from src.classifier import BehaviorClassifier from src.tracker import SimpleTracker from src.statistics import BehaviorStatistics # 加载配置 with open(configs/default.yaml, r, encodingutf-8) as f: cfg yaml.safe_load(f) # 初始化各模块 reader VideoReader(cfg[video][path], cfg[video][frame_interval]) detector Detector(cfg[detector][model_path], cfg[detector][conf_threshold]) classifier BehaviorClassifier(cfg[classifier][model_path], cfg[classifier][input_size]) tracker SimpleTracker() stats BehaviorStatistics()这段的作用是把配置里的路径和阈值喂给各个模块的构造函数。注意VideoReader第二个参数是抽帧间隔它内部会在read()时按这个间隔跳帧而不是先把所有帧读进内存再筛这样长视频也不会把内存撑爆。第二段是主循环逐帧检测、分类、跟踪for frame, timestamp in reader.frames(): # 1. 检测人体框 boxes detector.detect(frame) # 2. 给每个框分配跟踪 ID tracked tracker.update(boxes, frame) # 3. 逐个裁剪并分类行为 for obj in tracked: crop frame[obj[y1]:obj[y2], obj[x1]:obj[x2]] label, score classifier.predict(crop) # 4. 记录该学生在该时间点的行为 stats.record(obj[track_id], timestamp, label, score)detector.detect返回的是[x1, y1, x2, y2, conf]格式的列表tracker.update负责把当前帧的框和上一帧的框做匹配匹配上就沿用旧 ID匹配不上就分配新 ID。分类时只裁人体框区域送进模型不送整帧这样模型看到的输入更聚焦准确率会高一些。stats.record每帧记一条最后统一汇总。第三段是收尾输出# 汇总并输出报表 stats.summarize() stats.to_csv(f{cfg[output][dir]}/behavior_report.csv) stats.plot_distribution(f{cfg[output][dir]}/distribution.png) print(处理完成结果已写入 outputs 目录)summarize()会把逐帧记录按track_id分组合并连续相同行为的时间段算出每个学生的各类行为总时长和占比。to_csv输出明细表plot_distribution画一张行为分布柱状图答辩时直接能用。3.4 第一次运行的验证方法跑之前先拿一段短一点的视频试比如一两分钟的片段确认整条链路通了再上完整录像。运行命令就是python main.py如果配置里视频路径写的是相对路径注意要在项目根目录下执行。跑完后看outputs/目录有behavior_report.csv说明统计通了有distribution.png说明画图也通了。如果开了save_annotated_video还会多一个带框和标签的视频拿它肉眼核对几帧看看框有没有框偏、标签有没有明显错得离谱这是最快的验证方式。4. 核心模块拆解检测、跟踪与行为分类的关键实现4.1 视频解码与抽帧的细节VideoReader看起来简单但有两个坑要提前说。第一个是帧率换算OpenCV 拿到的CAP_PROP_FPS有时候不准尤其是经过转码的视频常见做法是用CAP_PROP_FRAME_COUNT除以时长做交叉验证。第二个是时间戳不要用“帧序号除以帧率”硬算最好用CAP_PROP_POS_MSEC拿真实时间戳避免可变帧率视频算出来的时间对不上。import cv2 class VideoReader: def __init__(self, path, interval5): self.cap cv2.VideoCapture(path) self.interval interval self.fps self.cap.get(cv2.CAP_PROP_FPS) def frames(self): idx 0 while True: ret, frame self.cap.read() if not ret: break if idx % self.interval 0: # 用真实时间戳单位毫秒转秒 ts self.cap.get(cv2.CAP_PROP_POS_MSEC) / 1000.0 yield frame, ts idx 1 self.cap.release()interval控制抽帧密度ts是这一帧对应的秒数后面统计时长全靠它。注意yield是生成器写法调用方用for frame, ts in reader.frames()就能边读边处理不会一次性把视频读进内存。4.2 检测与跟踪给每个学生一个稳定 ID检测模块本身是调模型没什么好改的真正影响统计结果的是跟踪。课堂场景下学生基本坐着不动但检测框会抖如果每帧都当新目标统计出来就是一堆碎片。SimpleTracker用 IoU 匹配加位置预测的思路逻辑不复杂但够用class SimpleTracker: def __init__(self, iou_threshold0.3, max_lost10): self.tracks {} # track_id - 最近一次框 self.next_id 0 self.iou_threshold iou_threshold self.max_lost max_lost # 连续多少帧没匹配上就丢弃 def update(self, boxes, frame): matched [] used set() for tid, last_box in list(self.tracks.items()): best_iou, best_idx 0, -1 for i, box in enumerate(boxes): if i in used: continue iou self._iou(last_box, box) if iou best_iou: best_iou, best_idx iou, i if best_iou self.iou_threshold: self.tracks[tid] boxes[best_idx] matched.append({track_id: tid, **self._to_dict(boxes[best_idx])}) used.add(best_idx) # 未匹配的框分配新 ID for i, box in enumerate(boxes): if i not in used: self.tracks[self.next_id] box matched.append({track_id: self.next_id, **self._to_dict(box)}) self.next_id 1 return matchediou_threshold调高会让匹配更严格学生稍微动一下就可能断 ID调低则容易把相邻两个学生匹配混。课堂场景 0.3 左右比较合适。max_lost是给短暂遮挡留的后悔药学生低头捡笔被桌子挡住几帧ID 不会立刻丢。_iou和_to_dict是辅助方法分别算交并比和把框转成字典实现不复杂但建议单独写别塞进主循环里。4.3 行为分类的输入预处理分类模型对输入很敏感裁剪出来的人体框直接 resize 到 224×224 往往效果一般因为长宽比被拉变形了。常见做法是先按比例缩放再补边保持人体不变形import cv2 import numpy as np def preprocess(crop, input_size(224, 224)): h, w crop.shape[:2] scale min(input_size[0] / w, input_size[1] / h) new_w, new_h int(w * scale), int(h * scale) resized cv2.resize(crop, (new_w, new_h)) canvas np.zeros((input_size[1], input_size[0], 3), dtypenp.uint8) # 居中放置空白处补零 top (input_size[1] - new_h) // 2 left (input_size[0] - new_w) // 2 canvas[top:top new_h, left:left new_w] resized # BGR 转 RGB 并归一化 canvas cv2.cvtColor(canvas, cv2.COLOR_BGR2RGB).astype(np.float32) / 255.0 return canvasscale取宽高缩放比例里较小的那个保证整张图都能塞进目标尺寸。补零而不是补灰是因为多数分类模型训练时用的就是零填充保持一致能少踩一个精度坑。归一化到 0 到 1 之后还要不要减均值除方差取决于模型训练时的预处理这个得看模型说明别想当然。4.4 统计模块把逐帧标签变成行为时长统计模块的核心是把“第几秒是什么行为”的流水记录合并成“某学生某行为持续了多少秒”。直接按帧数乘间隔会不准因为抽帧间隔固定但视频帧率可能变所以统一用时间戳算import pandas as pd class BehaviorStatistics: def __init__(self): self.records [] def record(self, track_id, timestamp, label, score): self.records.append({ track_id: track_id, timestamp: timestamp, behavior: label, score: score }) def summarize(self): df pd.DataFrame(self.records).sort_values([track_id, timestamp]) # 相邻记录时间差作为该行为的持续时长 df[duration] df.groupby(track_id)[timestamp].diff().fillna(0) self.summary df.groupby([track_id, behavior])[duration].sum().reset_index() total self.summary.groupby(track_id)[duration].transform(sum) self.summary[ratio] self.summary[duration] / total return self.summarydiff()算的是同一学生相邻两条记录的时间差也就是上一条行为持续了多久。最后一条记录的时长会是 0因为后面没有记录可减这个误差在长视频里可以忽略追求精确的话可以在收尾时补一个视频总时长。ratio是行为占比答辩时最有说服力的就是这个数。5. 避坑与常见问题跑不通时先查这几处5.1 检测框抖动导致 ID 频繁切换现象是统计报表里学生数量远多于实际人数每个“学生”只出现几秒。原因多半是检测框在相邻帧之间位置跳变IoU 低于阈值跟踪器认不出是同一人。解决办法有两个一是把iou_threshold从 0.3 降到 0.2 左右给匹配留点余量二是在检测后加一个简单的框平滑用当前框和上一帧框做加权平均再送进跟踪器。我一般先调阈值不行再加平滑两步都试过基本能压住。5.2 分类结果全是同一类现象是报表里所有学生都是“听讲”其他行为一个没有。先别怀疑模型坏了大概率是预处理和训练时不一致。检查三处输入是不是 RGBOpenCV 默认 BGR、有没有做归一化、补边方式是不是和训练一致。另一个常见原因是裁剪框把学生裁得太紧只剩个脑袋模型看不到手部动作自然分不出“低头写字”。把框往外扩 10% 到 15% 再裁往往就正常了。5.3 长视频跑到一半内存爆掉现象是处理几分钟的视频没事上完整四十分钟录像时进程被系统杀掉。原因是某处把帧或记录全存内存了。检查VideoReader是不是用了read()一次性读完以及records列表是不是无限增长。前者改成生成器逐帧读后者可以每处理一千条就落一次盘再清空。另外save_annotated_video开着的时候视频写入器没及时释放也会占内存确认release()在异常分支里也调用了。5.4 时间戳对不上导致时长算错现象是统计出来的总时长和视频实际长度差很多。原因通常是用了帧序号除以帧率来算时间而视频实际帧率不稳定。改成用CAP_PROP_POS_MSEC拿真实时间戳并且在summarize里用时间差而不是帧数差算时长。还有一个隐蔽的坑抽帧间隔设成 5 时相邻两条记录的时间差是 5 帧对应的秒数这个没问题但如果中间有丢帧时间差会突然变大属于正常现象不用当 bug 修。5.5 模型文件路径在 Windows 下报错现象是 Linux 下跑得好好的换到 Windows 提示找不到模型。原因是配置里写的是正斜杠相对路径而某些加载库对路径分隔符敏感。解决办法是配置里统一用正斜杠加载时用os.path.normpath转一下或者干脆在代码里用pathlib.Path拼路径。另外注意工作目录python main.py和python src/main.py的工作目录不一样相对路径解析结果也不同统一从项目根目录执行最稳。6. 二次开发换模型、加行为类别与验证改造效果拿到这套代码后最常见的改造方向有三个换更准的检测模型、加新的行为类别、把统计结果接到别的系统里。换检测模型时只要新模型的输出能转成[x1, y1, x2, y2, conf]格式detector.py里改一下加载和推理部分就行跟踪和统计完全不用动。加行为类别要动两处分类模型的输出维度以及statistics.py里行为名称的映射表改完记得拿一段标注过的视频重新验证别直接上生产。验证改造效果我一般用一个小脚本抽几十帧人工标一下真实行为和模型输出对比算个简单准确率# 简易验证对比人工标注与模型输出 import pandas as pd gt pd.read_csv(data/manual_labels.csv) # 人工标注frame_id, behavior pred pd.read_csv(outputs/behavior_report.csv) # 按帧对齐后统计一致率 merged gt.merge(pred, onframe_id, suffixes(_gt, _pred)) acc (merged[behavior_gt] merged[behavior_pred]).mean() print(f行为一致率: {acc:.2%})这个脚本不追求严谨的评估指标就是快速看改造有没有把效果改坏。如果一致率比改造前还低先回退再逐项排查别在错误的方向上继续加功能。还有一个容易被忽略的改造点把outputs/里的 CSV 接到可视化看板上。毕设答辩时一张静态柱状图说服力有限如果能按时间轴画出每个学生的行为色带图评委一眼就能看懂。用 matplotlib 的imshow把行为序列转成颜色矩阵就行几十行代码的事但展示效果提升明显。最后说个我自己的习惯。每次改完模型或参数我都会先拿同一段固定视频跑一遍把输出 CSV 存成带日期的备份再和上一版对比。有次调阈值把检出率调高了报表里学生数翻了一倍差点当成效果提升一对比才发现全是重复 ID。从那以后我每次改完都强制走一遍固定视频回归确认学生数、总时长、行为分布三项没异常再往下做。希望这套拆解能帮你少走几步弯路把项目跑起来、改下去。本文还有配套的精品资源点击获取
