SO-101
课程总览/第 08 章 · 数据采集
EN
第 08 章数据与训练约 20 分钟

数据采集

配套页面:控制台的「数据采集」页签

7 个小节 3 张图 9 段代码 采集30 fps时间戳
数据采集页

1. 为什么要采集#

前七章做的事,本质是让机械臂"能听懂指令、能走到位置"。而要让机械臂学会一个动作(抓杯子、开抽屉),光有指令不够,还需要人做一遍、机器记一遍:

text
人扶着机械臂做动作  →  30 Hz 把"看到的"和"动了什么"一起记下来  →  训练策略  →  机械臂自己会做

这条链路里,采集质量直接决定训练结果。帧率不稳、时间戳对不上、相机和关节差半拍,训出来的策略就会"看着左边、抓向右边"。

所以数据采集要解决三件事:

问题 这一页的答案
记什么 六个关节角 + 相机画面
记多快 30 Hz,固定周期
怎么对齐 每帧三个时间戳,差多少都写下来

采集期间,机械臂基座和第三视角相机的位置必须固定,不能挪动。基座决定机器人坐标系和工作空间,第三视角相机决定模型看到的画面;两者一动,同一组关节角对应的像素、桌面位置和安全边界都会变。同一批数据里混入不同位置,模型会学到互相矛盾的“状态 → 动作”,训练和推理都会明显变差。采集前把基座固定好、相机架稳;中途挪过,就重新标定/重新录一批,不要接着往旧数据集里追加。

2. 采集什么#

关节角(6 维)#

text
shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll, gripper

为什么记关节角,而不是 TCP 位姿?

关节角 TCP 位姿
数据量 6 个数 5 个数
是否唯一 是——一组关节角唯一确定一个位姿 否——同一位置可能有多组关节角
能不能互相推 关节角 → FK → 位姿,随时能算 位姿 → IK → 关节角,可能多解、可能无解
丢失信息 无 丢失了肘部/腕部的具体姿态

所以关节角是原始量,位姿是派生量。记原始量,需要位姿时用第 4 章的 FK 现算即可。

这也是为什么这一页不采 TCP 位姿:它可以从关节角算出来,重复存一份只会在两列数据不一致时带来麻烦。

相机帧(可多选)#

真实机器人采集通常用两台相机:

  • 腕部相机(wrist):装在腕部或夹爪附近,跟着手臂一起动,拍夹爪、物体和接触点的近距离画面;
  • 第三视角相机(top / external):固定在桌面外侧、支架或工作区上方,拍整条手臂、桌面和任务区域。控制台里这个角色叫 top,但不一定真的装在正上方。

一条 episode 可以同时绑多路相机。正式采集建议两路都勾;三种选择的区别:

勾选 写什么
只勾顶部 top_rgb/episode-000.mp4 → observation.images.top_rgb_ns
只勾腕部 wrist_rgb/episode-000.mp4 → observation.images.wrist_rgb_ns
两路都勾 两条 mp4 → 两列 *_ns

两种方案的取舍:

方案 优点 缺点
双路(推荐)
正式采集
第三视角给任务上下文,腕部给夹爪和接触细节;一边被挡时另一边还能提供信息 USB 带宽、CPU、磁盘都翻倍;两路时间戳和重复帧都要盯
仅第三视角
快速验证、远景任务
资源占用低,能看到整条手臂和桌面;调试简单 夹爪和接触点小,容易被手臂或物体挡住;精细操作难
仅腕部
末端特写、辅助验证
近距离看清夹爪和物体,不受身体遮挡 没有全局位置和任务上下文,机械臂快速移动时画面容易糊

单路不是“默认正确”,而是资源受限时的退路。 两路 720p@30 确实会抢 USB 带宽和 CPU;但把 MJPG、驱动缓冲 2、两路独立采集线程和关闭 3D 视图做好后,实测可以稳定在 30.1 Hz。正式采集优先两路;只有带宽/CPU 实在不够,或只是快速验证流程时,才退到单路。

控制台里顶部默认勾选、腕部默认不勾;正式采集请把腕部也勾上。页面上的「录制视角」 勾几路就录几路,文件结构见 §4。

时间戳(每帧三个)#

时间戳对齐
字段 含义
hardware_ns 这一采样周期的 monotonic_ns,主时间轴
observation.state_ns 关节角读取时刻(与上一行同一周期,值相同)
observation.images.top_rgb_ns 相机帧真实采集时刻

后两个与主时间轴之差,就是这一帧的延迟。用 monotonic 而不是系统时间,是因为 monotonic 不会被对时(NTP)改动,跨帧差值永远可靠。

3. 30 fps 是怎么保证的#

录制线程按固定周期跑:

text
每 1/30 秒(33.3 ms):
  ① 取一次 monotonic 时刻         → hardware_ns
  ② 读六个关节角                   → observation.state
  ③ 取相机最近一帧 + 它的采集时刻   → observation.images.<key>_ns
  ④ 写进内存缓冲,同时把帧喂给编码器

三个细节决定帧率能不能稳在 30:

A. 相机要显式设成 MJPG + 30 fps。 USB 2.0 带宽下 1280×720 只有 MJPG 编码能跑 30 fps。不指定的话,很多相机默认协商成10 fps——录制端每周期都在,但相机每 100 ms 才出一帧,于是大量重复帧。实测:

设置前 设置后
相机实际帧率 10.3 fps 30.2 fps
108 帧里的重复帧 72 2

B. 关掉相机的「动态帧率」。很多 UVC 相机(尤其这些 USB 小相机)默认开着 exposure_dynamic_framerate:画面一变暗,它就拉长曝光时间换亮度,代价是帧率掉到 20 多帧。腕部相机最明显——朝天花板时 30 fps,一转向桌面就变 20 多帧,一上一下来回跳。

打开相机时会自动执行:

bash
v4l2-ctl -d /dev/videoX -c exposure_dynamic_framerate=0

关掉后驱动只能在 1/30 s 内靠增益补亮度,帧率稳定在 30。可以自己核对:v4l2-ctl -d /dev/video0 --list-ctrls | grep dynamic,value 应该是 0。

C. 驱动缓冲不能设成 1。 V4L2 单缓冲时,驱动没有地方暂存下一帧,应用读得稍慢一点就丢帧。双路实测:

CAP_PROP_BUFFERSIZE 两路各自的交付帧率
1 21.0 / 20.3 fps
2 30.3 / 30.3 fps
4 30.3 / 30.3 fps

给 2 个缓冲即可跑满,延迟只多一帧(约 33 ms)。

D. 两路相机各走一条采集通道。顶部和腕部各自一个抓帧线程、各自一个帧槽位,互不阻塞。每路都带帧序号和交付帧率,页面上直接显示:

text
顶部 top /dev/video2 1280×720 · 30.3 fps
腕部 wrist /dev/video0 1280×720 · 30.3 fps

录制时「实时」卡还会逐路列出交付帧数和延迟。实测双路同录:

单路 双路(修好后)
实际帧率 30.0 Hz 30.1 Hz
重复帧 2/119 2/181
最大延迟 10.7 ms 27.9 ms

E. 采样要等新帧,不能硬按节拍取。相机的出图间隔是有抖动的。测过一台腕部相机:32.5, 31.5, **36.0**, 32.1, 32.0, **36.0** … ——平均是 30 fps,但每隔几拍就来一个 36 ms 的空档。固定 33.3 ms 打拍,撞上空档就拿到旧帧,于是记成重复。

代码里每拍发现帧时间戳没变时,最多再等 20 ms 拿新帧,等不到才真的复用。实测:

等待窗口 20 秒录制(600 帧)的重复帧
不等 40 ~ 90
12 ms 2
20 ms 0

窗口不能无限大:等太久会让采样落后于节拍。20 ms 是实测下来既压住重复、又不掉拍的值。

F. 追不上就重置节拍,不补帧。如果某一周期超时(例如相机卡了一下),下一拍从当前时刻重新对齐,而不是连发几帧追赶。补帧会制造出"看起来 30 fps、实际时间戳挤在一起"的假数据。

G. 重复帧单独计数,不改时间戳。相机偶尔慢一拍时,这一帧会用上一帧的画面,但时间戳仍是这一周期的 ——下游能通过 drop_stats 知道"这里有一帧是复用的"。

H. 录制时把 3D 视图关掉。页面右侧的姿态视图要持续渲染,实测能把浏览器推到 8 个核、把两路相机挤到 21 fps。点标题栏的「3D 开 / 3D 关」关闭,会释放 WebGL 上下文和渲染循环;采集侧不受影响,两路仍稳定 30 fps。

互动实验

帧率体检

实测场景回放

录制线程每 33.3 ms 打一拍;相机慢一拍,这一拍就复用了上一帧。选一个场景,看 1 秒里的节拍、相机帧和重复帧。

录制节拍(30 Hz)相机新帧重复帧
相机交付30.2fps
重复帧2/ 108
占比1.9%
场景与数值来自第 8 章第 3 节的实测表。>2% 警告、>10% 错误的阈值也来自第 9 章。

4. 文件结构#

每次录制写一个 episode,追加到数据集目录:

text
recordings/<数据集名>/                       ← 工作区下的相对路径,没有会自动创建
├── meta/
│   ├── info.json                           ← 总说明:fps、特征、相机、路径模板
│   ├── stats.json                          ← 各特征统计(均值/方差/极值)
│   ├── tasks.jsonl                         ← 任务名(task_index → task)
│   └── episodes/chunk-000/episode-000.parquet   ← 这一段的元信息
├── data/
│   └── chunk-000/episode-000.parquet       ← 逐帧数据(每帧一行)
└── videos/
    └── chunk-000/
        ├── top_rgb/episode-000.mp4         ← 顶部画面(与 parquet 行数一一对应)
        └── wrist_rgb/episode-000.mp4       ← 腕部画面(勾了就写)

chunk-000 是分片:每 1000 个 episode 换一个 chunk,避免单目录塞太多文件。

meta/info.json#

json
{
  "format": "pooled_episodes_v1",
  "codebase_version": "v3.0",
  "fps": 30.0,
  "task_name": "UMI_9_29",
  "cameras": {"top_rgb": {"height": 720, "width": 1280}},
  "data_path": "data/chunk-{c:03d}/episode-{f:03d}.parquet",
  "video_path": "videos/chunk-{c:03d}/{image_key}/episode-{f:03d}.{ext}",
  "features": {
    "observation.state":            {"dtype": "float32", "shape": [6]},
    "observation.state_ns":         {"dtype": "int64", "shape": [1]},
    "observation.images.top_rgb_ns":{"dtype": "int64", "shape": [1]},
    "action":                       {"dtype": "float32", "shape": [6]}
  }
}

data/chunk-000/episode-000.parquet#

每行 = 一帧,30 行/秒。

列 类型 说明
episode_index int64 第几段
frame_index int64 段内帧号,从 0 开始
timestamp double 相对段首的秒数
task_index int64 任务编号
wall_time double 绝对时间(Unix 秒,便于和别的设备对表)
hardware_ns int64 主时间轴(monotonic)
observation.state float32[6] 六个关节角
observation.state_ns int64 关节角读取时刻
observation.images.top_rgb_ns int64 顶部相机帧采集时刻
observation.images.wrist_rgb_ns int64 腕部相机帧采集时刻(录了才有这一列)
action float32[6] 当前录制器写入的实测关节角(与 observation.state 同一份数据)

当前录制器的 action 与 observation.state 相同。如果训练端没有额外做 next-state / shift,ACT 学到的会是 state → state;在拿这类数据训练前,先确认训练端的动作时序处理。本文档按当前录制器如实记录,不改变录制行为。

meta/episodes/chunk-000/episode-000.parquet#

一段一行,描述这段录制本身:

列 说明
episode_index / task_index 编号
start_frame_index / end_frame_index / length 在全局帧序列里的位置与长度
duration_sec 时长
drop_stats 重复帧、缺帧、相机最大延迟
video_codec 编码器与参数

视频#

videos/chunk-000/<image_key>/episode-000.mp4,H.264、1280×720、30/1 fps、与 parquet 行数严格相等。

重复帧不影响"720p30"这件事。 视频永远严格 30 帧/秒、行间隔 33.3 ms;某一路相机没送来新画面时,只是同一张图被写两次,时间轴不会漂。实测一段 581 帧的录制:行间隔中位数 33.3 ms、最大 33.5 ms。勾了几路就有几个子目录,每个子目录里一条 mp4,行数都等于 parquet 行数。读的时候第 N 行对应第 N 帧,不需要额外索引。

5. 页面怎么用#

数据采集页:按钮位置

截图上的编号对应下面每一步。

前提:先在「主从遥操」页连接主臂和从臂。 数据采集是“人扶着主臂、从臂跟随、页面记录”的过程;只连从臂不会产生示教动作。到「主从遥操」页填好主臂串口 + 从臂串口,确认「主从对照」有主臂读数、从臂已上力;如果用绝对映射,先把两臂对齐并开始遥操,再回本页录制。本页的「开始录制」只负责记录,不会替你启动主从遥操。

开始前再确认一次:机械臂基座和第三视角相机的位置没有移动(见 §1 末尾的警告);挪动过就先恢复/重标定,不要直接在旧位置上继续采。

准备

编号 操作
④ 「相机画面」里点「扫描设备」列出候选,给顶部(第三视角)和腕部各选一个设备(哪台是顶部由你判断),再分别点「连接」
⑤ 看两路预览确认没接反:能看到夹爪指头的是腕部。标签里带实际帧率,正常是 30 fps
① 填数据集名(如 UMI_9_29),会记住上次输入
② 「录制视角」勾要录的视角;正式采集建议顶部 + 腕部都勾(见 §2 相机帧)
⑧ 建议先把 3D 视图关掉(见下方提示)

录制

编号 操作
③ 点「开始录制」,卡片下方显示 录制中 · episode #N · 帧数
⑥ 录制时盯「实时」:实际频率、重复帧、延迟
③ 操作完点「停止录制」,显示 已保存 episode #N · N 帧 / x.xs · 重复帧 n · 最大延迟 x ms
③ 这段不想要了:点「异常终止」,本次数据直接丢弃、不写盘、不占 episode 数;下次录制沿用同一个编号
⑦ 「已有数据集」里确认 episode 数 +1,大小有增长

页面和日志里的 episode 编号都是 1 基,从 #1 开始;磁盘上的文件名仍是 LeRobot v3 约定的 0 基(episode-000.mp4 对应日志里的 episode #1)。编号由 meta/info.json 的 last_episode_index 水位线控制,严格递增:在质检页删掉末尾几段后再录,也只会往后排,不会把旧编号重新用一遍。

开录前会自动校验

点「开始录制」时,服务端先量 1 秒:任一路相机低于 27.5 fps 就直接拒绝开录,并指出是哪一路:

text
wrist 相机当前只有 24.8 fps(要求 ≥27.5)。检查线缆/USB 口,
或关掉其它占用 CPU 的程序后重试

这样不会白录一段满是重复帧的数据。

检查

指标 正常范围 异常说明
实际频率 29–30 Hz 明显低于 30 → 相机没跑满 30 fps
相机重复帧 < 2% 2–10% 会收到质检告警;比例高 → 相机帧率不够或缓冲设置不对
相机缺帧 0 非 0 → 相机掉线
相机最大延迟 < 50 ms 过大 → USB 带宽或 CPU 吃紧
单路卡顿次数 0 出现说明那一路中途断过(线缆最常见)
相机实测 fps 30.0 这是相机自己的出图率(不是采样率);低于 29 说明那台相机跑不满
相机最大间隔 ≈33 ms 60 ms 以上说明相机偶发卡顿

录制前先关掉 3D 视图(⑧)

姿态视图的那个 3D 场景要持续渲染,实测能把 Chrome 推到 8 个核、把相机采集挤到 21 fps。点卡片标题栏的 「3D 开 / 3D 关」 关掉它,会释放 WebGL 上下文和渲染循环,占位框显示「3D 视图已关闭(不占 CPU/GPU)」。

关掉之后两路相机仍稳定在 30 fps。开关状态会记住,下次打开页面保持不变。

6. 常见问题#

现象 原因 处理
实际频率只有 10 Hz 相机没协商成 30 fps 重新连接(系统会按 MJPG + 30 fps 打开)
重复帧很多 相机帧率低于采样率 同上;或降到 480×270 / 640×360
只有某一路重复帧多 那一路被抢了 CPU / 线缆松动 见下面「某一路掉帧怎么查」
两路画面接反 顶部/腕部选错了设备 看画面判断,改设备路径重连
录制开始就报错 相机没连 / 机械臂没连 先连接
episode 编号从 1 开始 新数据集 正常;同一数据集里编号严格递增,日志显示 #N,质检页也显示同一个 N
录到一半发现不对 这一段不能用了 点「异常终止」,丢弃数据且不占编号;下次录制仍用这个编号
视频和 parquet 行数不一致 编码器丢帧 本实现每帧都写入,不会发生;若出现说明磁盘写满

某一路掉帧怎么查#

重复帧是按路统计的,录完看 meta/episodes/*.parquet 的 drop_stats 就知道是哪一台:

json
{"top_rgb_duplicate": 1, "wrist_rgb_duplicate": 61,
 "top_rgb_lag_max_ms": 11.8, "wrist_rgb_lag_max_ms": 49.0}

两条判据:

看什么 说明什么
只有一路重复高 问题在那一路(相机本身 / 它的线 / 它的线程被抢)
该路 lag_max_ms 明显更大 那一路周期性卡顿,不是单纯的帧率低

实测对照:臂静止录 20 秒,两路各 600 帧、各只重复 1 帧——说明采集链路本身没问题;臂动起来才掉,优先怀疑腕部相机线缆随手臂拉扯或当时主机 CPU 被占满。

排查顺序:

  1. 看页面上两路标签的实时帧率(顶部 … 30.0 fps)。臂静止时哪一路长期低于 29,基本就是那台相机或它的线。
  2. 关掉 3D 视图再录一次(见 §3 F 条)。
  3. 录之前别同时开别的预览/录制工具。
  4. 换 USB 口:两台相机尽量插在不同控制器上(lsusb -t 看 Bus 编号)。
  5. 腕部相机:换软一点的短线、加应力释放,别和电机线束捆在一起。
  6. 还不行就把该路降到 640×480 再试——解码和数据量都减半。

两路同时掉说明不是相机问题,是主机被占满了。按这个顺序清:

  1. 关掉其它标签页(每个开着「数据采集」页的标签都会拉两路预览)
  2. 关 3D 视图
  3. 关掉跑在旁边的其它程序(浏览器自动化、视频播放、模型推理)

服务端对预览做了 200 ms 缓存,同一路重复请求不会重复编码;页面在录制期间也会把预览降到约 1 fps。但多开几个标签页仍然会叠加,这一点只能靠关标签解决。

录制期间页面会把相机预览降到约 1 fps,把 CPU 让给采集线程。

参考#