更新时间:2026-11-13 GMT+08:00
分享

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配置文件。

表1 参数说明

参数名

是否必填

默认值

可选值

说明

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
表2 字段说明

字段

类型

必填

说明

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 关节的值。

表3 source子字段说明

字段

类型

默认值

说明

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将逐步淡出。

节卡(jaka)
 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]}

相关文档