Parameter encoding video

Ketika penyimpanan video diaktifkan, LeRobot menyimpan setiap aliran kamera sebagai file MP4 alih-alih menyimpan satu file gambar per langkah waktu. Pengodean video melakukan kompresi melintasi waktu, yang biasanya mengurangi ukuran dataset dan I/O dibandingkan tumpukan PNG, sambil tetap mempertahankan MP4 — format yang dipahami oleh setiap pemutar dan pemuat.

Encoding frame ke dalam MP4 adalah pipeline FFmpeg lengkap: pilihan encoder, format piksel, GOP/keyframe, kualitas vs. kecepatan, dan flag encoder tambahan opsional. Sebagian besar pengaturan ini dapat disesuaikan oleh pengguna melalui rgb_encoder, yaitu RGBEncoderConfig bersarang (lerobot.configs.video.RGBEncoderConfig) yang diteruskan melalui PyAV.

Anda dapat mengatur parameter ini dari CLI dengan --dataset.rgb_encoder.<field> (misalnya dengan lerobot-record atau lerobot-rollout). Blok yang sama berlaku untuk setiap stream video kamera dalam run tersebut.

Penyimpanan video harus diaktifkan agar rgb_encoder memiliki efek — gunakan use_videos=True pada API Python, atau --dataset.video=true pada CLI (default perekaman). Jika video dimatikan, input tetap berupa gambar dan rgb_encoder diabaikan.

Untuk detail mengenai kapan frame ditulis vs. di-encode (streaming vs. pasca-episode), antrean, dan sakelar --dataset.* tingkat atas lainnya, lihat Streaming Video Encoding. Untuk perbandingan parameter encoding dan eksperimen, lihat ruang video-benchmark.

Contoh

lerobot-record \
    --robot.type=so100_follower \
    --robot.port=/dev/tty.usbmodem58760431541 \
    --robot.cameras="{laptop: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
    --robot.id=black \
    --teleop.type=so100_leader \
    --teleop.port=/dev/tty.usbmodem58760431551 \
    --teleop.id=blue \
    --dataset.repo_id=<my_username>/<my_dataset_name> \
    --dataset.num_episodes=2 \
    --dataset.single_task="Grab the cube" \
    --dataset.streaming_encoding=true \
    --dataset.encoder_threads=2 \
    --dataset.rgb_encoder.vcodec=h264 \
    --dataset.rgb_encoder.preset=fast \
    --dataset.rgb_encoder.extra_options='{"tune": "film", "profile:v": "high", "bf": 2}' \
    --display_data=true

Menyetel parameter

Nilai bawaarannya disetel untuk menyeimbangkan rasio kompresi, kualitas visual, dan kecepatan decoding/seek untuk dataset robotika yang umum. Mengubahnya dapat memengaruhi baik perekaman (beban CPU, frame drop) maupun pelatihan (throughput decoding, kualitas gambar).

Hanya timpa parameter ini jika Anda memiliki alasan spesifik, dan ukur dampaknya pada pipeline Anda sebelum mengandalkan pengaturan baru.

Semua flag di bawah ini memiliki awalan --dataset.rgb_encoder. pada CLI.

Aliran kedalaman

Peta kedalaman (Intel RealSense, Reachy 2) disimpan sebagai stream video tersendiri di samping stream RGB. Kedalaman mentah (uint16 milimeter atau float32 meter) tidak dapat bertahan melalui codec 8-bit, sehingga LeRobot mengkuantisasi setiap peta menjadi kode 12-bit ([0, 4095]) — secara logaritmik secara default, untuk mencocokkan profil kesalahan 1/depth dari sensor kedalaman — kemudian mengemasnya ke dalam format piksel dengan kedalaman bit tinggi (gray12le) dan mengenkodinya dengan codec 12-bit.

Konfigurasi pipeline kedalaman melalui blok depth_encoder paralel (DepthEncoderConfig). Blok ini berbagi setiap field RGBEncoderConfig (vcodec, pix_fmt, crf, …) dan menambahkan empat knob kuantizer, yang diatur melalui --dataset.depth_encoder.<field>:

lerobot-record \
    ... \
    --dataset.depth_encoder.vcodec=hevc \
    --dataset.depth_encoder.depth_min=0.05 \
    --dataset.depth_encoder.depth_max=5.0 \
    --dataset.depth_encoder.use_log=true

depth_min, depth_max, dan shift selalu diinterpretasikan dalam meter, terlepas dari unit kedalaman input. Input dideteksi secara otomatis: array bilangan bulat (misalnya uint16 milimeter langsung dari RealSense) diperlakukan sebagai milimeter, sedangkan array bilangan desimal sebagai meter. Pilih depth_min / depth_max untuk membatasi rentang kerja aktual sensor Anda — kuantum di luar rentang tersebut akan jenuh, yang dapat merusak detail di batas-batasnya.

Fitur kedalaman ditandai dengan "is_depth_map": true di meta/info.json, dan pengaturan kuantizernya (video.depth_min, video.depth_max, video.shift, video.use_log) disimpan — hal inilah yang memungkinkan kedalaman untuk didekuantisasi kembali ke satuan fisik saat dimuat.

Unit output saat pemuatan

depth_encoder adalah masalah pada waktu perekaman. Unit yang digunakan untuk mendekuantisasi peta kedalaman saat memuat (misalnya selama pelatihan) diatur secara terpisah oleh flag waktu baca --dataset.depth_output_unit:

lerobot-train \
    --dataset.repo_id=<my_username>/<my_dataset_name> \
    --dataset.depth_output_unit=m \
    --policy.type=act

Ini murni pilihan presentasi pada waktu decode — hal ini tidak mengubah video yang disimpan atau metadatanya, sehingga dataset yang sama dapat dibaca sebagai mm atau m tanpa re-encoding. Hal ini tidak berdampak pada dataset tanpa kamera kedalaman.

Persistensi dalam metadata dataset

Setelah episode pertama dari aliran video dikodekan, konfigurasi encoder disimpan ke dalam metadata dataset (meta/info.json) di bawah setiap fitur video, berdampingan dengan nilai yang diambil dari file itu sendiri. Untuk fitur video observation.images.<camera>, tata letak di info.json adalah:

{
  "features": {
    "observation.images.laptop": {
      "dtype": "video",
      "shape": [480, 640, 3],
      "info": {
        "video.height": 480,
        "video.width": 640,
        "video.codec": "h264",
        "video.pix_fmt": "yuv420p",
        "video.fps": 30,
        "video.channels": 3,
        "is_depth_map": false,
        "video.g": 2,
        "video.crf": 30,
        "video.preset": "fast",
        "video.fast_decode": 0,
        "video.video_backend": "pyav",
        "video.extra_options": { "tune": "film", "profile:v": "high", "bf": 2 }
      }
    }
  }
}

Dua sumber berkontribusi pada blok info:

Blok ini diisi sekali, dari episode pertama. Blok ini mengasumsikan setiap episode dalam dataset dikodekan dengan rgb_encoder yang sama. Mengubah pengaturan encoder di tengah perekaman tidak didukung — info.json hanya akan mencerminkan parameter yang digunakan untuk episode pertama.

Menggabungkan dataset

Saat mengagregasi dataset dengan merge_datasets, file video digabungkan apa adanya (tanpa re-encoding), dan field encoder di info.json digabungkan per kunci: