Usando as Ferramentas de Conjunto de Dados

Este guia mostra como explorar um dataset do LeRobot, online ou localmente, e em seguida aborda as utilidades que o LeRobot oferece para modificar e editar datasets existentes.

Explore um Dataset no Navegador

A maneira mais rápida de ver o que um dataset LeRobot contém é o LeRobot Dataset Visualizer, um Hugging Face Space que reproduz qualquer dataset LeRobot no Hub, sem necessidade de instalar nada. Os datasets que você grava com lerobot são enviados para o Hub, a menos que você opte por não fazê-lo, então suas próprias gravações também abrem lá.

Para testar em um dataset real, abra o episódio 0 de lerobot/svla_so101_pickplace, um braço SO-101 colocando um bloco de lego em uma caixa, e siga o processo:

1. Escolha um conjunto de dados. Na página inicial do visualizador, insira um id de repositório, como lerobot/svla_so101_pickplace, ou selecione um dos exemplos. Faça login para abrir seus conjuntos de dados privados.

   

2. Escolha um episódio. A barra lateral lista todos os episódios, abaixo do total de quadros do conjunto de dados, da contagem de episódios e do FPS. Clique em um para abri-lo ou use ↑ / ↓ para navegar entre eles.

3. Assista às gravações. Todas as câmeras do conjunto de dados reproduzem em sincronia. Amplie uma delas ou oculte as que você não precisa. A tarefa do episódio, sua instrução em linguagem natural, é exibida abaixo dos vídeos.

4. Leia os dados em paralelo. Abaixo dos vídeos, o estado e as ações do robô são plotados ao longo de todo o episódio, com uma linha por junta. Um cursor acompanha a reprodução, e a legenda exibe cada valor no quadro atual (ou sob o ponteiro enquanto você passa o mouse). Pressione Space para reproduzir ou pausar, arraste a barra de busca ou clique em um gráfico para pular para aquele momento.

   

5. Vá além. 3D Replay anima o robô a partir das posições articulares gravadas (SO-100/SO-101, OpenArm e Unitree G1, em datasets v3.0). Avançado oferece estatísticas do dataset, filtragem para sinalizar episódios problemáticos, visões gerais dos primeiros/últimos frames e insights de ação.

Link direto para um episódio com https://huggingface.co/spaces/lerobot/visualize_dataset?path=/<repo_id>/episode_<index>, por exemplo, para compartilhar um caso de falha com sua equipe.

Visualize um Dataset Localmente

Você também pode visualizar episódios de um dataset localmente usando nossa ferramenta de linha de comando.

Do Hugging Face Hub:

lerobot-dataset-viz \
    --repo-id lerobot/pusht \
    --episode-index 0

Para um conjunto de dados privado ou restrito, autentique-se primeiro com hf auth login ou defina a variável de ambiente HF_TOKEN. O cliente do Hub então descobre a credencial automaticamente; nenhum argumento de token é necessário.

A partir de uma pasta local: Adicione a opção --root e defina --mode local. --root é a própria pasta do dataset. Por exemplo, para um dataset armazenado em ./my_local_data_dir/lerobot/pusht:

lerobot-dataset-viz \
    --repo-id lerobot/pusht \
    --root ./my_local_data_dir/lerobot/pusht \
    --mode local \
    --episode-index 0

Uma vez executado, a ferramenta abre o rerun.io e exibe os fluxos de câmera, os estados do robô e as ações do episódio selecionado.

Para usar o Foxglove em vez do Rerun, instale o extra viz (ele inclui o foxglove-sdk) e adicione --display-mode foxglove. Isso inicia um servidor WebSocket (conecte o aplicativo Foxglove a ws://127.0.0.1:8765) que serve o episódio como uma linha do tempo navegável, que você pode reproduzir/pausar e navegar.

Para uso avançado — incluindo a visualização de conjuntos de dados armazenados em um servidor remoto — execute:

lerobot-dataset-viz --help

Editando Conjuntos de Dados

O LeRobot fornece várias utilidades para manipular conjuntos de dados:

1. Excluir episódios - Remove episódios específicos de um conjunto de dados
2. Dividir Dataset - Dividir um dataset em vários datasets menores
3. Mesclar conjuntos de dados - Combina vários conjuntos de dados em um único. Os conjuntos de dados devem ter recursos idênticos, e os episódios são concatenados na ordem especificada em repo_ids
4. Adicionar recursos - Adicionar novos recursos a um conjunto de dados
5. Remover recursos - Remove recursos de um dataset
6. Modificar tarefas - Altere as descrições de tarefas em linguagem natural associadas aos episódios
7. Converter para vídeo - Converte conjuntos de dados baseados em imagens para o formato de vídeo para armazenamento eficiente (câmeras RGB e de profundidade são codificadas com codificadores separados)
8. Re-codificar vídeos - Re-codifique os fluxos de RGB e/ou profundidade de um conjunto de dados de vídeo existente com novas configurações de codificador
9. Exibir as informações dos conjuntos de dados - Exibe o resumo das informações dos conjuntos de dados, como o número de episódios, etc.

A implementação principal está em lerobot.datasets.dataset_tools. Um script de exemplo detalhando como usar a API de ferramentas está disponível em examples/dataset/use_dataset_tools.py.

Ferramenta de Linha de Comando: lerobot-edit-dataset

lerobot-edit-dataset é um script de linha de comando para editar conjuntos de dados. Ele pode ser usado para excluir episódios, dividir conjuntos de dados, mesclar conjuntos de dados, remover recursos, modificar tarefas, converter conjuntos de dados de imagem para o formato de vídeo, re-codificar vídeos, recalcular estatísticas e exibir informações do conjunto de dados. Adicionar recursos está disponível apenas por meio da API em Python (lerobot.datasets.dataset_tools).

Execute lerobot-edit-dataset --help para obter mais informações sobre a configuração de cada operação.

Exemplos de uso

Excluir Episódios

Remove episódios específicos de um conjunto de dados. Isso é útil para filtrar dados indesejados.

# Delete episodes 0, 2, and 5 (modifies original dataset)
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type delete_episodes \
    --operation.episode_indices "[0, 2, 5]"

# Delete episodes and save to a new dataset (preserves original dataset)
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --new_repo_id lerobot/pusht_after_deletion \
    --operation.type delete_episodes \
    --operation.episode_indices "[0, 2, 5]"

Dividir Dataset

Divide um conjunto de dados em vários subconjuntos.

# Split by fractions (e.g. 60% train, 20% val, 20% test)
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type split \
    --operation.splits '{"train": 0.6, "val": 0.2, "test": 0.2}'

# Split by specific episode indices
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type split \
    --operation.splits '{"task1": [0, 1, 2, 3], "task2": [4, 5]}'

Não há restrições aos nomes das divisões; eles podem ser definidos pelo usuário. Os conjuntos de dados resultantes são salvos sob o id do repositório com o nome da divisão anexado, por exemplo, lerobot/pusht_train, lerobot/pusht_task1, lerobot/pusht_task2.

Mesclar Conjuntos de Dados

Combine multiple datasets into a single dataset.

# Merge train and validation splits back into one dataset
lerobot-edit-dataset \
    --new_repo_id lerobot/pusht_merged \
    --operation.type merge \
    --operation.repo_ids "['lerobot/pusht_train', 'lerobot/pusht_val']"

Remover recursos

Remove recursos de um conjunto de dados.

# Remove a camera feature
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type remove_feature \
    --operation.feature_names "['observation.images.top']"

Modificar Tarefas

Alterar as descrições de tarefas em linguagem natural associadas aos episódios. Isso é útil para corrigir erros de digitação, padronizar a redação ou reclassificar episódios.

modify_tasks modifica o dataset in-place (atualizando meta/tasks.parquet, a coluna task_index nos arquivos de dados, a coluna tasks nos metadados do episódio e total_tasks em meta/info.json). Os parâmetros --new_repo_id e --new_root são ignorados para esta operação.

# Set a single task for all episodes
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type modify_tasks \
    --operation.new_task "Pick up the cube and place it"

# Set different tasks for specific episodes
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type modify_tasks \
    --operation.episode_tasks '{"0": "Task A", "1": "Task B", "2": "Task A"}'

# Replace existing task strings wherever they appear
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type modify_tasks \
    --operation.task_replacements '{"Pick up the red cube": "Lift the red cube"}'

# Combine modes in a single run
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type modify_tasks \
    --operation.new_task "Default task" \
    --operation.task_replacements '{"Pick up the red cube": "Lift the red cube"}' \
    --operation.episode_tasks '{"5": "Special task for episode 5"}'

Parâmetros:

• new_task: Uma string de tarefa única usada como padrão para episódios não cobertos de outra forma.
• episode_tasks: Mapeamento do índice do episódio para a string da tarefa.
• task_replacements: Mapeamento de strings de tarefas existentes para suas substituições, aplicado a episódios cuja tarefa atual corresponde a uma chave. Cada chave deve ser uma tarefa existente no conjunto de dados.

Os modos podem ser combinados em uma única execução. Por episódio, a tarefa é resolvida com a seguinte precedência:

episode_tasks > task_replacements > new_task > tarefa original

Pelo menos um de new_task, episode_tasks ou task_replacements deve ser especificado. Um episódio que termina sem nenhuma tarefa gera um erro.

Converter para Vídeo

Converte um dataset baseado em imagens para o formato de vídeo, criando um novo LeRobotDataset em que as imagens são armazenadas como vídeos. Isso é útil para reduzir os requisitos de armazenamento e melhorar o desempenho de carregamento de dados. O novo dataset terá exatamente a mesma estrutura do original, mas com as imagens codificadas como vídeos MP4 no formato LeRobot adequado.

# Local-only: Save to a custom output directory (no hub push)
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_image_to_video \
    --operation.output_dir /path/to/output/pusht_video

# Save with new repo_id (local storage)
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --new_repo_id lerobot/pusht_video \
    --operation.type convert_image_to_video

# Convert and push to Hugging Face Hub
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --new_repo_id lerobot/pusht_video \
    --operation.type convert_image_to_video \
    --push_to_hub true

# Convert with custom video codec and quality settings
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_image_to_video \
    --operation.output_dir outputs/pusht_video \
    --operation.rgb_encoder.vcodec libsvtav1 \
    --operation.rgb_encoder.pix_fmt yuv420p \
    --operation.rgb_encoder.g 2 \
    --operation.rgb_encoder.crf 30

# Convert a dataset that includes depth maps, customizing the depth encoder
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_image_to_video \
    --operation.output_dir outputs/pusht_video \
    --operation.depth_encoder.depth_min 0.01 \
    --operation.depth_encoder.depth_max 10.0 \
    --operation.depth_encoder.use_log true

# Convert only specific episodes
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_image_to_video \
    --operation.output_dir outputs/pusht_video \
    --operation.episode_indices "[0, 1, 2, 5, 10]"

# Convert with multiple workers for parallel processing
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_image_to_video \
    --operation.output_dir outputs/pusht_video \
    --operation.num_workers 8

# For memory-constrained systems, users can now specify limits:
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_image_to_video \
    --operation.max_episodes_per_batch 50 \
    --operation.max_frames_per_batch 10000

Parâmetros:

• output_dir: Diretório de saída personalizado (opcional - por padrão, usa new_repo_id ou {repo_id}_video)
• rgb_encoder: Configurações do codificador de vídeo aplicadas às câmeras RGB — todos os subcampos acessíveis via --operation.rgb_encoder.<field>. Consulte Parâmetros de codificação de vídeo para mais detalhes.
• depth_encoder: Configurações do codificador de vídeo aplicadas a câmeras de mapa de profundidade (por exemplo, de um Intel RealSense). Além dos campos padrão do codificador, expõe os controles de quantização de profundidade (depth_min, depth_max, shift, use_log), acessíveis via --operation.depth_encoder.<field>. Essas configurações de quantização são persistidas nos metadados do conjunto de dados para que a profundidade possa ser desquantizada de volta para unidades físicas ao carregar. Consulte a seção Streams de profundidade para mais detalhes.
• episode_indices: Lista de episódios específicos para converter (padrão: todos os episódios)
• num_workers: Número de workers paralelos para processamento (padrão: 4)

Observação: O dataset resultante será um LeRobotDataset adequado, com todas as câmeras codificadas como vídeos no diretório videos/, e arquivos parquet contendo apenas metadados (sem dados de imagem brutos). Câmeras de mapa de profundidade são detectadas automaticamente e direcionadas ao depth_encoder, enquanto câmeras RGB usam o rgb_encoder. Todos os episódios, estatísticas e tarefas são preservados.

Re-codificar Vídeos

Re-codifique os vídeos de um conjunto de dados de vídeo existente com configurações de codificador diferentes, sem voltar aos quadros brutos. Vídeos RGB usam o rgb_encoder e vídeos de profundidade usam o depth_encoder. Na linha de comando, ambos os codificadores sempre têm configurações (os padrões, a menos que você os altere), portanto, um tipo de fluxo que você não configura é re-codificado com as configurações padrão, a menos que já as utilize.

# Re-encode all RGB videos with new settings (saves to lerobot/pusht_reencoded by default)
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type reencode_videos \
    --operation.rgb_encoder.vcodec h264 \
    --operation.rgb_encoder.pix_fmt yuv420p \
    --operation.rgb_encoder.crf 23

# Re-encode both RGB and depth videos in a dataset with depth maps
lerobot-edit-dataset \
    --repo_id lerobot/pusht_depth \
    --operation.type reencode_videos \
    --operation.rgb_encoder.vcodec h264 \
    --operation.depth_encoder.crf 50

Parâmetros:

• rgb_encoder: Configurações do encoder aplicadas a todos os vídeos RGB.
• depth_encoder: Configurações do encoder aplicadas a cada vídeo de profundidade.

Para re-codificar apenas um tipo de stream e deixar o outro intacto, use a API em Python e passe None para o outro codificador, por exemplo, reencode_dataset(dataset, rgb_encoder=..., depth_encoder=None).

• num_workers: Número de workers paralelos para processamento.

Ao re-codificar vídeos de profundidade, os parâmetros de quantização de profundidade existentes (depth_min, depth_max, shift, use_log) e a flag is_depth_map são preservados — a re-codificação altera apenas o codec/qualidade do stream armazenado, não a forma como a profundidade é desquantizada no carregamento.

Exibir as informações dos conjuntos de dados

Exibe as informações dos conjuntos de dados, como o número de episódios, o número de quadros, o tamanho do arquivo, entre outras. Nenhuma alteração será feita no conjunto de dados

# Show dataset information without feature details
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type info

# Show dataset information with feature details
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type info \
    --operation.show_features true

Parâmetros:

• show_features: Se os detalhes dos recursos também devem ser exibidos (padrão: false).

Push to Hub

Adicione a flag --push_to_hub true a qualquer comando para enviar automaticamente o dataset resultante para o Hugging Face Hub:

lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --new_repo_id lerobot/pusht_after_deletion \
    --operation.type delete_episodes \
    --operation.episode_indices "[0, 2, 5]" \
    --push_to_hub true

Também existe uma ferramenta para adicionar recursos a um conjunto de dados que ainda não é coberto em lerobot-edit-dataset.