课堂行为检测数据集VOC+YOLO双格式解析与训练避坑指南

简介：一份面向学生课堂行为检测的VOC+YOLO格式数据集，整体覆盖5622张图片、7个行为类别（dk、dx、js、tt、xt、zl、zt），适合目标检测学习者及教育AI研究者用于课堂行为识别模型训练与评测，整体设计贴近真实教学场景。下载压缩包共2000个文件，其中1999个为VOC格式xml标注文件，另含使用说明txt，压缩包大小约268.46MB，结构清晰，便于按需筛选与批量处理。xml文件包含目标框坐标与类别信息，可借助labelImg等标注工具打开核查，也可直接配合YOLO、SSD等主流检测框架使用；目前已有1542人浏览学习，资源省去从零标注的繁琐流程，支持数据增强、格式转换及二次标注，压缩包以xml标注为主体，适合已有课堂图片的研究者快速接入训练流程，助力课堂专注度、参与度等行为分析实验落地，无论是学术实验、课程设计还是工程应用，都能降低数据准备门槛。

1. 学生课堂行为检测数据集VOC+YOLO格式：5622张双格式标注，能直接喂给YOLO也能读进Faster R-CNN

学生课堂行为检测数据集，如果你正在做课堂监控或教学督导相关的视觉项目，这套 VOC+YOLO 双格式的 5622 张标注集会省掉大半数据预处理时间。压缩包里是 5622 张 jpg 原图，每张图配套一个 Pascal VOC 的 xml 标注和一个 YOLO 的 txt 标注，覆盖 dk、dx、js、tt、xt、zl、zt 共 7 类课堂行为，类别以拼音缩写命名。

双格式是这套数据的实在优点：走 Faster R-CNN 系框架直接解析 xml，走 YOLO 系直接读 txt，不用自己写转换脚本。但双格式也要求两套标注严格对齐，我实际训练时踩过类别 ID 错位、坐标超界、空标注混入这类坑，单独看文件发现不了，训练跑到一半才暴露，非常耽误事。

适合三类人：训练课堂行为检测模型的算法工程师、做教学督导系统的开发者、缺标注数据做毕设验证的学生。拿到手先做一轮结构和数量校验再进训练，下文从文件核对讲到训练参数，再讲踩坑记录，可按顺序跟一遍。

2. 数据集构成与标注体系：5622 张图的文件结构、7 类行为语义与双格式坐标关系

2.1 先做数量和一一对应校验：解压后立刻执行的三个命令

解压 .7z 后，目录里是"使用前必读.txt"、大量 firc_class_*.xml 文件，以及同名的 jpg 和 txt 文件。命名规则是主文件名一致、仅扩展名不同，比如 firc_class_707.xml 对应 firc_class_707.jpg 和 firc_class_707.txt。这种命名方式比较省心，做数据集划分时只需要按主文件名操作，不容易把图片和标注拆散。

第一步永远是数量和配对校验。拿到任何数据集，我都先跑三个命令确认文件数对得上，再写个循环检查主文件名是否一一对应。资料说明是 5622 张 jpg、5622 个 xml、5622 个 txt，解压后第一件事就是验证这个数字：

# 统计三类文件数量，期望都是 5622 ls *.jpg | wc -l ls *.xml | wc -l ls *.txt | wc -l # 检查 jpg 与 xml、txt 是否一一对应 for f in *.jpg; do base="${f%.jpg}" [ -f "$base.xml" ] || echo "缺少 xml: $base" [ -f "$base.txt" ] || echo "缺少 txt: $base" done

这里有个容易忽略的点：这个压缩包里的 txt 是 YOLO 格式的标注文件，不是训练集/验证集的划分列表。摘要里已经写明"不包含分割路径的 txt"，所以不要按划分文件去读它。如果你之前用过一些把 train.txt、val.txt 作为路径清单的数据集，很容易在这里先入为主，我一开始也差点拿标注 txt 去当路径清单解析，白折腾一轮。

数量对上了，还要确认一批关键信息：图片尺寸是否统一、xml 里的 width/height 是否和 jpg 实际尺寸一致、txt 是否每行都是 5 列。这些信息决定了后面要不要做统一缩放，也决定了坐标归一化是否可信。尺寸一致性可以用 Python 批量扫一遍，若发现混入了不同分辨率的图，训练时就要格外注意 imgsz 的选取，这个在第 4 章会展开。

2.2 七类课堂行为标签：dk/dx/js/tt/xt/zl/zt 的语义与确认方法

这 7 个类别是拼音首字母缩写，常见对应如下。

我的习惯是拿到手先随机抽 30～50 张图，打开对应的 xml，看框的位置和人体的姿态是否与表格里的语义吻合。不要完全信任缩写推断——不同团队对"低头"和"打瞌睡"的边界定义可能不同，有人把趴在桌上算 dk，有人算 dx。如果训练集和验证集的标准不一致，mAP 再高，部署到真实教室也会翻车。抽样核对这一步，本质上是在确认标注标准的唯一性。

另外注意一个数据特点：每张图的标注框数量不固定，有的图一个人都没有（纯背景或远景教室），有的图可能一张里有十几个框。这在课堂场景里很正常，不是数据损坏，训练时把无标注图作为背景负样本即可；但做验证集时要留意，别让无目标图占比过高，否则 val 的 mAP 会被拉高，给你一个虚高的假象。

2.3 双格式坐标体系：VOC 的像素框与 YOLO 的归一化中心点

打开任意一个 xml，结构是标准的 Pascal VOC。以 firc_class_707.xml 为例：

<annotation> <filename>firc_class_707.jpg</filename> <size> <width>1280</width> <height>720</height> <depth>3</depth> </size> <object> <name>dk</name> <bndbox> <xmin>312</xmin> <ymin>188</ymin> <xmax>421</xmax> <ymax>309</ymax> </bndbox> </object> </annotation>

对应的 YOLO txt 文件里，同一个目标的一行是：

0 0.2863 0.3451 0.0852 0.1681

五个字段依次是：类别ID、归一化中心点 x、归一化中心点 y、归一化宽度、归一化高度。换算关系是一个固定公式：

cx = ((xmin + xmax) / 2) / width cy = ((ymin + ymax) / 2) / height w = (xmax - xmin) / width h = (ymax - ymin) / height

注意两点：YOLO 的坐标全部除以图片宽高做归一化，所以它和图片实际分辨率无关，训练时无论 imgsz 设多少，框都能跟着缩放；而 VOC 的坐标是原始像素值，换分辨率必须重新计算。另外 XML 里<name>是字符串类别名，txt 里是整数 ID，这个 ID 的顺序不是随意的，它必须和训练配置里的 names 列表一一对应，顺序错一位整个模型就废了，这个坑在第 3 章和第 5 章会反复提到。

3. VOC 与 YOLO 格式对齐：类别映射、坐标归一化公式与批量校验脚本

3.1 类别映射是训练的前置条件：names 顺序错一位，训练全白费

YOLO 训练时，模型并不知道 0 代表 dk 还是 dx，它只认整数 ID。这个 ID 到类别名的对应关系，完全由训练配置文件里的 names 列表决定。所以整个数据集里 txt 的类别 ID 分布，必须和 names 列表严格一致。对这套数据，标准顺序是：

names: ['dk', 'dx', 'js', 'tt', 'xt', 'zl', 'zt']

即 0=dk、1=dx、2=js、3=tt、4=xt、5=zl、6=zt。如果你自己重新生成过 txt（比如从 xml 转了一次），或者用标注工具重新导出过，就很容易出现顺序漂移——有的工具按字母序排，有的按标注时间排，出来的 txt 第一列可能就变成了另一种映射。

避免这个问题的唯一办法是脚本核对。写一个统计脚本，扫描所有 txt，统计每个类别 ID 出现的次数，再抽样用 xml 去反查类别名，两边比对：

import os from collections import Counter label_dir = 'labels' counter = Counter() for fn in os.listdir(label_dir): if not fn.endswith('.txt'): continue with open(os.path.join(label_dir, fn)) as f: for line in f: parts = line.split() if len(parts) != 5: print(f'[格式异常] {fn}: {line.strip()}') continue cls_id = int(parts[0]) counter[cls_id] += 1 print('类别ID分布:', sorted(counter.items()))

如果打印出来的 ID 最大值为 6，且 0～6 都有分布，说明 ID 范围正常；如果出现 7 或负数，说明类别映射已经漂移，需要回到 xml 重新生成。判断依据是第一列的范围，而不是空跑一遍训练看 loss——loss 下降不能证明类别映射正确，模型完全可以在错误映射下照样收敛，只是预测结果没有任何实际意义，这是典型的黑匣子陷阱。

3.2 坐标系换算：从 (xmin, ymin, xmax, ymax) 到 (cx, cy, w, h) 的完整推导

如果你需要从 xml 重新生成 txt（例如要修改某个类别的标注，或者从新标注工具导出），转换函数要先写对。基于 2.3 的公式，封装成一个函数：

def voc_to_yolo(xmin, ymin, xmax, ymax, img_w, img_h): """VOC像素坐标转YOLO归一化坐标""" cx = (xmin + xmax) / 2.0 / img_w cy = (ymin + ymax) / 2.0 / img_h w = (xmax - xmin) / img_w h = (ymax - ymin) / img_h # 防止浮点误差导致超界 cx = min(max(cx, 0.0), 1.0) cy = min(max(cy, 0.0), 1.0) w = min(max(w, 0.0), 1.0) h = min(max(h, 0.0), 1.0) return cx, cy, w, h

这里有个细节值得说：原来的框如果画出了图片边缘（标注工具允许拖出画布时常见），xmax 可能大于 width，直接套公式会得到 w>1，训练时 YOLO 会报警告甚至报错。所以函数里加了 min/max 裁剪。但这个裁剪属于"兜底"，不是"修复"——裁剪后框的面积和中心点都变了，如果越界严重，应该回去改原始标注，而不是靠裁剪糊弄。裁剪是后悔药，不是常规流程。

反向函数（验证用）同样要写对：

def yolo_to_voc(cx, cy, w, h, img_w, img_h): """YOLO归一化坐标转回VOC像素坐标""" xmin = (cx - w / 2) * img_w ymin = (cy - h / 2) * img_h xmax = (cx + w / 2) * img_w ymax = (cy + h / 2) * img_h return round(xmin, 1), round(ymin, 1), round(xmax, 1), round(ymax, 1)

3.3 批量转换与抽样反向验证：转换完必须闭环检查

当需要全量重生成 txt 时，用 XML 遍历脚本批处理：

import glob import os import xml.etree.ElementTree as ET CLASSES = ['dk', 'dx', 'js', 'tt', 'xt', 'zl', 'zt'] def convert_xml_to_yolo(xml_path, out_path): tree = ET.parse(xml_path) root = tree.getroot() img_w = int(root.find('size/width').text) img_h = int(root.find('size/height').text) lines = [] for obj in root.findall('object'): name = obj.find('name').text.strip() if name not in CLASSES: print(f'[未知类别] {xml_path}: {name}') continue cls_id = CLASSES.index(name) box = obj.find('bndbox') xmin = float(box.find('xmin').text) ymin = float(box.find('ymin').text) xmax = float(box.find('xmax').text) ymax = float(box.find('ymax').text) cx, cy, w, h = voc_to_yolo(xmin, ymin, xmax, ymax, img_w, img_h) lines.append(f'{cls_id} {cx:.6f} {cy:.6f} {w:.6f} {h:.6f}') with open(out_path, 'w') as f: f.write('\n'.join(lines)) for xml_path in glob.glob('Annotations/firc_class_*.xml'): out_path = 'labels/' + os.path.basename(xml_path).replace('.xml', '.txt') convert_xml_to_yolo(xml_path, out_path)

转换完不要直接进训练，先做闭环反向验证：随机抽 20 个文件，把新生成的 txt 用 yolo_to_voc 转回像素坐标，和 xml 里的原始 bndbox 对比，允许 1 像素以内的舍入误差。如果有任何一条对不上，说明解析逻辑或坐标类型有问题（常见的是把字符串当 int 用了，或者读 xml 时 xmin 和 ymin 顺序搞反）。这套"生成→反向解析→对比"的闭环流程，能挡住绝大部分格式类事故。

提示：这套数据集本身已经同时提供了 xml 和 txt，所以多数情况下你不需要重新转换。这个章节的价值在于：当你增删类别、重新标注、或要迁移到其他框架时，有一套可信的转换和验证工具链，而不是临时凑脚本。

4. 用 YOLO 系列训练课堂行为检测：目录编排、配置文件与参数调优

4.1 目录结构：把 5622 张图按 9:1 拆成 train/val

先按 YOLO 的习惯组织目录。原始解压目录里 jpg 和 txt 混在一起，训练前需要拆开。常见结构如下：

classroom_dataset/ ├── images/ │ ├── train/ # 约 5060 张 │ └── val/ # 约 562 张 ├── labels/ │ ├── train/ # 对应的 txt │ └── val/ └── classroom.yaml

划分脚本里最需要注意的是：图片和同名 txt 必须进同一个 split。用 shutil.move 而不是分别随机抽，否则训练时会出现图片有标注没 txt 或者反过来，YOLO 会静默跳过，导致训练数据凭空少一截。

import os, random, shutil random.seed(42) imgs = [f for f in os.listdir('images') if f.endswith('.jpg')] random.shuffle(imgs) val_n = int(len(imgs) * 0.1) val_set = set(imgs[:val_n]) for img in imgs: base = os.path.splitext(img)[0] sub = 'val' if img in val_set else 'train' shutil.move(os.path.join('images', img), os.path.join('images', sub, img)) shutil.move(os.path.join('labels', base + '.txt'), os.path.join('labels', sub, base + '.txt'))

一个实际操作建议：固定 random.seed(42)，并且划分后把 val 文件名清单存一份 txt 留档。这样复现实验时，train 和 val 的构成是可追溯的，不会因为重新划分导致两次实验的验证集不一样，对比结果失去意义。

4.2 data.yaml：names 顺序必须与 txt 类别 ID 完全一致

YOLO 训练配置是 yaml 文件，核心内容如下：

path: /data/classroom_dataset # 数据集根目录的绝对路径或相对路径 train: images/train val: images/val nc: 7 names: 0: dk 1: dx 2: js 3: tt 4: xt 5: zl 6: zt

这里 names 的书写顺序不是随意的，它就是在告诉模型"ID 0 对应 dk"。写配置时对照 3.1 节的类别映射表，跟 txt 里第一列的数字含义对齐。容易出错的操作是：从网上复制一段模板 yaml，没改 names 就开训，模型跑了一天，结果把 dk 当成了别的类别。这个错法看起来很蠢，但确实常见，因为你训练时看的是 loss 曲线，loss 在降，你不会意识到映射错了。

4.3 训练参数：imgsz、batch、epochs 与类别不均衡的应对

基础训练命令如下（以 YOLOv8 为例，其他 YOLO 版本的入口大同小异）：

yolo detect train \ data=classroom.yaml \ model=yolov8n.pt \ epochs=120 \ imgsz=640 \ batch=16 \ patience=20 \ project=runs/classroom

关键参数说明：

• imgsz：课堂场景的特点是远景、中景混杂，后排学生目标很小。如果原图分辨率高且小目标多，640 可能不够，建议试 1280；但 imgsz 翻倍，显存占用接近翻 4 倍，batch 要跟着降。我的做法是先跑一版 640 看 baseline，再用 1280 对比，两个模型在 val 上的 mAP 差距如果超过 3 个点，说明小目标增益明显，值得保留大分辨率。
• batch：根据显卡显存调整，显存不够时优先降 batch 而不是降 imgsz，因为 batch 影响的是梯度估计稳定性，imgsz 影响的是目标尺度。
• patience：120 epochs 配 20 的早停耐心值，意思是 val 指标连续 20 个 epoch 不提升就停。课堂行为类别之间相似度高（低头和打瞌睡姿态接近），收敛慢，耐心值别设太小，15 以下容易在曲线还没爬起来时就提前掐断训练。
• 类别不均衡：7 类行为里，低头、写字的出现频率远高于举手、站立。如果统计后发现某几类框数特别少，先不要急着上复杂的采样策略，最简单有效的是先跑一版 baseline，看 per-class 的 AP 差距；如果小样本类别 AP 明显拉垮，再给 loss 加类别权重，或者对少样本类别的图片做离线复制增强（上下翻转、轻微旋转），一版一版对比。

训练结束后，立即做验证并保存指标：

yolo detect val \ data=classroom.yaml \ model=runs/classroom/exp/weights/best.pt

验证输出里重点看每个类别的 AP 和整体的 mAP50、mAP50-95。mAP50-95 比 mAP50 更能反映框的定位质量，做行为检测场景，框不准会影响后续的行为统计，所以两个指标都记录，不要只看 mAP50 好看就收工。

提示：模型文件选 yolov8n 起步是为了快速验证流程和数据质量，确认数据集没问题后再换 s 或 m 版本提精度。不要一上来就最大模型，浪费时间且问题难排查。

5. 避坑与排查：类别 ID 错位、坐标越界、EXIF 旋转与样本不均衡的实战记录

训练这套课堂行为数据，我实际踩过下面几个坑，按"现象→原因→解决"记录，遇到类似问题可以直接对照排查。

5.1 标注文件层面的三个坑：来源不明先扫描，别急着训练

坑一：类别 ID 错位，训练正常收敛但验证时特定类别完全识别不出。

现象：训练 loss 正常下降，val 的 mAP50 有 0.8 以上，但把验证集图片画出来看，所有 dk 的框都标成了 dx，或者某几个类别永远不输出。原因：txt 第一列的 ID 和 classroom.yaml 的 names 顺序不一致。可能有人手工改过 txt，或者数据从其他工具导出时类别顺序被重排过。解决：训练前先跑类别 ID 扫描脚本（3.1 节那段代码），确认最大 ID 不超过 6，再随机抽 20 个 txt，打开对应 xml 人工比对类别名是否对得上。这套动作 5 分钟能完成，但能避免一次超过数小时的无效训练。

坑二：坐标越界，训练日志弹出 box 坐标警告或直接爆训练错误。

现象：训练时控制台出现 warnings，提示某些 box 中心点或宽高超出 [0,1]；严重点的会在某一个 epoch 直接报错，训练中断。原因：标注框拖出图片边界，转换脚本没做裁剪；或者 txt 里坐标位数被截断，四舍五入导致边界刚好越过 1.0。解决：写脚本扫描所有 txt，找出 w、h 大于 1 或 cx、cy 小于 0 / 大于 1 的行，输出文件名和行号，逐一回到 xml 确认是不是原始标注越界。如果是原始越界，用 3.2 节的裁剪逻辑兜底；如果是转换脚本 bug，修脚本后重新生成，不要手工去改几千个 txt。

坑三：空标注文件混入，实际训练数据量比预期少。

现象：统计发现某个类别的 AP 特别低，排查后发现训练集里有一批 txt 是空文件，对应的图片被 YOLO 当成了无目标背景，但你以为这些图片都有标注，导致实际参与该类别训练的样本远少于预期。原因：空 txt 可能来自原始标注就为空（纯背景教室），也可能来自转换脚本崩溃后留下的半成品文件。解决：解压后立刻统计空 txt 数量：

find labels -name "*.txt" -empty | wc -l

把空 txt 分成两类处理：原始就是空标注的，保留并单独放到 background 目录做负样本；转换产生的半成品，删除并重新生成。不要把所有空文件一刀切删掉，否则背景样本可能不够，模型容易把无关区域误检成目标。

5.2 数据与训练层面的两个坑：图像读取与类别权重

坑四：EXIF 旋转信息导致框和图像错位，可视化时框全偏了。

现象：训练完做预测，画在图上的人脸框位置明显不对，有的框转了 90 度，但训练 loss 一直正常。原因：教室现场用手机或相机拍摄的 jpg 经常带 EXIF 方向标记，OpenCV 的 imread 默认忽略 EXIF，按原始像素读入；而标注工具如果按 EXIF 校正后的方向显示，导出坐标就基于旋转后的图像。两套坐标系不一致，框自然错位。解决：在预处理阶段统一图像方向，用 PIL 读图并应用 exif_transpose 后再保存，同时把对应 txt 坐标按同样方向做变换；或者全流程都用同一套读取方式，禁止混用 OpenCV 和 PIL。这个坑最阴的地方在于它只影响部分图片（只有带 EXIF 标记的），所以可视化看几张正常的就放松警惕了。

坑五：样本不均衡，小类别 AP 被拉垮。

现象：整体 mAP50 有 0.85，但看 per-class AP，zl（站立）和 js（举手）可能只有 0.5 出头，而 dk、dx 这类高频类别接近 0.9。原因：课堂场景里低频行为天然少，标注也不均衡，模型把有限的学习容量都分给了高频类别。解决：先量化不均衡程度，统计每类框数；然后按 4.3 节的方法，先跑 baseline 再针对小样本类别做增强或调 loss 权重。我一般会先试类别权重方案，因为它不动原始标注；如果效果不明显，再考虑对少样本图片做复制增强。注意增强策略别乱上，横向翻转对"举手"这种对称动作没问题，对"转头"这种方向敏感动作就得谨慎，翻转后语义可能就变了。

6. 进阶验证：预测可视化和课堂行为统计时间线的两个实用脚本

模型训练完，不要只看 mAP 数字，把预测框画到原图上逐张看，再统计每个类别在每帧的出现次数，能做出一个课堂行为时间线，这个对教学督导场景最实用。用训练好的权重跑一遍 val 预测：

yolo detect predict \ model=runs/classroom/exp/weights/best.pt \ source=dataset/images/val \ save=True \ save_txt=True

save_txt=True 会把每张图的预测结果写成 txt，格式和训练标注一致。写一个小脚本按帧统计每类框数：

import glob from collections import Counter class_names = ['dk', 'dx', 'js', 'tt', 'xt', 'zl', 'zt'] timeline = {} for txt in sorted(glob.glob('runs/classroom/exp/predict/labels/*.txt')): frame = txt.split('/')[-1][:-4] c = Counter() for line in open(txt): c[int(line.split()[0])] += 1 timeline[frame] = c

把 timeline 按帧画成折线图，就能看到这节课的"行为曲线"：哪个时间段举手人数激增，哪个时间段低头占比上升。行为统计的价值不在单个框，而在群体的时间分布，这是课堂行为检测和普通目标检测的差别。

我常用的验证技巧是单独抽 50 张后排学生的裁剪图看小目标框的定位质量。课堂教室后排学生往往只有几十像素高，模型对远景小目标的表现直接决定系统实用性，这种验证比整体 mAP 更能暴露问题。如果后排误检多，优先调高 imgsz。另外，按类别挑出每类 AP 最低的 10 张图逐张排查原因：遮挡、姿态模糊还是标注本身错误。如果是标注错误，回到数据集修正后重训；如果是姿态模糊，考虑合并相似类别。

这套课堂行为数据集的完整使用流程就是解压、校验、对齐、训练、可视化验证五个环节，模型和评估结论都有据可查。从那以后我每次拿到新数据集都会强制走一遍固定流程：数量校验、类别 ID 扫描、坐标边界扫描、抽样可视化，四步全过才进训练，已经帮我挡掉了好几次数小时无效训练的损失。希望帮到你。

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