isaac_ros_mcap_lerobot_converter#

Source code available on GitHub.

Overview#

Converts MCAP rosbags produced by isaac_ros_unitree_g1_recorder into a LeRobot dataset that the external GR00T N fine-tuning script can consume. The tool is a pure Python package — no ROS installation is required — and can be run on the host instead of inside the Isaac ROS dev container to avoid PyTorch version conflicts with the training environment.

For a narrative walk-through, see Convert MCAP Bags to a LeRobot Dataset.

Tutorial: Convert MCAP Bags to a LeRobot Dataset#

Prerequisites#

Install the Converter#

  1. Clone the repository under ${ISAAC_ROS_WS}/src:

    cd ${ISAAC_ROS_WS}/src && \
       git clone -b release-5.1 https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_data_tools.git isaac_ros_data_tools
    
  2. Create a virtual environment and install the converter in editable mode. Run on the host, not inside the Isaac ROS dev container:

    cd ${ISAAC_ROS_WS}/src/isaac_ros_data_tools/isaac_ros_mcap_lerobot_converter
    uv venv --python 3.12 .venv
    source .venv/bin/activate
    uv pip install -e .
    

Run the Conversion#

Point --rosbags-dir at the recorder session directory. Both flat (rosbags_dir/<episode>/metadata.yaml) and nested (rosbags_dir/<episode>/bag/metadata.yaml) layouts are auto-detected:

mcap-to-lerobot \
    --rosbags-dir ~/workspaces/isaac/recordings/session_<TIMESTAMP> \
    --output-dir ~/workspaces/isaac/recordings/lerobot_output \
    --task "move the apple to the plate" \
    --fps 30 --embodiment unitree_g1

Replace <TIMESTAMP> with the session you want to convert (the recorder printed the host path when it started). The output directory contains a standard LeRobot dataset (meta/, videos/, data/) ready as input to the fine-tuning step.

To merge multiple recording sessions into one dataset, repeat --rosbags-dir once per session. Episodes are numbered sequentially across the supplied directories in the order given:

mcap-to-lerobot \
    --rosbags-dir ~/workspaces/isaac/recordings/session_A \
    --rosbags-dir ~/workspaces/isaac/recordings/session_B \
    --output-dir ~/workspaces/isaac/recordings/lerobot_output \
    --task "move the apple to the plate" \
    --fps 30 --embodiment unitree_g1

Use recordings with the same sync_rate in a batch. The first bag discovered in input argument order supplies the detected rate. Omitting --fps retains recorded timing and rounds that rate for the dataset label. A supplied --fps retains timing within 5% of the detected rate; larger mismatches resample the batch, or fail with --strict-fps.

API#

CLI Arguments#

Argument

Required

Description

--rosbags-dir

yes

Directory of bag folders (each must contain metadata.yaml). Repeat the flag to merge multiple recording sessions into one dataset; episodes are numbered sequentially across the supplied directories in the order given.

--output-dir

yes

Output directory for the LeRobot dataset; it must not already exist.

--task

yes

Task description label written to the dataset’s tasks.jsonl.

--fps

no

Dataset fps label, written to info.json; detected from /record_data and rounded to an integer when omitted, without resampling. To retain recorded timing, use the recorder’s sync_rate (30 for the Unitree G1 recorder default) within 5% of the detected rate. Larger mismatches resample the batch, or fail with --strict-fps, as described above.

--embodiment

no

Embodiment used for the dataset schema and the robot type label written to info.json (default unitree_g1).

Output Layout#

<output-dir>/
    meta/
        info.json            # dataset metadata
        episodes.jsonl       # per-episode length + task
        tasks.jsonl          # task labels
        modality.json        # joint-to-modality mapping
    data/chunk-000/episode_<idx>.parquet   # per-episode tabular data
    videos/chunk-000/.../episode_<idx>.mp4 # per-episode camera video