SO-101
课程总览/第 09 章 · 数据质检
EN
第 09 章数据与训练约 15 分钟

数据质检

配套页面:控制台的「数据质检」页签 质检器:webapp/dataqc.py(版本 2.0,只读,进程内调用)

7 个小节 1 张图 2 段代码 质检关节角视频帧时间戳
数据质检页

1. 为什么要质检#

第 8 章说了怎么把数据录下来。但录下来 ≠ 能用。

一段数据里可能有几帧时间戳倒退、某一路相机整段没写进去、视频比 parquet 少 3 帧、机械臂整段没动。这些问题在录制时看不出来(页面只显示"已保存 600 帧"),但训练时会把模型带偏:

数据里的问题 训练时会怎样
时间戳乱序 / 空洞 训练样本的先后关系错乱,模型学到"倒放"或"跳帧"的动作
某一路相机缺失 该模态在该批次是空值,模型学会忽略它,或者干脆学不会
视频与关节差半拍 图像和动作对不上,模型学到"看着左边、抓向右边"
关节角整段不变 一段"机械臂没动"的示教被当成有效动作,模型学到"停在原地"
关节角尖刺 / 越限 模型把传感器毛刺当成动作,执行时抖动或撞限位

而且这些问题不会报错——训练照样能跑完,只是效果差一点。等你发现"模型怎么学不会"时,已经浪费了几个小时。所以录完就质检,别等训练。

一句话:质检是把"看起来正常"的数据变成"可以证明正常"的数据。

2. 质检器检查什么#

本项目只产生三类需要检查的数据:

  1. RGB 视频帧:每路相机 mp4 的帧数、分辨率、fps、重复帧、全黑/无纹理;
  2. 关节角数据列:observation.state / action 的 6 个关节列;
  3. 相关时间戳: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 维定长列表,按录制器的顺序解释:

text
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",而是这一段还能不能代表一次正常的示教。

互动实验

质检结论模拟器

第 9 章规则

勾选这一段里真实存在的发现项,看看质检器会给出什么结论。规则照第 9 章:硬缺陷是 error,需要判断的是 warn,稳定的固定偏移只是 info。

重复帧比例(V2)0.0%
>2% warn>10% error
可以训练

没有发现硬缺陷。

暂无发现项
这是按文档规则做的教学模拟,不是 dataqc.py 本体。真实结论还要结合回放、动作合理性和任务要求判断。

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 报告。报告只包含本项目的三类检查:

  1. 数据集概览(相机、关节列、帧数);
  2. 质检结论 + 逐段总表;
  3. 关节角数据:每段 6 个关节的最小/最大/均值/标准差/跨度/限位/越限帧/是否全程不变;
  4. 时间戳:每个流的中位间隔、最大间隔、回退、重复、丢帧、相对主时钟偏移;
  5. RGB 视频:每路相机的分辨率、fps、视频帧、parquet 行、差、时长、重复帧、亮度;
  6. 问题明细 + 结论与建议。

点「删除选中段」把勾选的段从数据集里彻底删掉——会同时删掉 parquet、所有视频和对应的 meta 记录,不可恢复,会弹确认框。

5. 一次完整的质检流程#

text
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(合成数据集覆盖关节角、视频帧、时间戳)