zju3dv/GVHMR

GVHMR – 세계 좌표계에 접지된 인체 동작 복원

개요 – GVHMR은 단일 비디오에서 3D 인체 동작을 재구성하고, 그 동작을 실제 세계(중력 정렬 좌표)에 고정하는 연구 코드베이스입니다. 시각적 주행 거리 측정(DPVO 또는 경량 SimpleVO)을 기반으로 카메라 움직임을 추정하고, 2D 포즈 감지를 전역적으로 일관된 3D 궤적으로 끌어올립니다.

주요 구성 요소

• 중력 뷰 좌표 (Gravity-View Coordinates) – 복원된 동작을 물리적 중력 방향에 맞추는 새로운 표현 방식으로, 애니메이션, AR/VR, 로봇 공학 등 후속 작업에 직접 활용 가능합니다.
• 시각적 주행 거리 측정 통합 – 카메라 이동 시 카메라 포즈 추정을 위해 선택적으로 DPVO (dense-pixel VO) 또는 최신 SimpleVO를 사용할 수 있습니다.
• 학습 및 평가 스크립트 – 3DPW, RICH, EMDB 데이터셋을 위한 즉시 실행 가능한 파이프라인으로, SIGGRAPH Asia 2024 논문에서 보고된 결과와 일치합니다.
• 데모 유틸리티 – 간단한 명령줄 도구 (tools/demo/demo.py, tools/demo/demo_folder.py) 및 임의의 비디오에서 빠르게 추론을 수행할 수 있는 Colab/HuggingFace 데모를 제공합니다.

시작하기

1. 설치 – docs/INSTALL.md의 단계별 가이드를 따르십시오(Python 3.9+, PyTorch, CUDA 및 몇 가지 비전 라이브러리 필요). 저장소에는 requirements.txt 스타일의 목록이 포함되어 있습니다.
2. 데모 실행 –

   python tools/demo/demo.py --video=docs/example_video/tennis.mp4 -s   # -s는 카메라가 정지 상태일 때 VO를 건너뜁니다
   

   demo_folder.py를 사용하여 비디오 디렉토리를 일괄 처리합니다.
3. 논문 결과 재현 – 단일 명령어로 세 가지 벤치마크 데이터셋 모두를 평가합니다:

   python tools/train.py global/task=gvhmr/test_3dpw_emdb_rich \
       exp=gvhmr/mixed/mixed \
       ckpt_path=inputs/checkpoints/gvhmr/gvhmr_siga24_release.ckpt
   

4. 학습 – 릴리스된 체크포인트에서 시작하거나 처음부터 학습합니다(릴리스된 모델은 두 개의 RTX 4090 GPU에서 420 에포크 동안 학습되었습니다). 예시:

   python tools/train.py exp=gvhmr/mixed/mixed
   

   참고: 학습에는 테스트 스크립트에서 사용되는 후처리가 포함되지 않으므로 원시 지표는 약간 다를 수 있습니다.

최근 업데이트

• 2025-03-08 – 경량 SimpleVO(DPVO 의존성 없음)가 추가되었으며, 풀프레임 카메라의 초점 거리를 밀리미터 단위로 설정하는 f_mm 플래그가 추가되었습니다.

데모 확인처

• Colab 데모: https://colab.research.google.com/drive/1N9WSchizHv2bfQqkE9Wuiegw_OT7mtGj
• HuggingFace Space: https://huggingface.co/spaces/LittleFrog/GVHMR (대화형 웹 UI).

인용

@inproceedings{shen2024gvhmr,
  title={World-Grounded Human Motion Recovery via Gravity-View Coordinates},
  author={Shen, Zehong and Pi, Huaijin and Xia, Yan and Cen, Zhi and Peng, Sida and Hu, Zechen and Bao, Hujun and Hu, Ruizhen and Zhou, Xiaowei},
  booktitle={SIGGRAPH Asia Conference Proceedings},
  year={2024}
}

개발 팀 – 이 프로젝트는 ZJU-3DV 그룹(절강대학교) 및 협력자들에 의해 진행되었으며, WHAM, 4D-Humans, ViTPose-Pytorch와 같은 이전 연구들의 기여에 감사드립니다.