humanoid-motion-tracking

사람의 모션 캡처를 휴머노이드로 옮기고, 그 동작을 따라가는 전신 제어 정책을 학습하는 파이프라인입니다. Unitree G1으로 시작했고 두 번째 로봇 IGRIS-C로 넓혔습니다.

English · Hugging Face · W&B · YouTube

범위는 시뮬레이션까지입니다. 하드웨어가 없어 실제 로봇 배포는 하지 않았고, sim-to-real 성능을 주장하지 않습니다. Isaac Lab에서 학습하고 MuJoCo로 옮겨 검증합니다.

군집 휴머노이드 시뮬레이션에서 NVIDIA의 GEAR-SONIC으로 G1을 제어해 봤는데, 쓰는 것과 만드는 것은 아는 것이 달랐습니다. 같은 계열(레퍼런스 모션 추종)의 전신 제어를 처음부터 끝까지 직접 만들어 보려고 시작했습니다.

• [2026-10-02] IGRIS-C 리타게팅에서 고친 두 곳: G1 설정을 그대로 쓰면 팔꿈치가 쭉 펴진 채 굳고, 다리를 발목까지 재면 걷는 내내 발이 바닥 아래 1.8cm에 박힙니다. 로봇을 바꿀 때 손봐야 하는 곳이 리타게팅 표입니다.
• [2026-10-02] IGRIS-C 정책: 같은 달리기 클립을 처음부터 학습한 것(완주 96%)과 G1 정책을 Any2Any 방식으로 옮긴 것(16%)을 비교했습니다. 옮긴 쪽이 초반엔 10배 빨리 배우지만 낮게 멈춥니다. 처음엔 자기 충돌 때문에 전혀 학습되지 않았습니다.
• [2026-10-01] 보상 ablation: 추종 보상 세 묶음 모두 필요합니다. 앵커 항을 빼면 표류(전역 오차 1.25m), 몸체 자세 항을 빼면 2초 만에 쓰러집니다. 전역 위치를 붙잡는 몫은 앵커 항보다 속도 항이 더 컸습니다.
• [2026-09-30] 두 번째 로봇 IGRIS-C 리타게팅. C++ 실시간 추론 루프가 20ms 제어 예산에 10배 가까운 여유로 듭니다(견고성).
• [2026-09-29] 모델 불일치 민감도: 지연 한 스텝(20ms)에 완주율 99.9% → 29.6%. 평가 코드가 랜덤화를 켠 채 돌던 버그를 고쳐 비교를 바로잡았습니다. 지표 이름을 정의한 논문의 것으로 바꿨습니다.
• [2026-09-27] 일반화 한계 측정: LAFAN1의 학습에 없던 63개 클립 중 완주 0개.
• [2026-09-24] 단일 동작 전문가 14개를 정책 하나로 증류. 여섯 지표 전부 같거나 낫습니다.
• [2026-09-14] 교사 정책을 MuJoCo로 옮겨 검증(sim-to-sim). LAFAN1 밖의 동작(kobe)도 학습.
• [2026-09-10] LAFAN1 교사 정책 17개 학습 완료.
• [2026-09-02] 첫 교사 정책. RTX 5080에서 30,000회에 8시간 38분.

• 개요
• 결과
• 데모
• 지원 로봇
• 체크포인트
• 설치
• 사용법
• 폴더 구조
• TODO
• 감사의 말
• 라이선스

단계별 설명과 평가 기준은 docs/pipeline.md에 있습니다.

전문가 14개를 하나로 합쳤고, 여섯 지표 전부 같거나 낫습니다.

100 롤아웃, 도메인 랜덤화 끔, 클립 전체 길이, 같은 평가 코드입니다. 오차는 완주한 롤아웃만 평균낸 값입니다. 지표 정의는 GMR 논문 (E_g-mpbpe, E_mpbpe, E_mpjpe)과 PBHC(E_mpbve, E_mpbae)를 따릅니다.

되는 것과 안 되는 것을 함께 쟀습니다.

리타게팅 (사람 → G1)	추종 정책 (Isaac Lab)
sim-to-sim (Isaac Lab | MuJoCo)	도메인 랜덤화
LAFAN1 밖의 동작 (ASAP kobe)	IGRIS-C: 처음부터 학습 | G1 정책에서 옮기기

전체 영상: 전체 클립 · 학습 경과 · 도메인 랜덤화 · 재생목록

IGRIS-C에서 G1 정책을 옮겨 쓰는 것(cross-embodiment transfer)과 처음부터 학습하는 것을 비교했습니다. 모델 파일에 라이선스가 없어 저장소에 복사하지 않고 원 저장소를 링크합니다. 자세한 것은 docs/igris.md.

Hugging Face에 있습니다.

학습 곡선은 W&B에 있습니다. 교사는 humanoid-motion-tracking 프로젝트의 stage4_teachers 그룹, 증류는 humanoid-motion-tracking-distill 프로젝트의 final 그룹, 보상 ablation은 reward_ablation_obstacles3, IGRIS-C는 igris_c_transfer 그룹입니다.

환경이 셋입니다.

학습은 BeyondMimic을 로컬에서 고쳐 씁니다. 원 저장소는 Isaac Sim 4.5 / Isaac Lab 2.1 기준이라 인터페이스 다섯 곳을 고쳤고, 고친 곳은 docs/pipeline.md에 적었습니다. 증류와 평가 코드를 포함한 그 포크는 아직 공개하지 않았습니다.

스크립트에 로컬 경로(/home/sehoon/...)가 박혀 있어 그대로 복제해 돌리기는 아직 어렵습니다(TODO).

1. 리타게팅 — LAFAN1 bvh를 G1 관절각으로 바꿉니다.

bash scripts/retarget_all.sh                      # data/lafan1/*.bvh -> outputs/retarget/*.pkl
python src/pkl_to_csv.py --src outputs/retarget --dst outputs/csv

2. 레퍼런스 모션 — csv를 물리 시뮬레이터에서 재생해 50 fps npz로 만듭니다.

bash scripts/npz_all.sh                           # BeyondMimic scripts/csv_to_npz.py

3. 교사 정책 학습 — 클립 하나에 정책 하나.

python scripts/rsl_rl/train.py --headless --task=Tracking-Flat-G1-v0 \
    --motion_file <시퀀스>.npz --run_name <시퀀스>                    # 4096 env, 30,000회

4. 증류 — 교사 14개를 학생 하나로.

python scripts/distill/train_student.py --headless --seqs configs/distill_seqs.txt \
    --student_hidden 2048 2048 1024 1024 512 --max_iteration 50000

5. 평가 — 100 롤아웃, 랜덤화 끔, 클립 전체 길이.

python scripts/distill/eval_student.py --headless --checkpoint <학생.pt> \
    --seqs configs/distill_seqs.txt --num_envs 100 --out eval.json

불일치 조건은 --action_delay 1, --torque_scale 0.7, --mass_scale 1.2 같은 인자를 하나씩 켭니다.

6. sim-to-sim — 학생 정책을 MuJoCo에서 돌립니다.

python src/sim2sim_student.py walk4_subject1 --onnx student/policy.onnx --video out.mp4

7. 실시간 루프 — C++ 추론 루프의 지연을 잽니다. cpp/README.md

3-5단계의 스크립트는 BeyondMimic 포크 쪽에 있습니다.

src/        리타게팅, 지표, 렌더, 표 생성, sim-to-sim (MuJoCo)
scripts/    배치 실행 스크립트
  igris/    두 번째 로봇: 모델 준비, IK 표, 관절 대응
cpp/        실시간 추론 루프(C++)와 파이썬 대조군
configs/    선별 목록, 학습 순서
docs/       단계별 상세 문서와 이 README의 그림
outputs/    생성 결과 (gitignored)
data ->     데이터 심볼릭 링크 (gitignored)

• LAFAN1 77개 리타게팅, 교사 정책 14개
• 교사 14개 → 통합 정책 하나 (증류)
• MuJoCo sim-to-sim
• 일반화·교란·모델 불일치 한계 측정
• C++ 실시간 추론 루프
• 두 번째 로봇 IGRIS-C 리타게팅
• 보상 항 ablation — 추종 보상 세 묶음을 하나씩 빼고 비교
• IGRIS-C 정책 — 처음부터 학습 vs G1 정책에서 옮기기
• 학습에 지연 넣기 — 도메인 랜덤화에 지연, 또는 명령 이력을 관측에
• 학습 모션 14 → 60개, 나머지를 held-out으로
• DAgger 롤아웃에 교란 넣기 (복구력)
• 리타게팅 선별 기준 다시 잡기 — 지면 관통, 발 미끄럼, 관절속도 위반
• 로컬 경로를 떼어 내 복제해 돌릴 수 있게
• 실제 로봇

• GMR (MIT) — 리타게팅. 두 번째 로봇의 IK 표도 G1 표에서 만들었습니다.
• BeyondMimic (MIT) — 교사 정책 학습 코드와 보상 설계.
• Isaac Lab, rsl_rl, MuJoCo.
• LAFAN1 — 모션 데이터. ASAP — kobe 모션.
• Unitree G1 모델은 BeyondMimic이 쓰는 unitree_description, IGRIS-C 모델은 robrosinc/igris_c_description_public(라이선스 표기 없음, 복사하지 않음).
• 평가와 비교의 기준: Retargeting Matters (GMR), PBHC, PolySim, Any2Any, GEAR-SONIC.

이 저장소의 코드는 MIT입니다. 데이터셋과 로봇 모델은 각 원 저장소의 조건을 따릅니다.