Skip to content

README.md

Latest commit

 

History

History
140 lines (108 loc) · 5.83 KB

README.md

File metadata and controls

140 lines (108 loc) · 5.83 KB

ROS Bag to LeRobot Conversion

ROS bag 파일을 LeRobot 데이터셋 형식으로 변환하는 도구들입니다.

파일 구조

파일 역할
rosbag_to_lerobot.py 단일 bag → LeRobot 변환 핵심 모듈 (배치 스크립트가 호출)
batch_convert_rosbag_to_lerobot.py 여러 bag을 하나의 데이터셋으로 배치 변환 + 통계/modality.json 생성
validate_lerobot_dataset.py 변환된 데이터셋 무결성 검증 및 시각화
verify_rel_action_convention.py relative end-pose action의 시간 규약(prev→cur vs cur→next) 검증
sensory_sync_issues.py 압축 이미지를 재생하며 start/end 프레임을 지정해 bag을 트리밍하는 대화형 도구
ACTION_ABSOLUTE_VS_RELATIVE.md absolute/relative action·state 조합 규약에 대한 상세 분석 문서

구현 내용

rosbag_to_lerobot.py

단일 bag을 LeRobot 데이터셋으로 변환하는 핵심 로직입니다. 직접 CLI로도 실행 가능합니다.

  • bag 저장 포맷(mcap/sqlite3) 자동 감지 (detect_storage_id, open_reader_auto)
  • 토픽 메시지 로드 후 reference 토픽 기준 nearest-neighbor 동기화 (synchronize_messages)
  • joint state / end-pose 추출, robot config 파일 기반 joint 순서 필터링
  • absolute/relative pose 계산 (compute_relative_pose, quaternion_multiply 등)
  • hybrid(absolute state + relative action) 포맷 지원

batch_convert_rosbag_to_lerobot.py

번호로 정렬된 폴더들을 스캔해 하나의 LeRobot 데이터셋으로 묶습니다.

  • bag 폴더 탐색 (직접/중첩 converted_* 레이아웃 지원)
  • message_count가 0인 토픽을 가진 bag 사전 감지 및 --skip-zero-count 처리
  • GR00T 호환 modality.json 생성, 정규화용 통계(mean/std/min/max/q01/q99) 계산
  • MODALITY_CONFIGS로 알고리즘별 state/action 차원 정의

validate_lerobot_dataset.py

  • 프레임 개수, 텐서 shape/dtype, 값 범위 검증
  • --visualize로 데이터셋 구조 및 샘플 프레임 출력

verify_rel_action_convention.py

relative action이 inference 기대와 같은 시간 규약을 따르는지 진단합니다.

  • Convention A (prev→current) vs Convention B (current→next)를 비교해 position/quaternion 오차 출력
  • 자세한 배경은 ACTION_ABSOLUTE_VS_RELATIVE.md 참고

sensory_sync_issues.py

센서 동기화 문제가 있는 bag을 잘라내는 대화형 트리머입니다.

  • 단일 모드(--input/--output)와 배치 모드(--roots) 지원
  • 최대 3개 이미지 동시 표시, 프레임 단위 탐색, 모든 토픽 보존
  • 키 조작: Space(start/end 지정), p(일시정지), a/←·d/→(프레임 이동), r(리셋), q/ESC(스킵)

사용법

배치 변환 (권장)

cd /workspace/physical_ai_tools/learning_data_preprocessing

python conversion/batch_convert_rosbag_to_lerobot.py \
    --input-dir /workspace/rosbag2/251129_260108_all/output/ffw_sg2_rev1_dkim \
    --output-dir /workspace/lerobot_251129_260108_all \
    --repo-id dkim/ffw_sg2_rev1_offline_200 \
    --fps 30 \
    --algorithm gr00_672x376 \
    --robot-type new_embodiment \
    --task-name "remove the flower" \
    --validate \
    --reference-observation observation.images.cam_head

단일 파일 변환

python conversion/rosbag_to_lerobot.py \
    --bag-dir /workspace/dkim_result/0/converted_20260106_142514_9160 \
    --output-dir /workspace/lerobot_datasets \
    --repo-id dkim/ffw_sg2_rev1_ep0000 \
    --fps 10 \
    --robot-type ffw_sg2_rev1

데이터셋 검증

python conversion/validate_lerobot_dataset.py \
    --repo-id dkim/ffw_sg2_rev1_offline_ep0000 \
    --root /workspace/lerobot_datasets/dkim_ffw_sg2_rev1_offline_ep0000 \
    --episode-index 0 \
    --num-samples 10 \
    --visualize

Relative action 규약 검증

python conversion/verify_rel_action_convention.py \
    --dataset-path /workspace/lerobot_datasets/dkim_ffw_sg2_rev1_offline_ep0000 \
    --max-frames 100 \
    --episodes 0,1,2

Bag 트리밍 (센서 동기화 이슈)

# 단일 bag
python conversion/sensory_sync_issues.py \
    --input /path/to/bag --output /path/to/trimmed_bag --fps 30

# 배치 스캔
python conversion/sensory_sync_issues.py \
    --roots /path/root1 /path/root2 --output_root ./trimmed_output --fps 15

Topic 매핑

기본 topic 매핑:

  • observation.images.cam_head → /zed/zed_node/left/image_rect_color/compressed
  • observation.images.cam_wrist_left → /camera_left/camera_left/color/image_rect_raw/compressed
  • observation.images.cam_wrist_right → /camera_right/camera_right/color/image_rect_raw/compressed
  • observation.state → /end_pose_right, /end_pose_left (0이면 /joint_states 사용)
  • action → /joint_states

알고리즘별 차이점 (--algorithm)

MODALITY_CONFIGS에 정의된 포맷입니다:

  • gr00_672x376: joint state 기반 (state 22D / action 22D), robot config 파일로 joint 필터링
  • maskact: end-pose state + multi-joint action
  • endpose_grip_672x376_absolute: 절대 pose + gripper (state 18D / action 16D)
  • endpose_grip_672x376_relative: 상대 pose + gripper (state 18D / action 16D)
  • endpose_grip_672x376_abs_state_rel_action: 절대 state + 상대 action 혼합

absolute/relative 조합의 의미와 주의점은 ACTION_ABSOLUTE_VS_RELATIVE.md를 참고하세요.

주의사항

  1. message_count가 0인 topic은 자동으로 스킵됩니다
  2. 각 bag 파일은 하나의 episode로 처리됩니다
  3. 이미지 주기를 기준으로 다른 topic들이 동기화됩니다
  4. 변환 완료 후 비디오 인코딩이 완료될 때까지 대기합니다 (최대 5분)

다음 단계

변환이 완료되면 postprocessing/ 폴더의 도구를 사용하여 통계를 생성할 수 있습니다.