LeRobot documentation

Dataset Tools 사용

LeRobot

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Dataset Tools 사용

이 가이드에서는 LeRobot 데이터셋을 온라인 또는 로컬에서 탐색하는 방법을 보여주고, 기존 데이터셋을 수정 및 편집하기 위해 LeRobot이 제공하는 유틸리티를 다룹니다.

브라우저에서 데이터셋 탐색

LeRobot 데이터셋의 내용을 가장 빠르게 확인할 수 있는 방법은 LeRobot Dataset Visualizer입니다. 이는 설치 과정 없이 Hub의 모든 LeRobot 데이터셋을 재생하는 Hugging Face Space입니다. lerobot으로 녹화한 데이터셋은 제외 옵션을 선택하지 않는 한 Hub에 업로드되므로, 본인의 녹화 데이터도 해당 Space에서 열 수 있습니다.

The LeRobot Dataset Visualizer showing episode 0 of lerobot/svla_so101_pickplace: the episode list, two synchronized camera recordings, the task, and joint charts

실제 데이터셋에서 사용해 보려면, 레고 블록을 상자에 놓는 SO-101 암의 lerobot/svla_so101_pickplace 에피소드 0을 열고 아래를 따라가 보세요:

데이터셋을 선택합니다. 시각화기 홈 페이지에서 lerobot/svla_so101_pickplace와 같은 저장소 ID를 입력하거나 예제 중 하나를 선택합니다. 개인 데이터셋을 열려면 로그인합니다.
에피소드를 선택합니다. 사이드바에는 데이터셋의 총 프레임 수, 에피소드 수, FPS 아래 모든 에피소드가 나열됩니다. 클릭하여 열거나 ↑ / ↓ 키를 눌러 순서대로 이동합니다.
녹화 영상을 시청합니다. 데이터셋의 모든 카메라가 동기화되어 재생됩니다. 하나의 영상을 확대하거나, 필요하지 않은 영상을 숨길 수 있습니다. 에피소드의 작업, 즉 언어 지시문은 비디오 아래에 표시됩니다.
데이터를 함께 읽어 보세요. 비디오 아래에는 에피소드 전체에 걸쳐 로봇의 상태와 동작이 관절별로 한 줄씩 차트로 표시됩니다. 재생을 따라가는 커서가 있으며, 범례에는 현재 프레임(또는 마우스를 올려놓은 경우 포인터 아래)의 각 값이 표시됩니다. 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> 링크를 통해 특정 에피소드로 바로 이동할 수 있습니다. 예를 들어 팀과 실패 사례를 공유하는 데 사용할 수 있습니다.

로컬에서 데이터셋 시각화

…

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는 데이터셋을 조작하기 위한 여러 유틸리티를 제공합니다:

에피소드 삭제 - 데이터셋에서 특정 에피소드를 제거합니다
데이터셋 분할 - 데이터셋을 여러 개의 더 작은 데이터셋으로 나눕니다
데이터셋 병합 - 여러 데이터셋을 하나로 결합합니다. 데이터셋은 동일한 특징을 가져야 하며, 에피소드는 repo_ids에 지정된 순서대로 연결됩니다.
기능 추가 - 데이터셋에 새 기능 추가
특성 제거 - 데이터셋에서 특성 제거
작업 수정 - 에피소드에 연결된 자연어 작업 설명을 변경합니다
비디오로 변환 - 이미지 기반 데이터셋을 효율적인 저장을 위해 비디오 형식으로 변환합니다 (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 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는 데이터셋을 in-place로 수정합니다(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: 기존 작업 문자열에서 해당 대체값으로의 매핑입니다. 현재 작업이 키와 일치하는 에피소드에 적용됩니다. 모든 키는 데이터셋에 존재하는 작업이어야 합니다.

모드는 단일 실행에서 결합할 수 있습니다. 에피소드마다 다음 우선순위로 작업이 해결됩니다:

episode_tasks > task_replacements > new_task > 원본 작업

new_task, episode_tasks, task_replacements 중 적어도 하나는 지정해야 합니다. 태스크가 없는 에피소드로 종료되면 오류가 발생합니다.

비디오로 변환

이미지 기반 데이터셋을 비디오 형식으로 변환하여, 이미지를 비디오로 저장하는 새로운 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>을 통해 접근할 수 있습니다. 자세한 내용은 비디오 인코딩 매개변수를 참조하세요.
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: 모든 깊이 비디오에 적용되는 인코더 설정.

스트림 유형 하나만 다시 인코딩하고 다른 스트림은 그대로 유지하려면 Python API를 사용하고 다른 인코더에 None을 전달하세요. 예를 들어 reencode_dataset(dataset, rgb_encoder=..., depth_encoder=None).

num_workers: 처리를 위한 병렬 워커 수.

깊이(depth) 비디오를 재인코딩할 때, 기존 깊이 양자화 매개변수(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 true

lerobot-edit-dataset에서 아직 다루지 않는 데이터셋에 기능을 추가하는 도구도 있습니다.

Update on GitHub

←대형 데이터셋 이식 언어 열 및 레시피→