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. 論文結果の再現 – 単一のコマンドで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. 学習 – リリースされたチェックポイントから開始するか、ゼロから学習します（リリースされたモデルは2枚の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 (インタラクティブなWeb 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などの先行研究に感謝します。