ROS2转LeRobot数据集
Rosbag转LeRobot算子用于将ROS bag文件(.db3)转换为LeRobot标准数据集格式,支持输出LeRobot V2.1与LeRobot V3两种格式。平台支持节卡、千寻、星海图(Galaxea R1)、星海图(Galaxea A1Z)、青龙、优傲六个类型的本体数据,可直接使用数据生产中生成的轨迹数据集作为输入。
- 核心能力:
- 数据提取:从ROS bag中提取图像、关节状态、控制命令等多路话题数据。
- 时间同步:对多路相机图像与机械臂状态/动作执行时间对齐与帧同步。
- 格式重组:按LeRobot标准目录结构(data/、meta/、videos/ 或 images/)重组数据。
- 任务描述注入:支持通过prompt.json为各episode注入多样化任务指令,或通过统一description 描述任务。
- 批量处理:支持一次提交多个bag目录并行转换,单个失败不影响其他。
- 当前支持机型: 星海图(Galaxea R1)、星海图(Galaxea A1Z)、千寻墨子(Moz1)、节卡(Jaka)、青龙(Azureloong)、优傲(UR5E)。
- 输入: 包含ROS bag文件与可选挂载配置文件(manifest.yaml),挂载配置文件的优先级高于输入数据集根目录配置文件。
- 输出: LeRobot V2.1或V3格式数据集目录。如果用户输出选的OBS路径,预置算法会判断是否有冲突目录,如果有冲突目录,则创建一个新目录并将结果放在新目录下。
参数配置
平台内置星海图(Galaxea R1)、星海图(Galaxea A1Z)、千寻墨子(Moz1)、节卡(Jaka)、青龙(Azureloong)、优傲(UR5E)六种本体的manifest配置文件。
| 参数名 | 是否必填 | 默认值 | 可选值 | 说明 |
|---|---|---|---|---|
| robot | 是 | manifest | manifest、galaxea_r1、galaxea_a1z、jaka、moz1、azureloong、ur5e | 指定机器人型号,使用平台内置支持的六种本体类型之一。 若robot设置为manifest,且OBS挂载目录和输入数据集根目录下均无manifest文件,则作业任务采用推断模式运行,输出数据集中的manifest文件仅供参考。 |
输入说明
输入数据支持ros2 db3格式数据,db3文件同级可配置转换映射配置文件manifest.yaml(推荐,manifest 2.0 格式)
输入目录结构
每个待转换的bag目录需包含ROS bag文件与配置文件:
<bag_dir>/ # 输入目录 ├── traj_1/ # 轨迹1目录(目录下通常为 *.db3 metadata.yaml) ├── traj_2/ # 轨迹2目录(目录下通常为 *.db3 metadata.yaml) ├── task.txt # 针对所有bag的统一描述(数据生成数据资产默认自带) ├── manifest.yaml # 放置在数据集一级目录下,数据集与话题映射配置(可选) └── prompt.json # 对每个bag单独,任务描述列表(可选)
manifest配置文件:
manifest 2.0是ros2lerobot算子的统一配置格式,以schema_version: "2.0" + source_type: ros2标识。配置顶层描述 state/action字段向量(每项可定位 ROS 话题字段或通过 expr 表达式组合)、相机话题映射、任务文本、源 bag 配置(bag_glob/时间戳对齐/分段)等。
以下给出平台内置的2个本体manifest 2.0 示例配置文件。当用户通过自动生成轨迹使用不同参数生成数据集后(如视频尺寸、FPS 参数设置不同时),可修改manifest中的参数实现数据转换,并将manifest.yaml挂载在OBS目录或放置输入数据集根目录下。
- 星海图(galaxea_r1)
schema_version: "2.0"
source_type: ros2
repo_id: pick_red_test
robot_type: galaxea_r1
fps: 10
state:
# 左臂 6 关节:从 /joint_states 读,names_from: embedded 反查 msg.name
- {locator: /joint_states.position, names_from: embedded,
names: [left_arm_joint1, left_arm_joint2, left_arm_joint3,
left_arm_joint4, left_arm_joint5, left_arm_joint6]}
# 左夹爪宽度 = (finger1 + finger2) * 1000 (legacy 两指求和 ×1000 作 gripper 宽度)
- {expr: "(f0+f1)*1000",
inputs: ["/joint_states.position[left_gripper_finger_joint1]",
"/joint_states.position[left_gripper_finger_joint2]"],
name: left_gripper, role: gripper}
# 右臂 6 关节:同左臂结构
- {locator: /joint_states.position, names_from: embedded,
names: [right_arm_joint1, right_arm_joint2, right_arm_joint3,
right_arm_joint4, right_arm_joint5, right_arm_joint6]}
# 右夹爪宽度 = (finger1 + finger2) * 1000
- {expr: "(f0+f1)*1000",
inputs: ["/joint_states.position[right_gripper_finger_joint1]",
"/joint_states.position[right_gripper_finger_joint2]"],
name: right_gripper, role: gripper}
action:
strategy: stored
fields:
# 左臂 6 关节指令;topic 可能无消息 → default=legacy initial 位姿
- {locator: /left_arm_position_controller/commands.data,
names: [left_arm_exp_1, left_arm_exp_2, left_arm_exp_3,
left_arm_exp_4, left_arm_exp_5, left_arm_exp_6],
default: [0.0, 2.0, -0.873, -1.57, -1.117, 1.57]}
# 左夹爪动作:strategy=next_state 用下一帧 state[6] 推导(比 default 更鲁棒)
- {strategy: next_state, state_index: 6, name: left_gripper_exp, role: gripper}
# 右臂 6 关节指令;default 为初始位姿
- {locator: /right_arm_position_controller/commands.data,
names: [right_arm_exp_1, right_arm_exp_2, right_arm_exp_3,
right_arm_exp_4, right_arm_exp_5, right_arm_exp_6],
default: [0.0, 2.0, -0.873, 1.57, 1.117, -1.57]}
# 右夹爪动作:(finger1 + finger2) * 1000 (legacy 宽度)
- {expr: "(f0+f1)*1000",
inputs: ["/right_gripper_position_controller/commands.data[0]",
"/right_gripper_position_controller/commands.data[1]"],
name: right_gripper_exp, role: gripper}
cameras:
wrist_right: {locator: /camera_right/camera_image_color, depth: false}
wrist_left: {locator: /camera_left/camera_image_color, depth: false}
front: {locator: /camera_head_left/camera_image_color, depth: false}
task:
mode: const
text: ""
output:
chunk_size: 1000
data_file_size_mb: 100
video_file_size_mb: 200
video_codec: auto
source:
bag_glob: "*.db3"
time:
stamp_source: auto # auto: 自动选时间戳来源(相机优先)
tolerance_ms: 50 # 时间对齐容忍度(毫秒)
on_stale: hold # 数据缺失策略:hold 保留上一帧
segment:
mode: per_bag # 一个 bag 一个 episode
min_frames: 30 # 最小帧数,少于此值的 episode 被丢弃} - 节卡(jaka)
schema_version: "2.0"
source_type: ros2
repo_id: jaka_minicobo_pickplace
robot_type: jaka
fps: 10
state:
# arm 6 关节:从 /joint_states 读,names_from: embedded 反查 msg.name
- {locator: /joint_states.position, names_from: embedded,
names: [joint_1, joint_2, joint_3, joint_4, joint_5, joint_6]}
# gripper:100 - 1000*f0/5.76 (legacy 公式从 right_finger_joint 推导夹爪宽度)
- {expr: "100 - 1000 * f0 / 5.76",
inputs: ["/joint_states.position[right_finger_joint]"],
name: gripper, role: gripper}
action:
strategy: stored
fields:
# arm 6 关节指令
- {locator: /arm_position_controller/commands.data, names: [arm_exp_1, arm_exp_2, arm_exp_3, arm_exp_4, arm_exp_5, arm_exp_6]}
# gripper 指令:0 if positions[1] > 0.1 else 100 (legacy step function)
- {expr: "where(f0 > 0.1, 0, 100)",
inputs: ["/gripper_position_controller/commands.data[1]"],
name: gripper_exp, role: gripper}
cameras:
external: {locator: /camera_external/camera_image_color, depth: false}
wrist: {locator: /camera_wrist/camera_image_color, depth: false}
task:
mode: const
text: ""
output:
chunk_size: 1000
data_file_size_mb: 100
video_file_size_mb: 200
video_codec: auto
source:
bag_glob: "*.db3"
time:
stamp_source: auto
tolerance_ms: 50
on_stale: hold
segment:
mode: per_bag
min_frames: 30 | 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| schema_version | string | 是 | manifest 版本号,ros2lerobot 当前为 "2.0"。 |
| source_type | string | 是 | 数据源类型,ros2lerobot 固定为 "ros2"。 |
| repo_id | string | 否 | 数据集标识符,作为输出子目录名(flat=false 时生效)。 |
| robot_type | string | 是 | 机器人本体类型,如 galaxea_r1/jaka/moz1/azureloong/ur5e/galaxea_a1z。 |
| fps | int | 否 | 采集帧率,默认 10。 |
| state | list | 是 | 状态字段向量定义,每项通过 locator/expr 定位 ROS 话题字段或表达式组合。 |
| action | dict | 是 | 动作字段定义,含 strategy 与 fields 子字段(结构同 state,可加 default/state_index)。 |
| cameras | dict | 是 | 相机话题映射,键为相机名(如 front),值为 {locator, depth}。 |
| task | dict | 否 | 任务文本配置,mode=const 时通过 text 给单一字符串,mode=topic 时从话题读取。 |
| source | dict | 否 | 源 bag 配置,含 bag_glob、time(时间戳对齐)、segment(分段策略)。 |
| output | dict | 否 | 输出参数:chunk_size、data_file_size_mb、video_file_size_mb、video_codec。 |
- state/action 项字段说明:
| 字段 | 类型 | 必填 | 说明 |
| locator | string | 否 | ROS 话题字段定位,格式 /topic_name.field,如 /joint_states.position。 |
| expr | string | 否 | 表达式组合(与 locator 二选一),如(f0+f1)*1000,f0/f1 引用 inputs 中第 0/1 项。 |
| inputs | list | 否 | expr 表达式输入列表,每项为 locator 加索引,如 /joint_states.position[joint_1]。 |
| names | list | 否 | 显式字段名列表(长度需匹配数据第 2 维)。 |
| names_from | string | 否 | 取值 "embedded" 时从 ROS msg.name 字段反查关节名(适合多关节话题)。 |
| name | string | 否 | 单字段名(expr 模式或单维字段使用)。 |
| role | string | 否 | 语义角色,如 "gripper"(标记后算子自动推导 gripper 索引写入清洗 sidecar)。 |
| strategy | string | 否 | action 字段专用,取值 stored(直接读取)/next_state(用下一帧 state 推导)/delta_state(增量)。 |
| default | list | 否 | 当话题无消息时的默认值(如 arm 控制器未发指令时用 initial 位姿填充)。 |
| state_index | int | 否 | strategy=next_state 时引用的 state 字段索引。 |
expr 表达式语法说明:表达式中 f0、f1、... 引用 inputs 列表的第 0、1、... 项;支持算术运算(+、-、*、/)、比较运算(>、<、== 等)、条件函数 where(cond, true_val, false_val)(元素级条件选择);inputs 中每项为 locator 加索引,如/joint_states.position[joint_1] 表示 /joint_states 话题 position 字段中 joint_1 关节的值。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| bag_glob | string | *.db3 | bag文件glob匹配模式。 |
| time.stamp_source | string | auto | 时间戳来源,auto自动选择(相机优先),或指定话题名。 |
| time.tolerance_ms | int | 50 | 时间对齐容忍度(毫秒)。 |
| time.on_stale | string | hold | 数据缺失时的策略,hold保留上一帧。 |
| segment.mode | string | per_bag | 分段模式,per_bag一个bag一个episode。 |
| segment.min_frames | int | 30 | 最小帧数,少于此值的episode被丢弃。 |
- manifest 2.0中cameras顶层dict必须配置所有相机话题:相机话题缺失,将会删除相关观测feature信息。
- 不同机器人的camera第三方视角话题不同:星海图R1用/camera_head_left/camera_image_color,星海图A1Z用 /external_camera/camera_image_color,节卡用/camera_external/camera_image_color,青龙用 /camera_front/camera_image_color,优傲用/external_camera/camera_image_color。节卡为单臂,gripper_action的对应话题填一个,如/gripper_position_controller/commands。
- observation.state 和 action 的shape取决于manifest中state/action字段项的总维度。星海图R1为14维(左臂 6 关节 + 左夹爪 1 + 右臂 6 关节 + 右夹爪 1)。
task.txt任务描述文件(数据生产后若添加了描述信息会包含该文件)
task.txt为单一字符串,设置后所有episode统一使用该任务描述。
The robot uses its right arm to grasp a black-and-white pen from the table and places it into a small black cylindrical container.
task.txt为单一字符串,设置后所有episode统一使用该任务描述。
输出说明
<output_dir>/ ├── data/ │ └── chunk-000/ │ ├── episode_000000.parquet │ └── ... ├── meta/ │ ├── info.json │ ├── tasks.jsonl │ ├── episodes.jsonl │ └── episodes_stats.jsonl ├── images/ │ ├── observation.images.front/ │ └── ... └── videos/
LeRobot V2.1输出结构
<output_dir>/ ├── data/ │ └── chunk-000/ │ ├── episode_000000.parquet # 轨迹数据 │ ├── episode_000001.parquet │ └── ... ├── meta/ │ ├── info.json # 数据集基本信息(版本、帧率等) │ ├── tasks.jsonl # 任务定义(jsonl 格式) │ ├── episodes.jsonl # Episode 元信息 │ └── episodes_stats.jsonl # Episode 统计信息 ├── images/ # 图像数据(图片序列,可选) │ ├── observation.images.front/ │ ├── observation.images.wrist_left/ │ └── observation.images.wrist_right/ └── videos/ # 视频数据(V2.1 必需字段)
LeRobot V3输出结构
<output_dir>/
├── data/
│ └── chunk-000/
│ ├── file_000000.parquet
│ ├── file_000001.parquet
│ └── ...
├── meta/
│ ├── info.json # 数据集基本信息(版本、帧率、特征等)
│ ├── stats.json # 数据统计信息
│ ├── tasks.parquet # 任务定义
│ └── episodes/ # Episode 元信息
└── videos/ # 视频数据
├── observation.images.front/
├── observation.images.wrist_left/
└── observation.images.wrist_right/ 历史config.yaml兼容性
本算子同时兼容历史config.yaml 配置格式(顶层含 processor/topic_handlers/features/initial 等字段)。当数据集目录下的 *.yaml 文件不含schema_version字段时,算子按config.yaml解析。建议新数据集使用manifest 2.0格式,以获得更精细的字段配置(expr表达式、names_from: embedded自动关节名推导、source.segment多bag切分等)。manifest 2.0是后续主推配置格式,config.yaml将逐步淡出。
processor: jaka_o3de_processor.JAKAO3DEProcessor # 配置类,jaka 本体,请勿修改
fps: 5 # 根据实际视频帧率修改
repo_id: jaka_minicobo_pickplace # 根据输出数据集需要修改
initial:
arm: [1.5, 0.12, 1.06, -2.23, -0.09, -0.9076] # 机械臂初始位姿
gripper: [100]
topic_handlers:
camera:
/camera_external/camera_image_color: observation.images.external
/camera_wrist/camera_image_color: observation.images.wrist
arm_state: [/joint_states]
arm_action: [/arm_position_controller/commands]
gripper_state: [/gripper_width]
gripper_action: [/gripper_position_controller/commands]
features:
observation.state: {dtype: float64, shape: [7], names: {axes: [arm_1, arm_2, arm_3, arm_4, arm_5, arm_6, gripper]}}
action: {dtype: float64, shape: [7], names: {axes: [arm_exp_1, arm_exp_2, arm_exp_3, arm_exp_4, arm_exp_5, arm_exp_6, gripper_exp]}}
observation.images.external: {dtype: video, shape: [3, 480, 640], names: [channel, height, width]}
observation.images.wrist: {dtype: video, shape: [3, 480, 640], names: [channel, height, width]}