Uso de las herramientas de conjuntos de datos

Esta guía muestra cómo explorar un conjunto de datos de LeRobot, en línea o localmente, y luego cubre las utilidades que LeRobot proporciona para modificar y editar conjuntos de datos existentes.

Explorar un conjunto de datos en el navegador

La forma más rápida de ver qué contiene un conjunto de datos de LeRobot es el LeRobot Dataset Visualizer, un Space de Hugging Face que reproduce cualquier conjunto de datos de LeRobot en el Hub, sin necesidad de instalar nada. Los conjuntos de datos que grabas con lerobot se suben al Hub a menos que decidas lo contrario, por lo que tus propias grabaciones también se abren allí.

Para probarlo con un conjunto de datos real, abra el episodio 0 de lerobot/svla_so101_pickplace, un brazo SO-101 que coloca un bloque de Lego en una caja, y siga los pasos:

1. Elige un conjunto de datos. En la página de inicio del visualizador, introduce un id de repositorio como lerobot/svla_so101_pickplace o selecciona uno de los ejemplos. Inicia sesión para abrir tus conjuntos de datos privados.

   

2. Elige un episodio. La barra lateral lista todos los episodios, bajo el total de fotogramas del conjunto de datos, el número de episodios y los FPS. Haz clic en uno para abrirlo, o usa ↑ / ↓ para navegar entre ellos.

3. Ve las grabaciones. Todas las cámaras del conjunto de datos se reproducen de forma sincronizada. Amplía una o oculta las que no necesites. La tarea del episodio, su instrucción en lenguaje natural, se muestra debajo de los vídeos.

4. Lee los datos de forma paralela. Debajo de los vídeos, el estado y las acciones del robot se grafican a lo largo de todo el episodio, con una línea por articulación. Un cursor sigue la reproducción y la leyenda muestra cada valor en el fotograma actual (o bajo el puntero mientras se pasa el ratón). Pulsa Space para reproducir o pausar, arrastra la barra de búsqueda o haz clic en un gráfico para saltar a ese momento.

   

5. Adelante. 3D Replay anima al robot a partir de las posiciones de articulaciones registradas (SO-100/SO-101, OpenArm y Unitree G1, en conjuntos de datos v3.0). Advanced incluye estadísticas del conjunto de datos, filtrado para marcar episodios problemáticos, vistas de las primeras y últimas fotogramas, e información sobre las acciones.

Enlace directo a un episodio con https://huggingface.co/spaces/lerobot/visualize_dataset?path=/<repo_id>/episode_<index>, por ejemplo, para compartir un caso de fallo con tu equipo.

Visualizar un conjunto de datos localmente

También puede visualizar episodios de un conjunto de datos localmente usando nuestra herramienta de línea de comandos.

Desde el Hugging Face Hub:

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

Para un conjunto de datos privado o con acceso restringido, autentíquese primero con hf auth login o establezca la variable de entorno HF_TOKEN. El cliente de Hub descubre la credencial automáticamente; no se necesita un argumento de token.

Desde una carpeta local: Añade la opción --root y establece --mode local. --root es la propia carpeta del conjunto de datos. Por ejemplo, para un conjunto de datos almacenado en ./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

Una vez ejecutado, la herramienta abre rerun.io y muestra las transmisiones de las cámaras, los estados del robot y las acciones del episodio seleccionado.

Para usar Foxglove en lugar de Rerun, instale el extra viz (incluye foxglove-sdk) y agregue --display-mode foxglove. Esto inicia un servidor WebSocket (conecte la aplicación Foxglove a ws://127.0.0.1:8765) que sirve el episodio como una línea de tiempo navegable que puede reproducir/pausar y desplazarse.

Para un uso avanzado, incluida la visualización de conjuntos de datos almacenados en un servidor remoto, ejecute:

lerobot-dataset-viz --help

Edición de conjuntos de datos

LeRobot proporciona varias utilidades para manipular conjuntos de datos:

1. Eliminar episodios - Elimina episodios específicos de un conjunto de datos
2. Dividir un conjunto de datos - Dividir un conjunto de datos en varios conjuntos de datos más pequeños
3. Combinar conjuntos de datos - Combina varios conjuntos de datos en uno. Los conjuntos de datos deben tener características idénticas y los episodios se concatenan en el orden especificado en repo_ids
4. Añadir características - Añadir nuevas características a un conjunto de datos
5. Eliminar características - Elimina características de un conjunto de datos
6. Modificar tareas - Cambia las descripciones de tareas en lenguaje natural asociadas a los episodios
7. Convertir a video - Convierte conjuntos de datos basados en imágenes al formato de video para un almacenamiento eficiente (las cámaras RGB y de profundidad se codifican con codificadores separados)
8. Recodificar videos - Recodifica los flujos de RGB y/o profundidad de un conjunto de datos de video existente con nuevas configuraciones de codificador
9. Mostrar la información de los conjuntos de datos - Muestra el resumen de la información de los conjuntos de datos, como el número de episodios, etc.

La implementación principal está en lerobot.datasets.dataset_tools. Un script de ejemplo que detalla cómo usar la API de herramientas está disponible en examples/dataset/use_dataset_tools.py.

Herramienta de línea de comandos: lerobot-edit-dataset

lerobot-edit-dataset es un script de línea de comandos para editar conjuntos de datos. Puede usarse para eliminar episodios, dividir conjuntos de datos, fusionar conjuntos de datos, eliminar características, modificar tareas, convertir conjuntos de datos de imágenes a formato de video, recodificar videos, recalcular estadísticas y mostrar información del conjunto de datos. Agregar características solo está disponible a través de la API de Python (lerobot.datasets.dataset_tools).

Ejecute lerobot-edit-dataset --help para obtener más información sobre la configuración de cada operación.

Ejemplos de uso

Eliminar episodios

Elimina episodios específicos de un conjunto de datos. Esto es útil para filtrar datos no deseados.

# 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 el conjunto de datos

Divide un conjunto de datos en varios 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]}'

No hay restricciones sobre los nombres de las divisiones; pueden ser determinados por el usuario. Los conjuntos de datos resultantes se guardan bajo el id del repositorio con el nombre de la división añadido, por ejemplo, lerobot/pusht_train, lerobot/pusht_task1, lerobot/pusht_task2.

Combinar conjuntos de datos

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']"

Eliminar características

Eliminar características de un conjunto de datos.

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

Modificar tareas

Cambia las descripciones de tareas en lenguaje natural asociadas a los episodios. Esto es útil para corregir errores tipográficos, estandarizar la redacción o reetiquetar episodios.

modify_tasks modifica el conjunto de datos in-place (actualizando meta/tasks.parquet, la columna task_index en los archivos de datos, la columna tasks en los metadatos del episodio y total_tasks en meta/info.json). Los parámetros --new_repo_id y --new_root se ignoran para esta operación.

# 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: una cadena de texto de una sola tarea que se usa como valor predeterminado para los episodios no cubiertos de otra manera.
• episode_tasks: Mapeo del índice de episodio a la cadena de tarea.
• task_replacements: Mapeo de cadenas de tareas existentes a sus reemplazos, aplicado a episodios cuya tarea actual coincide con una clave. Cada clave debe ser una tarea existente en el conjunto de datos.

Los modos se pueden combinar en una sola ejecución. Por episodio, la tarea se resuelve con la siguiente precedencia:

episode_tasks > task_replacements > new_task > tarea original

Al menos uno de new_task, episode_tasks o task_replacements debe especificarse. Un episodio que termina sin tarea genera un error.

Convertir a Video

Convierte un conjunto de datos basado en imágenes al formato de video, creando un nuevo LeRobotDataset donde las imágenes se almacenan como videos. Esto es útil para reducir los requisitos de almacenamiento y mejorar el rendimiento de la carga de datos. El nuevo conjunto de datos tendrá exactamente la misma estructura que el original, pero con las imágenes codificadas como videos MP4 en el formato LeRobot adecuado.

# 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: Directorio de salida personalizado (opcional; por defecto usa new_repo_id o {repo_id}_video)
• rgb_encoder: Configuración del codificador de vídeo aplicada a las cámaras RGB; todos los subcampos son accesibles mediante --operation.rgb_encoder.<field>. Consulte Parámetros de codificación de vídeo para más detalles.
• depth_encoder: Configuración del codificador de vídeo aplicada a las cámaras de mapas de profundidad (p. ej., de un Intel RealSense). Además de los campos estándar del codificador, expone los parámetros de cuantización de profundidad (depth_min, depth_max, shift, use_log), accesibles mediante --operation.depth_encoder.<field>. Estas configuraciones de cuantización se persisten en los metadatos del conjunto de datos para que la profundidad pueda descuantizarse y volver a unidades físicas al cargar. Consulte la sección Depth streams para más detalles.
• episode_indices: Lista de episodios específicos para convertir (predeterminado: todos los episodios)
• num_workers: Número de trabajadores paralelos para el procesamiento (predeterminado: 4)

Nota: El conjunto de datos resultante será un LeRobotDataset adecuado, con todas las cámaras codificadas como videos en el directorio videos/ y archivos parquet que contienen solo metadatos (sin datos de imagen crudos). Las cámaras de mapa de profundidad se detectan automáticamente y se enrutan al depth_encoder, mientras que las cámaras RGB utilizan el rgb_encoder. Se conservan todos los episodios, estadísticas y tareas.

Re-codificar videos

Re-codifica los videos de un conjunto de datos de video existente con diferentes configuraciones de codificador, sin volver a los fotogramas crudos. Los videos RGB usan el rgb_encoder y los videos de profundidad usan el depth_encoder. En la línea de comandos, ambos codificadores siempre tienen configuraciones (los valores predeterminados, a menos que los cambies), por lo que un tipo de flujo que no configures se re-codificará con las configuraciones predeterminadas, a menos que ya las esté utilizando.

# 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: Configuración del codificador aplicada a cada video RGB.
• depth_encoder: Configuración del codificador aplicada a cada video de profundidad.

Para re-codificar solo un tipo de flujo y dejar el otro sin cambios, use la API de Python y pase None para el otro codificador, por ejemplo, reencode_dataset(dataset, rgb_encoder=..., depth_encoder=None).

• num_workers: Número de trabajadores paralelos para el procesamiento.

Al recodificar videos de profundidad, los parámetros de cuantización de profundidad existentes (depth_min, depth_max, shift, use_log) y la bandera is_depth_map se conservan: recodificar solo cambia el códec/calidad del flujo almacenado, no cómo se descuantiza la profundidad al cargar.

Mostrar la información de los conjuntos de datos

Muestra la información de los conjuntos de datos, como el número de episodios, el número de fotogramas, el tamaño del archivo, etc. No se realizará ningún cambio en el conjunto de datos

# 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: Si se muestran también los detalles de las características (predeterminado: false).

Subir al Hub

Agrega la bandera --push_to_hub true a cualquier comando para subir automáticamente el conjunto de datos resultante al 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

También existe una herramienta para añadir características a un conjunto de datos que aún no está cubierta en lerobot-edit-dataset.