接入 LeRobot

rosbag_to_lerobot 工具

rosbag_to_lerobot 用于将机器人采集的 ROS 2 rosbag2 数据转换为 LeRobot V3 数据集。工具根据不同机型的 YAML 配置解析机器人状态、动作和相机 Topic，并完成时间对齐、重采样和数据集生成。

功能特性

• 输入格式： 支持 rosbag2 目录、metadata.yaml、与其同目录的 .mcap / .db3 数据文件，以及包含一份 rosbag2 数据的 .tar / .tar.gz / .tgz 归档。

• 机型支持： 当前提供 Quanta X1、Quanta X2 和 Desktop 的转换配置。

• Topic 配置： 不同机型通过 YAML 配置定义状态、动作和相机数据来源，不建议在转换代码中直接写死 Topic。

• 时间同步： 转换时计算各有效数据流的共同时间区间，并按照目标 FPS 对状态、动作和图像进行时间对齐和重采样。

• Episode： 支持单个 rosbag 转换，也支持批量数据和平台任务数据组织为多个 episode。

• 输出格式： 低维状态和动作数据保存为 Parquet，相机数据保存为 MP4，并生成 LeRobot V3 所需的 metadata。

当前交付状态

tools/rosbag_to_lerobot/ 当前已经在 SDK 内部代码中实现并完成基础功能核验，但 SDK v1.1.2 的公开导出包尚未包含该工具。

因此，以下目录和命令用于说明当前转换工具的接口和工作流程。只有在获得包含 rosbag_to_lerobot 的 SDK 版本或正式发布的工具包后，才能直接执行。

工具目录

tools/rosbag_to_lerobot/
├── scripts/
│   ├── convert_rosbag_to_lerobot.py
│   ├── convert_rosbag_to_lerobot_v3_batch.py
│   └── convert_platform_task_to_lerobot_v3.py
├── config/
│   ├── quanta_x1/
│   ├── quanta_x2/
│   └── desktop/
├── requirements.txt
├── README.md
└── README_CN.md

依赖安装

当前工具依赖中固定使用 LeRobot 0.4.2。工具正式交付后，建议优先按照随工具发布的 requirements.txt 安装依赖。下载 v0.4.2 版本的 lerobot 安装包，安装方法

python -m pip install ./lerobot-0.4.2-py3-none-any.whl

python -m pip install -r tools/rosbag_to_lerobot/requirements.txt

输入数据

标准 rosbag2 目录通常包含：

my_rosbag/
├── metadata.yaml
└── xxx.mcap

或者：

my_rosbag/
├── metadata.yaml
└── xxx.db3

metadata.yaml 用于描述 rosbag2 数据集，.mcap / .db3 保存实际 ROS 2 消息数据。

工具同时支持内部包含一份完整 rosbag2 数据的 .tar、.tar.gz 和 .tgz 归档。

快速开始

获得包含该工具的 SDK 后，在 tools/rosbag_to_lerobot 目录下执行：

python scripts/convert_rosbag_to_lerobot.py     --bag-path /path/to/rosbag2     --output-dir /path/to/lerobot_data     --repo-id "my_org/my_dataset"     --config config/quanta_x1/lerobot_v3_16d.yaml

参数说明

其他可选参数以当前工具执行 --help 的输出为准。

机型配置

当前工具已经提供以下机型配置：

• Quanta X1： 左右机械臂末端位姿、左右夹爪、头部状态及三路相机等数据。

• Quanta X2： 根据不同夹爪类型配置对应的腕部位姿、夹爪状态和相机数据。

• Desktop： 左右机械臂、夹爪和相机数据。

具体 Topic 名称、数据类型以及字段映射以对应机型 YAML 为准。

Quanta X1 数据结构

当前 Quanta X1 的 LeRobot V3 配置使用 16 维状态 / 动作表示，主要包括：

• 左臂末端位置和姿态；

• 左夹爪状态；

• 右臂末端位置和姿态；

• 右夹爪状态；

• 头部 pitch 和 yaw。

字段名称、顺序和单位应以对应 YAML 配置和转换后数据集的 metadata 为准。

时间同步与 Action 构造

不同机器人数据源的采样频率可能不同。转换工具会先计算有效数据流的共同时间区间，再按照目标 FPS 对各数据源进行重采样，使同一个 LeRobot frame 中的图像、state、action 和 timestamp 对齐到统一时间轴。

默认配置可以使用下一时刻的 state 构造当前 action：

action[t] = state[t + 1]

也可以根据机型配置从独立动作数据源构造 action。实际使用方式以对应 YAML 中的 action 配置为准。

输出目录结构

转换后的 LeRobot V3 数据集通常包含：

lerobot_data/
├── meta/
│   ├── info.json
│   ├── stats.json
│   ├── tasks.parquet
│   └── episodes/
│       └── chunk-000/
│           └── file-000.parquet
├── data/
│   └── chunk-000/
│       └── file-000.parquet
└── videos/
    └── observation.images.<camera_name>/
        └── chunk-000/
            └── file-000.mp4

• data/：状态、动作、时间戳等低维时序数据。

• videos/：相机视频。

• meta/info.json：数据集 feature、FPS 和数据版本等信息。

• meta/stats.json：数据统计信息。

• meta/tasks.parquet：任务信息。

• meta/episodes/：episode 元数据。

批量转换

需要批量处理多份 rosbag 数据时，可以使用：

scripts/convert_rosbag_to_lerobot_v3_batch.py

批量转换适合将多次采集结果组织为多个 episode。

转换后检查

完成转换后，建议至少检查：

1. 输出目录中的 meta、data 和 videos 是否完整；

2. episode 数量和帧数是否符合预期；

3. 相机视频能否正常播放；

4. state 和 action 的 shape、顺序和单位是否与机型配置一致；

5. 图像、state、action 和时间戳是否正确对齐；

6. 是否存在明显缺帧、时间戳异常或数据长度不一致；

7. task 信息是否与实际 episode 对应。

与 SDK DataCollector JSON 转换的区别

SDK 中同时正式支持 DataCollector → collected_data JSON → tools/convert_to_lerobot.py 转换流程。

该流程与本节介绍的 rosbag2 → rosbag_to_lerobot → LeRobot V3 是两套不同的数据链路。

两种流程的输入目录、转换脚本、配置方式和命令行参数不能混用。SDK DataCollector JSON 数据的转换方法请参考“数据采集示例”中的对应说明。