数据采集
配套页面:控制台的「数据采集」页签
1. 为什么要采集#
前七章做的事,本质是让机械臂"能听懂指令、能走到位置"。而要让机械臂学会一个动作(抓杯子、开抽屉),光有指令不够,还需要人做一遍、机器记一遍:
人扶着机械臂做动作 → 30 Hz 把"看到的"和"动了什么"一起记下来 → 训练策略 → 机械臂自己会做
这条链路里,采集质量直接决定训练结果。帧率不稳、时间戳对不上、相机和关节差半拍,训出来的策略就会"看着左边、抓向右边"。
所以数据采集要解决三件事:
| 问题 | 这一页的答案 |
|---|---|
| 记什么 | 六个关节角 + 相机画面 |
| 记多快 | 30 Hz,固定周期 |
| 怎么对齐 | 每帧三个时间戳,差多少都写下来 |
采集期间,机械臂基座和第三视角相机的位置必须固定,不能挪动。基座决定机器人坐标系和工作空间,第三视角相机决定模型看到的画面;两者一动,同一组关节角对应的像素、桌面位置和安全边界都会变。同一批数据里混入不同位置,模型会学到互相矛盾的“状态 → 动作”,训练和推理都会明显变差。采集前把基座固定好、相机架稳;中途挪过,就重新标定/重新录一批,不要接着往旧数据集里追加。
2. 采集什么#
关节角(6 维)#
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 是怎么保证的#
录制线程按固定周期跑:
每 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 多帧,一上一下来回跳。
打开相机时会自动执行:
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. 两路相机各走一条采集通道。顶部和腕部各自一个抓帧线程、各自一个帧槽位,互不阻塞。每路都带帧序号和交付帧率,页面上直接显示:
顶部 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。
4. 文件结构#
每次录制写一个 episode,追加到数据集目录:
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#
{
"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 就直接拒绝开录,并指出是哪一路:
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 就知道是哪一台:
{"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 被占满。
排查顺序:
- 看页面上两路标签的实时帧率(
顶部 … 30.0 fps)。臂静止时哪一路长期低于 29,基本就是那台相机或它的线。 - 关掉 3D 视图再录一次(见 §3 F 条)。
- 录之前别同时开别的预览/录制工具。
- 换 USB 口:两台相机尽量插在不同控制器上(
lsusb -t看 Bus 编号)。 - 腕部相机:换软一点的短线、加应力释放,别和电机线束捆在一起。
- 还不行就把该路降到 640×480 再试——解码和数据量都减半。
两路同时掉说明不是相机问题,是主机被占满了。按这个顺序清:
- 关掉其它标签页(每个开着「数据采集」页的标签都会拉两路预览)
- 关 3D 视图
- 关掉跑在旁边的其它程序(浏览器自动化、视频播放、模型推理)
服务端对预览做了 200 ms 缓存,同一路重复请求不会重复编码;页面在录制期间也会把预览降到约 1 fps。但多开几个标签页仍然会叠加,这一点只能靠关标签解决。
录制期间页面会把相机预览降到约 1 fps,把 CPU 让给采集线程。
参考#
- 第 4 章:FK 与 IK —— 关节角怎么变成位姿
- 第 7 章:相机标定 —— 相机怎么接、怎么对
- 代码:
webapp/recorder.py(采集与写盘)、webapp/server.py的/api/collect/*