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 個 epoch）。範例：

   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 等先前研究的貢獻。