LeRobot documentation
Dataset Toolsの使用
Dataset Toolsの使用
このガイドでは、LeRobot データセットをオンラインまたはローカルで探索する方法を示し、その後、既存のデータセットを変更・編集するための LeRobot が提供するユーティリティについて説明します。
ブラウザでデータセットを探索する
LeRobot データセットの内容を素早く確認する最速の方法は、LeRobot Dataset Visualizerです。これは Hugging Face Space であり、インストールなしで Hub 上の任意の LeRobot データセットを再生できます。lerobot で記録したデータセットは、オプトアウトしない限り Hub にプッシュされるため、ご自身の記録もそこで開くことができます。
実際のデータセットで試すには、lerobot/svla_so101_pickplace のエピソード 0（SO-101 アームが箱にレゴブロックを置く様子）を開き、以下の手順に従ってください。
データセットを選択します。ビジュアライザーのホームページで、
lerobot/svla_so101_pickplaceのようなリポジトリIDを入力するか、例の一つを選択します。プライベートなデータセットを開くには、サインインしてください。
エピソードを選択します。 サイドバーには、データセットの総フレーム数、エピソード数、FPSの下に、すべてのエピソードがリスト表示されます。クリックして開くか、
↑/↓を使用して切り替えます。録画映像を確認します。 データセット内のすべてのカメラが同期して再生されます。特定のカメラを拡大表示したり、不要なカメラを非表示にしたりできます。エピソードのタスクである言語指示は、動画の下に表示されます。
データを並べて読み取る。 ビデオの下には、エピソード全体にわたってロボットの状態とアクションがグラフ化されており、各関節ごとに1行表示されます。カーソルは再生に追従し、凡例には現在のフレーム（またはホバー中はポインターの下）の各値が表示されます。
Spaceキーを押して再生または一時停止し、シークバーをドラッグするか、グラフをクリックしてその時点にジャンプできます。
さらに詳しく。 3D Replayは、記録された関節位置からロボットをアニメーション表示します（SO-100/SO-101、OpenArm、Unitree G1、v3.0 データセット対応）。Advancedには、データセットの統計情報、問題のあるエピソードをフラグ付けするためのフィルタリング、最初のフレーム/最後のフレームの概要、アクションのインサイトが含まれます。
https://huggingface.co/spaces/lerobot/visualize_dataset?path=/<repo_id>/episode_<index>を使用すると、エピソードに直接リンクできます。例えば、チーム内で失敗ケースを共有する際に便利です。
Datasetをローカルで可視化
コマンドラインツールを使用して、ローカルでデータセットのエピソードを可視化することもできます。
Hugging Face Hubから:
lerobot-dataset-viz \
--repo-id lerobot/pusht \
--episode-index 0プライベートまたはゲート付きのデータセットを使用する場合は、まずhf auth loginで認証するか、HF_TOKEN環境変数を設定してください。その後、Hubクライアントは認証情報を自動的に検出するため、トークン引数は不要です。
ローカルフォルダーから: --rootオプションを追加し、--mode localを設定します。--rootはデータセットフォルダー自体です。例えば、./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実行すると、ツールはrerun.ioを開き、選択したエピソードのカメラストリーム、ロボットの状態、およびアクションを表示します。
Rerun の代わりに Foxglove を使用するには、viz エクストラ（foxglove-sdk を含む）をインストールし、--display-mode foxglove を追加します。これにより WebSocket サーバーが起動し（Foxglove アプリを ws://127.0.0.1:8765 に接続します）、エピソードをシーク可能なタイムラインとして配信します。再生/一時停止やスクラブ操作が可能です。
高度な利用方法（リモートサーバーに保存されたデータセットの可視化を含む）では、以下を実行します：
lerobot-dataset-viz --helpデータセットの編集
LeRobotは、データセットを操作するためのいくつかのユーティリティを提供しています：
- エピソードの削除 - データセットから特定のエピソードを削除します
- Split Dataset - データセットを複数の小さなデータセットに分割します
- データセットのマージ - 複数のデータセットを1つに結合します。データセットは同一のフィーチャーを持つ必要があり、エピソードは
repo_idsで指定された順序で連結されます。 - 機能の追加 - データセットに新しい機能を追加します
- 機能の削除 - データセットから機能を削除します
- タスクの変更 - エピソードに関連付けられた自然言語のタスク説明を変更します
- Videoへ変換 - 画像ベースのデータセットを、効率的なストレージのために動画形式に変換します（RGBカメラと深度カメラはそれぞれ別のエンコーダーでエンコードされます）
- 動画の再エンコード - 既存の動画データセットのRGBおよび/または深度ストリームを、新しいエンコーダー設定で再エンコードします
- データセットの情報を表示 - エピソード数などのデータセット情報の概要を表示します。
コア実装はlerobot.datasets.dataset_toolsにあります。
ツールAPIの使用方法を示すサンプルスクリプトはexamples/dataset/use_dataset_tools.pyで利用できます。
コマンドラインツール: lerobot-edit-dataset
lerobot-edit-datasetは、データセットを編集するためのコマンドラインスクリプトです。エピソードの削除、データセットの分割、データセットのマージ、特徴量の削除、タスクの変更、画像データセットの動画形式への変換、動画の再エンコード、統計情報の再計算、データセット情報の表示に使用できます。特徴量の追加は、Python API（lerobot.datasets.dataset_tools）でのみ利用可能です。
各操作の設定に関する詳細については、lerobot-edit-dataset --helpを実行してください。
使用例
エピソードの削除
データセットから特定のエピソードを削除します。これは、不要なデータをフィルタリングするために便利です。
# 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]"Split Dataset
データセットを複数のサブセットに分割します。
# 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]}'スプリット名に制約はなく、ユーザーが決定できます。生成されたデータセットは、リポジトリ ID にスプリット名を付加した形で保存されます。例えば、lerobot/pusht_train、lerobot/pusht_task1、lerobot/pusht_task2 などです。
データセットのマージ
複数のデータセットを単一のデータセットに結合します。
# 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']"機能の削除
データセットから特徴を削除します。
# Remove a camera feature
lerobot-edit-dataset \
--repo_id lerobot/pusht \
--operation.type remove_feature \
--operation.feature_names "['observation.images.top']"タスクの変更
エピソードに付随する自然言語のタスク説明を変更します。これは、タイポの修正、表現の標準化、エピソードのラベル付けのやり直しに役立ちます。
modify_tasksは、データセットをインプレースで変更します（meta/tasks.parquet、データファイル内のtask_index列、エピソードメタデータ内のtasks列、およびmeta/info.json内のtotal_tasksを更新します）。この操作では、--new_repo_idおよび--new_rootパラメータは無視されます。
# 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"}'パラメータ:
new_task: 他に指定されていないエピソードのデフォルトとして使用される単一のタスク文字列。episode_tasks: エピソードインデックスからタスク文字列へのマッピング。task_replacements: 既存のタスク文字列からその代替文字列へのマッピング。現在のタスクがキーと一致するエピソードに適用されます。すべてのキーは、データセットに存在するタスクである必要があります。
モードは1回の実行内で組み合わせることができます。エピソードごとに、タスクは以下の優先順位で解決されます。
episode_tasks > task_replacements > new_task > 元のタスク
new_task、episode_tasks、task_replacementsのいずれか少なくとも1つを指定する必要があります。タスクが1つも残らないエピソードではエラーが発生します。
動画に変換
画像ベースのデータセットを動画形式に変換し、画像を動画として保存する新しいLeRobotDatasetを作成します。これはストレージ要件の削減とデータ読み込みパフォーマンスの向上に役立ちます。新しいデータセットは元のデータセットと完全に同じ構造を持ちますが、画像は適切なLeRobot形式でMP4動画としてエンコードされます。
# 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パラメータ:
output_dir: カスタム出力ディレクトリ（省略可能 - デフォルトではnew_repo_idまたは{repo_id}_videoを使用）rgb_encoder: RGBカメラに適用されるビデオエンコーダーの設定 — すべてのサブフィールドは--operation.rgb_encoder.<field>を介してアクセスできます。詳細はVideo Encoding Parametersを参照してください。depth_encoder: 深度マップカメラ（Intel RealSense など）に適用されるビデオエンコーダーの設定です。標準的なエンコーダーフィールドに加えて、深度量子化の調整項目（depth_min、depth_max、shift、use_log）を公開しており、--operation.depth_encoder.<field>を介してアクセスできます。これらの量子化設定はデータセットのメタデータに永続化されるため、読み込み時に深度を物理単位へ逆量子化できます。詳細はDepth streamsセクションを参照してください。episode_indices: 変換する特定のエピソードのリスト（デフォルト: 全エピソード）num_workers: 処理用の並列ワーカー数（デフォルト: 4）
注: 生成されるデータセットは、videos/ ディレクトリ内にすべてのカメラが動画としてエンコードされた、適切な LeRobotDataset になります。parquet ファイルにはメタデータのみが含まれ、生の画像データは含まれません。深度マップカメラは自動的に検出され、depth_encoder にルーティングされ、RGB カメラは rgb_encoder が使用されます。すべてのエピソード、統計情報、タスクは保持されます。
動画の再エンコード
既存の動画データセットの動画を、生フレームに戻すことなく、異なるエンコーダー設定で再エンコードします。RGB動画にはrgb_encoderが、深度動画にはdepth_encoderが使用されます。コマンドラインでは、両方のエンコーダーには常に設定（変更しない限りデフォルト値）が存在するため、設定していないストリームタイプは、既にデフォルト設定を使用していない限り、デフォルト設定で再エンコードされます。
# 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パラメータ:
rgb_encoder: すべてのRGB動画に適用されるエンコーダーの設定。depth_encoder: すべての深度ビデオに適用されるエンコーダーの設定。
ストリームタイプを1つだけ再エンコードし、もう1つは変更しない場合は、Python APIを使用し、もう1つのエンコーダーにNoneを渡します。例: reencode_dataset(dataset, rgb_encoder=..., depth_encoder=None)。
num_workers: 処理用の並列ワーカー数。
深度ビデオを再エンコードする際、既存の深度量子化パラメータ（
depth_min、depth_max、shift、use_log）およびis_depth_mapフラグは保持されます。再エンコードは保存されたストリームのコーデックや品質を変更するだけで、読み込み時の深度のデ量子化の方式は変更されません。
データセットの情報を表示します
エピソード数、フレーム数、ファイルサイズなどの、データセットに関する情報を表示します。 データセットに変更は加えられません。
# 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
パラメータ:
show_features: 特徴の詳細も表示するかどうか（デフォルト:false）。
Hubにプッシュ
--push_to_hub true フラグを任意のコマンドに追加すると、生成されたデータセットが 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 truelerobot-edit-datasetではまだカバーされていない、データセットに機能を追加するためのツールも用意されています。