别再被Parquet和MP4拆分搞晕:V2D Challenge的LeRobot v2.1数据格式实战指南
别再被Parquet和MP4拆分搞晕:V2D Challenge的LeRobot v2.1数据格式实战指南
NVIDIA 的 V2D Challenge(video_to_data_challenge)是一个从人类演示视频到机器人数据链路实测的数据集,它完整采用 LeRobot v2.1 数据格式组织:每一帧的数值数据存在 Parquet 里,视频存在 MP4 里,数据格式的"说明书"放在 meta/ 目录。本文直接基于仓库真实目录逐层拆解,帮你在 5 分钟内看懂任何一条 episode 该从哪里读起、怎么和帧对齐,避开新手最常踩的四个坑。
为什么 LeRobot v2.1 要把数据拆成 Parquet 和 MP4
先记住一句话:Parquet 管"每一帧的数字",MP4 管"每一帧的画"。
- 图像/视频逐帧塞进 Parquet 会膨胀几十倍,而 H.264 压缩后的 MP4 体积小、读取快,所以视频一律走
videos/目录; - 姿态、时间戳、索引这类结构化数值走
data/下的 Parquet,支持按列裁剪读取; meta/目录不存数据本身,而是存"这份数据长什么样"的元信息,让读取端(包括 LeRobot 官方加载器)能自动拼出文件路径。
| 目录 | 存放内容 | 典型文件 |
|---|---|---|
data/chunk-000/ |
每帧数值(一集一个 Parquet) | episode_000000.parquet |
videos/chunk-000/ |
压缩视频(一集一个 MP4,按相机流分文件夹) | episode_000000.mp4 |
meta/ |
数据格式说明书与每集元数据 | info.json |
💡
chunk-000不是"第 0 块数据",而是按chunks_size(每 1000 集分一块)归档 episode 的目录约定,本数据集均只有一个 chunk。
V2D Challenge 三个 Track 的数据总览
整个仓库分三个赛道(README.md),都是 LeRobot v2.1 数据集,但 Parquet 里装的"干货"差别很大:
| Track | 规模 | Parquet 里存什么 | 视频流 |
|---|---|---|---|
| track_1 重建赛道 | 30 集 / 16,563 帧 / 30 fps | 仅 6 个结构列,纯视频输入做目标跟踪 | 1 路第三人称 exo_camera(1536×1152,H.264,无音频) |
| track_2 机器人落地赛道 | 30 集 × 2 个噪声 Tier / 22,990 帧 | 人体 231 维姿态 + 物体 7 维位姿 + 可见性标志 | 与 Track 1 字节一致的同一路 exo_camera |
| track_3 第一视角赛道 | public 20 集 / 5,246 帧 / 20.25 fps | observation.objects 结构化多物体位姿列表 |
3 路 ego 相机(a 彩色 2028×1520,b/c 单目立体 1280×800,基线 75mm) |
Track 2 的每个 Tier(tier_1_multiview_caption/ 与 tier_2_synthetic_noise/)各自是一个完整独立的数据集:Tier 1 是干净重建轨迹,Tier 2 是注入了抖动、丢帧、接触误差的合成噪声轨迹,两者帧索引刻意重叠以便逐帧对比。除 Parquet 外的配套资产还包括 mesh/(GLB 带纹理物体网格)、ground_plane/(拟合地面平面 JSON)与 support_surface/(USD 支撑面),Track 3 还额外提供 urdf/ 与 camera_calibration.json 相机标定。
先读 meta/info.json:数据格式的"说明书"
拿到任何 LeRobot v2.1 数据集,第一步永远是打开 meta/info.json。它声明了四件大事:
codebase_version: "v2.1"—— 版本,决定加载器行为;fps、total_episodes、total_frames—— 数据集规模;- 路径模板(track_1/meta/info.json#L14-L15):
data_path = data/chunk-{episode_chunk:03d}/episode_{episode_index:06d}.parquet
video_path = videos/chunk-{episode_chunk:03d}/{video_key}/episode_{episode_index:06d}.mp4
把 episode_index 填进去就得到真实文件路径——比如第 7 集就是 episode_000007.parquet,所以根本不需要 glob 扫目录;
features—— 每一列的 dtype、shape 与维度名。视频特征会额外带video.codec、video.height/width、video.fps等信息(track_1/meta/info.json#L23-L47),而 track_3/public/meta/info.json 里则能看到observation.objects是list<struct{name, pose, visible}>的可变长列表。
其余 meta 文件各司其职(以 track_1/meta/ 为例):
| 文件 | 作用 |
|---|---|
| episodes.jsonl | 每集帧数 length 与对应任务描述 |
| episodes_metadata.jsonl | 每集的拍摄相机、目标物体 object 与提示词 object_prompt、video_key |
| episodes_stats.jsonl | 各列的 mean/max/min 等统计量 |
| tasks.jsonl | task_index → 自然语言任务描述的映射 |
Parquet 列结构拆解:Track 1、2、3 各存了什么
三个 Track 共用同一套"骨架列":timestamp、frame_index、episode_index、index(全局帧号)、task_index、next.done(本集最后一帧为真),差异全在"肉"上。
Track 1:纯索引列,数据全在视频里
Track 1 的 Parquet 只保留对齐视频帧所需的最少结构列(见 track_1/README.md 的 Layout 一节),没有人体姿态、物体姿态或可见性标注——重建工作正是参赛者要从 MP4 里完成的。
Track 2:人体 231 维姿态 + 物体 7 维位姿
以 track_2/tier_1_multiview_caption/meta/info.json 的 features 为例,肉厚多了:
observation.human.pose:231 个 float32,是 77 根骨骼 × 3 个欧拉角(Hips.rx…RightToeEnd.rz),外加translation(3 维)、identity_coeffs(45 维体型系数)与scale_params;observation.object.pose:7 维[x, y, z, qw, qx, qy, qz]——平移 3 维 + 四元数,且 w 在最前;observation.object.visible:bool 可见性标志。
Track 3:一列装下多个物体
Track 3 每集跟踪 1~2 个(偶尔更多)物体,全部打包在 observation.objects 这一列里(track_3/README.md#L40-L68):
list<struct{ name: string, pose: float32[7], visible: bool }>
name直接就是网格目录名:white_pot→ mesh/white_pot/white_pot.glb;- 同一集内成员恒定且按名字排序,
objects[i]每帧都是同一个物体,无需逐帧判断。
MP4 帧号与 Parquet 行号如何对齐
这是整套拆分设计的"闭环",规则只有一条:
Parquet 的第 i 行 = 该集每个 MP4 的第 i 帧(第 0 行对第 0 帧)。
Track 3 明确说明视频与 Parquet 是 frame-exact 对齐,且在全部 60 条 ego 视频上验证过(track_3/README.md)。timestamp 列则等于 frame_index / fps:Track 1/2 是 30 fps,Track 3 约为 20.254 fps。所以想取"第 100 帧的画面 + 该帧位姿",只需分别读视频第 100 帧和 Parquet 第 100 行,二者天然同步,无需查表。
四个最常见的坑:LFS 指针、Tier 混读、四元数顺序与 visible 过滤
- 文件打开是 LFS 指针而不是数据。 如果 Parquet/MP4 开头几十字节是
version https://git-lfs...,说明大文件只拉到了指针。改用官方方式整仓下载(见下一节),或补拉 LFS 对象,别对着指针文件调试。 - 不要把 Track 2 的两个 Tier 拼在一起读。 官方建议以单个 Tier 目录作为数据集根目录,且两 Tier 的 episode 与全局帧索引刻意重叠用于逐帧对照(track_2/README.md)。混读会导致同一帧出现两份、统计量失真。
- 四元数顺序是 w-first。 位姿是
[x, y, z, qw, qx, qy, qz],不是常见的[x, y, z, wx, wy, wz, w]里的尾 w 习惯,也不是(x,y,z,w)顺序——转换到库函数前务必核对,转错了姿态会整个"翻面"。 visible = false时位姿是全零(零四元数,不是单位旋转)。 使用前必须先按visible过滤,否则零四元数会污染轨迹。另外 Track 3 的 x/y 是按集居中的、z 不居中,各集之间不共享世界原点,跨集拼接时要留一手。
下载后 5 分钟检查清单
按仓库 README.md 推荐,用 Hugging Face Hub 客户端保留原目录结构下载(如遇鉴权先 hf auth login):
python -m pip install -U "huggingface_hub"
hf download nvidia/video_to_data_challenge \
--repo-type dataset \
--local-dir ./video_to_data_challenge
大文件走 HF 的大文件基础设施,下载前请留足磁盘空间。落盘后按顺序自查:
- 打开对应 Track 的 meta/info.json,核对
codebase_version、fps、data_path/video_path模板; - 抽一集(如 track_3/public/data/chunk-000/episode_000000.parquet),确认列与
features声明一致、行数等于 episodes.jsonl 里的length; - 用 episodes_metadata.jsonl 把该集映射到相机、目标物体与配套 mesh / ground_plane / support_surface;
- 抽一帧验证"行 i ↔ 帧 i"对齐,确认 MP4 能正常解码而非 LFS 指针。
四步走完,Parquet 与 MP4 的拆分就不再是黑盒:meta 定规矩、Parquet 出数字、MP4 出画面,三者靠 episode_index 与行号一一对应。