Parâmetros de codificação de vídeo

Quando o armazenamento em vídeo está habilitado, o LeRobot armazena cada fluxo de câmera como um arquivo MP4 em vez de salvar um arquivo de imagem por passo de tempo. A codificação de vídeo comprime ao longo do tempo, o que geralmente reduz o tamanho do conjunto de dados e a entrada/saída em comparação com uma pilha de PNG, mantendo o MP4 — um formato que todos os players e loaders entendem.

Codificar frames em um MP4 é um pipeline completo do FFmpeg: escolha do codificador, formato de pixel, GOP/keyframes, qualidade versus velocidade e flags extras opcionais do codificador. A maioria desses parâmetros é ajustável pelo usuário por meio de rgb_encoder, um RGBEncoderConfig aninhado (lerobot.configs.video.RGBEncoderConfig) passado por meio do PyAV.

Você pode definir esses parâmetros pela CLI com --dataset.rgb_encoder.<field> (por exemplo, com lerobot-record ou lerobot-rollout). O mesmo bloco se aplica a todos os fluxos de vídeo de câmera naquela execução.

O armazenamento de vídeo deve estar ativado para que rgb_encoder tenha algum efeito — use_videos=True nas APIs Python, ou --dataset.video=true na CLI (o padrão de gravação). Com o vídeo desativado, as entradas permanecem como imagens e rgb_encoder é ignorado.

Para detalhes sobre quando os frames são gravados versus codificados (streaming versus pós-episódio), filas e outros switches de nível superior --dataset.*, consulte Streaming Video Encoding. Para uma comparação de parâmetros de codificação e experimentos, consulte o video-benchmark Space.

Exemplo

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

Parâmetros de ajuste

Os padrões são ajustados para equilibrar taxa de compressão, qualidade visual e velocidade de decodificação/seek para conjuntos de dados de robótica típicos. Alterá-los pode afetar tanto a gravação (carga de CPU, quedas de quadros) quanto o treinamento (vazão de decodificação, qualidade das imagens).

Sobrescreva esses parâmetros apenas se tiver um motivo específico para isso e meça o impacto no seu pipeline antes de confiar nas novas configurações.

Todas as flags abaixo são prefixadas com --dataset.rgb_encoder. na CLI.

Streams de profundidade

Mapas de profundidade (Intel RealSense, Reachy 2) são armazenados como seus próprios fluxos de vídeo ao lado dos fluxos RGB. A profundidade bruta (uint16 em milímetros ou float32 em metros) não sobrevive a um codec de 8 bits, portanto o LeRobot quantiza cada mapa para um código de 12 bits ([0, 4095]) — logaritmicamente por padrão, para corresponder ao perfil de erro 1/depth dos sensores de profundidade — e, em seguida, o empacota em um formato de pixel de alta profundidade de bits (gray12le) e o codifica com um codec de 12 bits.

Configure o pipeline de profundidade por meio de um bloco depth_encoder paralelo (DepthEncoderConfig). Ele compartilha todos os campos de RGBEncoderConfig (vcodec, pix_fmt, crf, …) e adiciona quatro parâmetros de quantizador, definidos via --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 e shift são sempre interpretados em metros, independentemente da unidade da profundidade de entrada. As entradas são detectadas automaticamente: arrays inteiros (por exemplo, uint16 em milímetros direto de um RealSense) são tratados como milímetros, e arrays de ponto flutuante como metros. Escolha depth_min / depth_max para delimitar a faixa de trabalho real do seu sensor — quanta fora dessa faixa saturam, o que pode comprimir detalhes nas bordas.

Os recursos de profundidade são marcados com "is_depth_map": true em meta/info.json, e as configurações do quantizador deles (video.depth_min, video.depth_max, video.shift, video.use_log) são persistidas — o que permite que a profundidade seja desquantizada de volta para unidades físicas no carregamento.

Unidade de saída no momento do carregamento

depth_encoder é uma preocupação de tempo de gravação. A unidade para a qual os mapas de profundidade são desquantizados no carregamento (por exemplo, durante o treinamento) é definida separadamente pela flag de tempo de leitura --dataset.depth_output_unit:

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

Essa é uma escolha de apresentação apenas no momento da decodificação — ela não altera o vídeo armazenado nem seus metadados, de modo que o mesmo conjunto de dados pode ser lido como mm ou m sem re-codificação. Isso não afeta conjuntos de dados sem câmeras de profundidade.

Persistência nos metadados do conjunto de dados

Após o primeiro episódio de um fluxo de vídeo ser codificado, a configuração do codificador é persistida nos metadados do conjunto de dados (meta/info.json) sob cada recurso de vídeo, junto com os valores obtidos do próprio arquivo. Para um recurso de vídeo observation.images.<camera>, o layout em info.json é:

{
  "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 }
      }
    }
  }
}

Duas fontes contribuem para o bloco info:

Este bloco é preenchido uma única vez, a partir do primeiro episódio. Ele pressupõe que todos os episódios no conjunto de dados foram codificados com o mesmo rgb_encoder. Alterar as configurações do codificador no meio de uma gravação não é suportado — o info.json refletirá apenas os parâmetros usados para o primeiro episódio.

Mesclando conjuntos de dados

Ao agregar conjuntos de dados com merge_datasets, os arquivos de vídeo são concatenados como estão (sem re-codificação) e os campos do codificador em info.json são mesclados por chave: