别再被Parquet和MP4拆分搞晕:V2D Challenge的LeRobot v2.1数据格式实战指南

原创2026-10-21 23:47:401,890 阅读

别再被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。它声明了四件大事:

  1. codebase_version: "v2.1" —— 版本,决定加载器行为;
  2. fps、total_episodes、total_frames —— 数据集规模;
  3. 路径模板(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 扫目录;

  1. 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 过滤

  1. 文件打开是 LFS 指针而不是数据。 如果 Parquet/MP4 开头几十字节是 version https://git-lfs...,说明大文件只拉到了指针。改用官方方式整仓下载(见下一节),或补拉 LFS 对象,别对着指针文件调试。
  2. 不要把 Track 2 的两个 Tier 拼在一起读。 官方建议以单个 Tier 目录作为数据集根目录,且两 Tier 的 episode 与全局帧索引刻意重叠用于逐帧对照(track_2/README.md)。混读会导致同一帧出现两份、统计量失真。
  3. 四元数顺序是 w-first。 位姿是 [x, y, z, qw, qx, qy, qz],不是常见的 [x, y, z, wx, wy, wz, w] 里的尾 w 习惯,也不是 (x,y,z,w) 顺序——转换到库函数前务必核对,转错了姿态会整个"翻面"。
  4. 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 的大文件基础设施,下载前请留足磁盘空间。落盘后按顺序自查:

  1. 打开对应 Track 的 meta/info.json,核对 codebase_version、fps、data_path/video_path 模板;
  2. 抽一集(如 track_3/public/data/chunk-000/episode_000000.parquet),确认列与 features 声明一致、行数等于 episodes.jsonl 里的 length;
  3. 用 episodes_metadata.jsonl 把该集映射到相机、目标物体与配套 mesh / ground_plane / support_surface;
  4. 抽一帧验证"行 i ↔ 帧 i"对齐,确认 MP4 能正常解码而非 LFS 指针。

四步走完,Parquet 与 MP4 的拆分就不再是黑盒:meta 定规矩、Parquet 出数字、MP4 出画面,三者靠 episode_index 与行号一一对应。

登录后查看全文
video_to_data_challenge