Utilisation des outils de jeu de données

Ce guide montre comment explorer un jeu de données LeRobot, en ligne ou localement, puis présente les utilitaires fournis par LeRobot pour modifier et éditer les jeux de données existants.

Explorer un jeu de données dans le navigateur

La façon la plus rapide de voir ce qu’un jeu de données LeRobot contient est le LeRobot Dataset Visualizer, un Space Hugging Face qui lit n’importe quel jeu de données LeRobot sur le Hub, sans rien installer. Les jeux de données que vous enregistrez avec lerobot sont poussés sur le Hub sauf si vous désactivez cette option, de sorte que vos propres enregistrements s’y ouvrent également.

Pour l’essayer sur un jeu de données réel, ouvrez l’épisode 0 de lerobot/svla_so101_pickplace, un bras SO-101 qui place une brique Lego dans une boîte, et suivez les étapes :

1. Choisissez un jeu de données. Sur la page d’accueil du visualiseur, saisissez un identifiant de dépôt tel que lerobot/svla_so101_pickplace, ou sélectionnez l’un des exemples. Connectez-vous pour accéder à vos jeux de données privés.

   

2. Choisissez un épisode. La barre latérale répertorie tous les épisodes, sous le nombre total de frames du jeu de données, le nombre d’épisodes et le FPS. Cliquez sur l’un d’eux pour l’ouvrir, ou utilisez ↑ / ↓ pour naviguer entre eux.

3. Regardez les enregistrements. Toutes les caméras du jeu de données sont synchronisées. Agrandissez-en une ou masquez celles dont vous n’avez pas besoin. La tâche de l’épisode, son instruction en langage naturel, est affichée sous les vidéos.

4. Lire les données en parallèle. Sous les vidéos, l’état du robot et ses actions sont tracés sur l’ensemble de l’épisode, une ligne par articulation. Un curseur suit la lecture, et la légende affiche chaque valeur à l’image courante (ou sous le pointeur lors du survol). Appuyez sur Space pour lire ou mettre en pause, faites glisser la barre de recherche, ou cliquez sur un graphique pour sauter à cet instant.

   

5. Allez plus loin. 3D Replay anime le robot à partir des positions articulaires enregistrées (SO-100/SO-101, OpenArm et Unitree G1, sur les jeux de données v3.0). Advanced propose des statistiques sur le jeu de données, un filtrage pour signaler les épisodes problématiques, des aperçus des premières et dernières images, ainsi que des analyses des actions.

Lien direct vers un épisode avec https://huggingface.co/spaces/lerobot/visualize_dataset?path=/<repo_id>/episode_<index>, par exemple pour partager un cas d’échec avec votre équipe.

Visualiser un jeu de données localement

Vous pouvez également visualiser localement des épisodes d'un jeu de données à l'aide de notre outil en ligne de commande.

Depos du Hugging Face Hub :

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

Pour un jeu de données privé ou protégé, authentifiez-vous d’abord avec hf auth login, ou définissez la variable d’environnement HF_TOKEN. Le client du Hub détecte ensuite automatiquement les identifiants ; aucun argument de jeton n’est nécessaire.

Depuis un dossier local : Ajoutez l'option --root et définissez --mode local. --root est le dossier du jeu de données lui-même. Par exemple, pour un jeu de données stocké dans ./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

Une fois exécuté, l’outil ouvre rerun.io et affiche les flux de caméras, les états du robot et les actions de l’épisode sélectionné.

Pour utiliser Foxglove à la place de Rerun, installez l’extra viz (qui inclut foxglove-sdk) et ajoutez --display-mode foxglove. Cela démarre un serveur WebSocket (connectez l’application Foxglove à ws://127.0.0.1:8765) qui sert l’épisode sous forme d’une chronologie navigable que vous pouvez lire/mettre en pause et parcourir.

Pour une utilisation avancée, y compris la visualisation de jeux de données stockés sur un serveur distant, exécutez :

lerobot-dataset-viz --help

Édition des jeux de données

LeRobot fournit plusieurs utilitaires pour manipuler les jeux de données :

1. Supprimer des épisodes - Supprimer des épisodes spécifiques d'un jeu de données
2. Diviser un jeu de données - Diviser un jeu de données en plusieurs jeux de données plus petits
3. Fusionner des jeux de données - Combinaison de plusieurs jeux de données en un seul. Les jeux de données doivent avoir des fonctionnalités identiques, et les épisodes sont concaténés dans l'ordre spécifié dans repo_ids
4. Ajouter des fonctionnalités - Ajouter de nouvelles fonctionnalités à un jeu de données
5. Supprimer des fonctionnalités - Supprimer des fonctionnalités d'un jeu de données
6. Modifier les tâches - Modifier les descriptions de tâches en langage naturel associées aux épisodes
7. Convertir en vidéo - Convertir les jeux de données basés sur des images au format vidéo pour un stockage efficace (les caméras RGB et de profondeur sont encodées avec des encodeurs distincts)
8. Re-coder des vidéos - Re-coder les flux RGB et/ou de profondeur d'un jeu de données vidéo existant avec de nouveaux paramètres d'encodeur
9. Afficher les informations des jeux de données - Affiche le résumé des informations des jeux de données, telles que le nombre d'épisodes, etc.

L’implémentation principale se trouve dans lerobot.datasets.dataset_tools. Un script d’exemple détaillant l’utilisation de l’API des outils est disponible dans examples/dataset/use_dataset_tools.py.

Outil en ligne de commande : lerobot-edit-dataset

lerobot-edit-dataset est un script en ligne de commande pour éditer des jeux de données. Il peut être utilisé pour supprimer des épisodes, diviser des jeux de données, fusionner des jeux de données, supprimer des fonctionnalités, modifier des tâches, convertir des jeux de données d’images au format vidéo, réencoder des vidéos, recalculer les statistiques et afficher les informations d’un jeu de données. L’ajout de fonctionnalités n’est disponible que via l’API Python (lerobot.datasets.dataset_tools).

Exécutez lerobot-edit-dataset --help pour plus d'informations sur la configuration de chaque opération.

Exemples d'utilisation

Supprimer des épisodes

Supprimez des épisodes spécifiques d'un jeu de données. Cela est utile pour filtrer les données indésirables.

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

Diviser le jeu de données

Diviser un jeu de données en plusieurs sous-ensembles.

# 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]}'

Il n'y a aucune contrainte sur les noms de sous-ensembles, ils peuvent être définis par l'utilisateur. Les ensembles de données résultants sont enregistrés sous l'identifiant du dépôt avec le nom du sous-ensemble ajouté, par exemple lerobot/pusht_train, lerobot/pusht_task1, lerobot/pusht_task2.

Fusionner des jeux de données

Combiner plusieurs jeux de données en un seul jeu de données.

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

Supprimer des fonctionnalités

Supprimer des caractéristiques d'un jeu de données.

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

Modifier les tâches

Modifiez les descriptions de tâches en langage naturel associées aux épisodes. Cela est utile pour corriger les fautes de frappe, standardiser la formulation ou reclasser les épisodes.

modify_tasks modifie le jeu de données en place (mise à jour de meta/tasks.parquet, de la colonne task_index dans les fichiers de données, de la colonne tasks dans les métadonnées des épisodes, et de total_tasks dans meta/info.json). Les paramètres --new_repo_id et --new_root sont ignorés pour cette opération.

# 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"}'

Paramètres :

• new_task : une chaîne de caractères représentant une tâche unique, utilisée par défaut pour les épisodes non couverts autrement.
• episode_tasks : Correspondance entre l'index de l'épisode et la chaîne de caractères de la tâche.
• task_replacements : Correspondance entre les chaînes de tâches existantes et leurs remplacements, appliquée aux épisodes dont la tâche actuelle correspond à une clé. Chaque clé doit être une tâche existante dans le jeu de données.

Les modes peuvent être combinés dans une seule exécution. Pour chaque épisode, la tâche est résolue selon la priorité suivante :

episode_tasks > task_replacements > new_task > tâche d'origine

Au moins un de new_task, episode_tasks ou task_replacements doit être spécifié. Un épisode qui se termine sans tâche provoque une erreur.

Convertir en vidéo

Convertir un jeu de données basé sur des images au format vidéo, en créant un nouveau LeRobotDataset où les images sont stockées sous forme de vidéos. Cette opération est utile pour réduire les besoins en stockage et améliorer les performances de chargement des données. Le nouveau jeu de données aura exactement la même structure que l'original, mais avec les images encodées en vidéos MP4 au format LeRobot approprié.

# 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

Paramètres :

• output_dir : répertoire de sortie personnalisé (facultatif - utilise par défaut new_repo_id ou {repo_id}_video)
• rgb_encoder : Paramètres de l’encodeur vidéo appliqués aux caméras RGB — tous les sous-champs sont accessibles via --operation.rgb_encoder.<field>. Consultez Paramètres d’encodage vidéo pour plus de détails.
• depth_encoder : Paramètres de l’encodeur vidéo appliqués aux caméras de cartes de profondeur (par exemple, issues d’un Intel RealSense). En plus des champs standard de l’encodeur, il expose les réglages de quantification de la profondeur (depth_min, depth_max, shift, use_log), accessibles via --operation.depth_encoder.<field>. Ces paramètres de quantification sont persistés dans les métadonnées du jeu de données afin que la profondeur puisse être déquantifiée en unités physiques lors du chargement. Consultez la section Flux de profondeur pour plus de détails.
• episode_indices : Liste des épisodes spécifiques à convertir (par défaut : tous les épisodes)
• num_workers : Nombre de travailleurs parallèles pour le traitement (par défaut : 4)

Remarque : Le jeu de données résultant sera un LeRobotDataset à part entière, avec toutes les caméras encodées en vidéos dans le répertoire videos/, et des fichiers parquet contenant uniquement des métadonnées (aucune donnée d'image brute). Les caméras de carte de profondeur sont détectées automatiquement et routées vers le depth_encoder, tandis que les caméras RGB utilisent le rgb_encoder. Tous les épisodes, statistiques et tâches sont conservés.

Re-coder des vidéos

Re-encodez les vidéos d’un jeu de données vidéo existant avec des paramètres d’encodeur différents, sans revenir aux images brutes. Les vidéos RVB utilisent rgb_encoder et les vidéos de profondeur utilisent depth_encoder. En ligne de commande, les deux encodeurs ont toujours des paramètres (les valeurs par défaut, sauf si vous les modifiez), de sorte qu’un type de flux que vous ne configurez pas est ré-encodé avec les paramètres par défaut, à moins qu’il n’utilise déjà ces paramètres.

# 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

Paramètres :

• rgb_encoder : Paramètres de l'encodeur appliqués à chaque vidéo RGB.
• depth_encoder : Paramètres de l'encodeur appliqués à chaque vidéo de profondeur.

Pour réencoder uniquement un type de flux et laisser l'autre inchangé, utilisez l'API Python et passez None pour l'autre encodeur, par exemple reencode_dataset(dataset, rgb_encoder=..., depth_encoder=None).

• num_workers : Nombre de travailleurs parallèles pour le traitement.

Lors du réencodage des vidéos de profondeur, les paramètres de quantification de profondeur existants (depth_min, depth_max, shift, use_log) et l'attribut is_depth_map sont conservés — le réencodage ne modifie que le codec/la qualité du flux stocké, et non la manière dont la profondeur est déquantifiée au chargement.

Afficher les informations des jeux de données

Affiche les informations des jeux de données, telles que le nombre d'épisodes, le nombre d'images, la taille du fichier, etc. Aucune modification ne sera apportée au jeu de données

# 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

Paramètres :

• show_features : Indique s'il faut également afficher les détails des caractéristiques (par défaut : false).

Push to Hub

Ajoutez le drapeau --push_to_hub true à n'importe quelle commande pour téléverser automatiquement le jeu de données résultant sur le 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

Il existe également un outil pour ajouter des fonctionnalités à un jeu de données, qui n'est pas encore documenté dans lerobot-edit-dataset.