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 等先前研究的贡献。