数据质检
配套页面:控制台的「数据质检」页签 质检器:webapp/dataqc.py(版本 2.0,只读,进程内调用)
1. 为什么要质检#
第 8 章说了怎么把数据录下来。但录下来 ≠ 能用。
一段数据里可能有几帧时间戳倒退、某一路相机整段没写进去、视频比 parquet 少 3 帧、机械臂整段没动。这些问题在录制时看不出来(页面只显示"已保存 600 帧"),但训练时会把模型带偏:
| 数据里的问题 | 训练时会怎样 |
|---|---|
| 时间戳乱序 / 空洞 | 训练样本的先后关系错乱,模型学到"倒放"或"跳帧"的动作 |
| 某一路相机缺失 | 该模态在该批次是空值,模型学会忽略它,或者干脆学不会 |
| 视频与关节差半拍 | 图像和动作对不上,模型学到"看着左边、抓向右边" |
| 关节角整段不变 | 一段"机械臂没动"的示教被当成有效动作,模型学到"停在原地" |
| 关节角尖刺 / 越限 | 模型把传感器毛刺当成动作,执行时抖动或撞限位 |
而且这些问题不会报错——训练照样能跑完,只是效果差一点。等你发现"模型怎么学不会"时,已经浪费了几个小时。所以录完就质检,别等训练。
一句话:质检是把"看起来正常"的数据变成"可以证明正常"的数据。
2. 质检器检查什么#
本项目只产生三类需要检查的数据:
- RGB 视频帧:每路相机 mp4 的帧数、分辨率、fps、重复帧、全黑/无纹理;
- 关节角数据列:
observation.state/action的 6 个关节列; - 相关时间戳:
hardware_ns、observation.state_ns、observation.images.*_ns、timestamp。
质检器不会去查手套 / IMU / SLAM 这些本项目没有的固定列。它先从数据里发现实际存在哪些列,再按列的类型和名字决定怎么查:observation.state / action 按关节角查,
*_ns 按时间戳查,videos/ 下的 mp4 按视频帧查。某个数据集没有视频,就只查关节角和时间戳,不会因为缺手套列而报错。
2.1 检查项一览#
| 编号 | 检查项 | 查的是什么 | 判据 / 阈值 |
|---|---|---|---|
| S1 | 数据集结构 | meta/info.json、meta/episodes、data/*.parquet 是否对得上 |
缺文件 / 声明长度不符 → error;episode_index 公式不符、frame_index 不连续 → warn |
| T1 | 时间戳顺序 | 各时间戳列相邻两帧是否回退或重复 | 回退 → error;重复 >0.5% → error,否则 warn(相机列的重复交给 V2) |
| T2 | 时间戳间隔 | 帧间隔是否突然变大 | 空洞 > max(2×标称, 标称+15ms):丢 ≤9 帧 warn,丢 ≥10 帧或单洞 ≥250ms → error |
| T3 | 时钟对齐 | 相机 / state / timestamp 相对主时钟的偏移与抖动 | 相机抖动 IQR >15ms 或 p95 偏差 >25ms → warn;>40/60ms → error;稳定偏移 >50ms → warn |
| J1 | 关节角完整性 | observation.state / action 的列数、NaN、限位、state 与 action 一致性 |
维度不符 / NaN / Inf → error;越限 ≤10° 记 info,>10° warn,>20° error;action 中位差 >5° → warn |
| J2 | 关节运动质量 | 整段静止、单帧尖刺、单帧跳变 | 整段完全不变 → error;静止占比 ≥80% → warn;尖刺 → warn;单帧跳变 >20° warn、>45° error |
| V1 | RGB 视频帧 | 每路相机 mp4 的帧数、分辨率、fps、时长、能否解码 | 缺文件 / 读不动 / 帧数 ≠ parquet 行数 → error;分辨率或 fps 不符 → warn |
| V2 | 画面质量 | 重复帧、全黑、无纹理 | 重复帧 ≥2% warn、≥10% error;抽帧全黑 → error;偏暗 / 无纹理 → warn |
每一条 finding 都带 severity:
| 级别 | 含义 |
|---|---|
error |
硬缺陷,这段数据不该用 |
warn |
可疑,需要人工看一眼 |
info |
只是记账(例如"有稳定偏移""关节全程不变"),不算缺陷 |
2.2 关节角数据列#
这一段是这次改版的重点。observation.state 和 action 都是 6 维定长列表,按录制器的顺序解释:
0 shoulder_pan 1 shoulder_lift 2 elbow_flex
3 wrist_flex 4 wrist_roll 5 gripper(0–100 %)
对每一列分别统计:最小、最大、均值、标准差、跨度、越限帧数、是否全程不变。再在整段上查:
- NaN / Inf:任何一帧出现就 error;
- 维度:实际列数与
meta/info.json声明不一致就 error; - 越限:和 URDF 限位比。现场标定行程会比 URDF 宽几度,所以 ≤10° 只记 info, 10–20° 记 warn,超过 20° 才记 error;
- 整段静止:所有关节在整个 episode 里完全不变 → error(这段示教是空的);
- 单帧尖刺:一帧突然偏离前后两帧、但前后两帧彼此接近 → warn(编码器/总线毛刺);
- 单帧跳变:相邻两帧某个关节变化 >20° → warn,>45° → error;
- state 与 action:当前录制器写的是同一条关节轨迹,中位差 >5° 说明两者不是一回事,记 warn;小差异只记 info。
关节角数值很小(|q|≤3.5、跨度≤6.3)时,质检器无法确定单位是度还是弧度,会跳过限位判断并记一条 info,避免把弧度数据误判成越限。
2.3 时间戳#
主时钟优先取 hardware_ns,没有就取 timestamp / wall_time。每个时间戳列都查:
- 回退:相邻两帧时间戳变小 → error;
- 重复:相邻两帧完全相同。
hardware_ns/state_ns等主时钟重复记 T1;相机*_ns重复是"相机那一拍没出新图",交给 V2 的重复帧统计; - 空洞:帧间隔明显大于标称周期(30 fps 时 33.3 ms)→ 折算丢了几个样本;
- 偏移/抖动:把每个流换算成"相对主时钟的经过时间",看中位偏移和 IQR。稳定的固定偏移可以训练前一次性补偿;抖动大才是真正的错位。
2.4 RGB 视频帧#
对每路相机、每一段:
- 用
ffprobe -count_frames数出真实帧数,和 parquet 行数逐段比。两者必须相等——这是"按frame_index取第 k 帧画面"的前提; - 分辨率、fps、时长和
meta/info.json对; - 读相邻两行的
observation.images.<cam>_ns:相同 = 相机复用了上一帧(重复帧); - 用 OpenCV 抽 3 帧看亮度和灰度标准差,全黑 / 几乎无纹理说明镜头被挡或没出图。
3. 不同问题对训练的影响#
严重(error,建议直接剔除该段)#
| 问题 | 后果 |
|---|---|
| T1 时间戳回退 | 时间轴不再单调,任何按时间对齐的训练/回放都会错位 |
| T2 大空洞(丢 ≥10 帧) | 空洞段里动作被跳过,模型学到不连续的运动 |
| J1 关节列 NaN / 维度不符 | 训练时该列是随机值/零,模型学不会这条轨迹 |
| J1 关节严重越限(>20°) | 标定或单位有问题,数据不可信 |
| J2 整段静止 | 一段"机械臂没动"的示教是无效样本 |
| V1 视频帧数 ≠ 行数 | 第 N 行配到的不是第 N 帧,图像和动作整体错位 |
| V2 重复帧 ≥10% | 相机跑不满 30 fps,图像与动作的时间对应变差 |
| S1 结构不一致 | 加载器可能读错段,或读到别人的段 |
中等(warn,需要判断)#
| 问题 | 后果 |
|---|---|
| T1 少量时间戳重复 | 同一时刻两个样本,轻微冗余;比例高则等于采样率不实 |
| T2 小空洞(丢 1–9 帧) | 少量动作被跳过,通常可接受 |
| T3 相机抖动 | 图像与关节差半拍以上,抓取类任务最敏感 |
| J1 越限 10–20° | 可能是标定行程比 URDF 宽,也可能真的撞限位 |
| J1 action 与 state 不一致 | 目标值和测量值不是同一条轨迹,训练前要确认 |
| J2 单帧尖刺 / 跳变 | 传感器毛刺会教坏模型,执行时抖动 |
| J2 大部分时间静止 | 示教里有效动作太少,样本效率低 |
| V2 重复帧 2–10% | 少量掉帧,通常可接受 |
| V1 分辨率 / fps 不符 | 可能是重新编码过,确认没有裁帧即可 |
轻微(info,一般不影响)#
| 问题 | 后果 |
|---|---|
| 稳定的固定偏移(例如相机恒定晚 20 ms) | 只要稳定就能在训练前一次性补偿 |
| 单个关节全程不变(例如夹爪一直没动) | 这一段没用夹爪,属正常 |
| 关节角小幅越限(≤10°) | 现场标定行程与 URDF 的正常差异 |
判断标准不是"有没有 finding",而是这一段还能不能代表一次正常的示教。
4. 页面怎么用#
截图上的编号对应下面的步骤。
选数据、看数据#
| 编号 | 操作 |
|---|---|
| ① | 选数据集(下拉里带段数和总帧数),点「刷新列表」重新扫描 |
| ② | 点某一行 = 载入回放;勾选框 = 加入质检/删除;「全选」「清空选择」批量操作 |
| ③ | 「播放」开始/继续;「停止」停在这一帧,不回开头;「上一帧」「下一帧」逐帧前后挪一格(会自动暂停) |
| ④ | 进度条:拖动定位到任意时刻,画面和机械臂一起跳过去 |
| ⑤ | 左边是视频(多路并排),右边是 3D 机械臂,同一个时间轴 |
回放用的是 parquet 的 hardware_ns 做主时间轴:
- 每帧相对时间 =
(hardware_ns - 首帧) / 1e9 - 拖动进度条 → 视频
currentTime跳到同一秒,3D 用该帧的关节角做 FK - 播放时以 60 fps 推进,视频漂移超过 0.12 秒会自动纠正
所以画面里"机械臂的手在哪",和视频里"手在哪"是同一时刻,可以直接对拍。
跑质检#
| 编号 | 操作 |
|---|---|
| ⑥ | 「质检选中段」只查勾选的;「质检整个数据集」全查 |
| ⑦ | 结果表:每段一行,S1 / T1 / T2 / T3 / J1 / J2 / V1 / V2 八列(✗ 错误 / △ 警告 / i 提示 / · 无),最后一列是结论;下面列具体问题 |
| ⑧ | 历史记录:每次质检都会存档,按时间倒序;点一条把那次结果调回来 |
播放按钮点下去文字不变,旁边的状态会显示 播放中…;此时按钮置灰,按「停止」或拖进度条恢复。
历史记录存在 ~/.starm/qc_history/<数据集>-<时间>.json,刷新页面、重开浏览器都还在。列表按时间倒序(不是按数据集名),「结论」列统计的是有效结论——质检器的 error/warn
和「重复帧」超阈值的段取较大者。
点「导出 PDF」把当前范围出一份 A4 报告。报告只包含本项目的三类检查:
- 数据集概览(相机、关节列、帧数);
- 质检结论 + 逐段总表;
- 关节角数据:每段 6 个关节的最小/最大/均值/标准差/跨度/限位/越限帧/是否全程不变;
- 时间戳:每个流的中位间隔、最大间隔、回退、重复、丢帧、相对主时钟偏移;
- RGB 视频:每路相机的分辨率、fps、视频帧、parquet 行、差、时长、重复帧、亮度;
- 问题明细 + 结论与建议。
点「删除选中段」把勾选的段从数据集里彻底删掉——会同时删掉 parquet、所有视频和对应的 meta 记录,不可恢复,会弹确认框。
5. 一次完整的质检流程#
1. 数据质检页 → 选数据集
2. 点「质检整个数据集」 ← 先看整体,哪些段有问题
3. 对每个 warn/error 的段:
- 点该行载入回放
- 播一遍,对着视频和 3D 看动作是否合理
- 看下面的问题明细,判断是真缺陷还是误报
4. 勾选要剔除的段 → 「删除选中段」
5. 再跑一次质检,确认只剩通过
6. 「导出 PDF」留档(历史记录里也能随时再导一次)
先看整体、再逐段回放,比一上来就逐段看快得多——通常 7 段里只有 1–2 段需要人工判断。
6. 常见问题#
| 现象 | 原因 | 处理 |
|---|---|---|
| 旧历史记录里还是 C1–C6 | 那条记录是 1.x 通用质检器存的 | 重新跑一次就是新的 S1–V2;旧记录仍可打开 |
| 单路录制的段报 V1 | 该数据集里别的段有两路相机,这一段只有一路 | 正常现象;只看这一段的话可忽略 |
| J1 提示"越限 ≤10°" | 现场标定行程比 URDF 宽,或断电后略低于限位 | 不算缺陷;超过 10° 才需要看 |
| 关节角数值很小,J1 没判越限 | 分不清度/弧度,质检器跳过限位判断 | 确认录制时单位;本项目按度记录 |
info 级"稳定偏移" |
相机固定晚几十毫秒且稳定 | 不算缺陷,训练前一次性补偿即可 |
| 质检很快但结论全绿 | 只查了时间轴/帧数/关节数值 | 动作质量、画面模糊这些它看不出来,仍需人工回放 |
| 导出 PDF 失败 | 缺 websocket-client 或无 Chrome/Edge |
pip install websocket-client;装 Chrome |
| 删除后编号不连续 | 只删了中间的段 | 正常,episode 保留原编号;新录制接在「用过的最大编号」之后,不会复用旧号 |
| 页面 episode 号和日志对不上 | 旧版本按 0 基文件号显示 | 现在页面、日志、质检报告统一用 1 基 episode_index;日志 #18 就是质检页的 episode 18 |
| 刷新后结果没了 | 旧版本只存在内存里 | 现在会自动存档,看「历史记录」 |
质检器只读数据集,不会改任何文件;只有页面上的「删除选中段」会真正删数据。
和旧版通用质检器的关系#
早期仓库里曾有 data_qc_v1.1.3/ 通用时间轴质检器,但当前发布包已经不再包含这个目录。控制台的质检和 PDF 都使用 webapp/dataqc.py;不要再按旧路径去找它。
参考#
- 第 8 章:数据采集 —— 数据是怎么录下来的
- 代码:
webapp/dataqc.py(检查逻辑)、webapp/report_pdf.py(PDF 打印)、webapp/dataq.py(列数据集 / 载入回放 / 调质检器 / 删除) - 测试:
webapp/tests/test_dataqc.py(合成数据集覆盖关节角、视频帧、时间戳)