GVHMR-Transfer

中文说明 | English

把普通人物视频交给 GVHMR 做单人三维动作恢复，再将结果直接转换成 MikuMikuDance 可读取的 VMD 身体动作。也可以只转换已有的 hmr4d_results.pt。不需要 Blender。

本项目提供 Windows + WSL2 的一键入口、30 fps 视频规范化、断点续跑、镜像还原、根运动控制、动作平滑、MMD 骨骼映射和 VMD 写出后回读验证。

重要：GVHMR、模型权重、SMPL/SMPL-X 人体模型和输入视频不包含在本仓库中。请分别遵守它们的许可证和使用条款。本仓库的 MIT 许可证只覆盖 GVHMR-Transfer 自身代码。

功能概览

从视频自动完成：环境预检 → FFmpeg 规范化 → GVHMR 推理 → VMD 导出 → 质量检查
读取 GVHMR 的 smpl_params_global 或 smpl_params_incam
将 21 个 SMPL 身体关节转换为 19 条标准 MMD FK 骼轨道
内置 standard_mmd 与 legacy_mmd 两套模型配置
支持保留或还原镜中动作的左右方向
支持 global、inplace、xz、none 四种根运动
四档旋转平滑、30 fps 时间轴重采样和四元数连续性处理
默认关闭左右足与脚尖 IK，避免与 FK 腿骨冲突
基于输入指纹缓存耗时的推理阶段；转换参数改变时只重做 VMD
为长视频提供流式 GVHMR 预处理补丁，减少一次性占用的内存

运行环境

经过验证的组合：

Windows 10/11
WSL2，默认发行版名为 Ubuntu-22.04
NVIDIA GPU，以及可被 WSL 中 PyTorch 识别的 CUDA 驱动
Python 3.10
FFmpeg / ffprobe（安装在 WSL 内）
PowerShell 5.1 或更高版本
GVHMR 固定版本 6ec3ca39336c50492c0fae65fba2fb831fc7d866

推荐目录布局：

D:\Projects\
├─ GVHMR\
└─ GVHMR-Transfer\

按此布局放置时，一键脚本会自动找到同级的 GVHMR。其他位置也可以通过 -GVHMRRoot 指定。

完整安装：配置 GVHMR 与本插件

1. 安装 WSL2

在管理员 PowerShell 中执行：

wsl --install -d Ubuntu-22.04
wsl --update

重启 Windows，并完成 Ubuntu 的首次启动。如果已经安装 WSL，可用下列命令确认发行版名称：

wsl -l -v

如果名称不是 Ubuntu-22.04，运行插件时传入 -WslDistro "实际名称"。

2. 克隆两个仓库并锁定 GVHMR 版本

在 WSL 终端中执行：

cd /mnt/d/Projects
git clone https://github.com/zju3dv/GVHMR.git
git clone https://github.com/LeslieH666/GVHMR-Transfer.git

cd GVHMR
git checkout 6ec3ca39336c50492c0fae65fba2fb831fc7d866

锁定版本很重要：随本项目发布的补丁以该提交为基线制作。以后若要升级 GVHMR，请先确认补丁仍可干净应用并重新运行测试。

3. 创建 GVHMR Python 环境

一键脚本默认使用 <GVHMR>/.venv/bin/python：

cd /mnt/d/Projects/GVHMR
sudo apt update
sudo apt install -y ffmpeg python3-venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e .

GVHMR 的依赖安装以其官方 INSTALL.md 为准。如果使用 Conda，不必再建 .venv；先执行 which python，然后把返回的 WSL 路径通过 -WslPythonPath 传给本项目。

确认 PyTorch 能看到 GPU：

cd /mnt/d/Projects/GVHMR
.venv/bin/python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name() if torch.cuda.is_available() else 'CUDA unavailable')"
ffmpeg -version
ffprobe -version

torch.cuda.is_available() 必须为 True。

4. 下载 GVHMR 权重与人体模型

按照 GVHMR 官方安装说明下载权重。SMPL 和 SMPL-X 需要在各自官网注册并接受许可条款；请勿把这些文件提交到本仓库。

运行一键流程前，以下文件必须存在：

GVHMR/
├─ inputs/checkpoints/
│  ├─ gvhmr/gvhmr_siga24_release.ckpt
│  ├─ yolo/yolov8x.pt
│  ├─ vitpose/vitpose-h-multi-coco.pth
│  ├─ hmr2/epoch=10-step=25000.ckpt
│  └─ body_models/
│     ├─ smpl/SMPL_NEUTRAL.pkl
│     └─ smplx/SMPLX_NEUTRAL.npz
└─ hmr4d/utils/body_model/
   ├─ smplx2smpl_sparse.pt
   └─ smpl_neutral_J_regressor.pt

插件会在推理前逐项检查，缺少任何文件时会直接列出完整路径。

5. 应用 GVHMR 集成补丁

本项目调用了 --no_render，并依赖分批读取视频的长视频兼容改动，所以不能直接搭配未打补丁的 GVHMR。补丁还包含 PyTorch 2.6+ 的可信 ViTPose 检查点加载兼容处理。

在 WSL 中执行：

cd /mnt/d/Projects/GVHMR
git apply --check ../GVHMR-Transfer/patches/gvhmr-integration.patch
git apply ../GVHMR-Transfer/patches/gvhmr-integration.patch

检查补丁状态：

git status --short
.venv/bin/python tools/demo/demo.py --help | grep no_render

如果第一条 git apply --check 失败，先确认 GVHMR 的 HEAD 正是上面锁定的提交，并确认工作区没有与补丁重叠的改动。不要在检查失败后强制应用。

补丁具体做了四件事：

增加 --no_render，VMD 流程无需渲染网格预览。
ViTPose 与 HMR2 按批读取视频，不把整段视频一次性装入内存。
每个预处理模型完成后主动释放 CPU/CUDA 内存。
兼容 PyTorch 2.6+ 对官方 ViTPose 完整检查点的加载方式。

流水线默认设置 GVHMR_PREPROCESS_BATCH_SIZE=4。

6. 可选：限制 WSL 内存

仓库中的 wslconfig-gvhmr.ini 是一个参考配置：

[wsl2]
memory=16GB
swap=8GB

[experimental]
autoMemoryReclaim=gradual

把这些设置合并到 Windows 的 %UserProfile%\.wslconfig 后执行：

wsl --shutdown

这会暂时停止所有 WSL 发行版和 Docker Desktop 容器。请根据自己的物理内存调整，不要盲目覆盖已有的 .wslconfig。

一键把视频转换成 VMD

镜子视频与老版 MMD 模型

双击 start_video_to_vmd.cmd，启动器会先要求选择相机模式：固定机位选 static，手持、跟拍或明显转动的相机选 moving。随后选择视频即可开始。也可以把视频拖到 start_video_to_vmd.cmd 或 mirror_video_to_vmd.cmd 上，相机模式仍会询问。

通用双击入口使用：

用户选择的相机模式 + 还原镜像 + 全局根运动 + legacy_mmd

因此 VMD 默认保留 GVHMR 识别出的 X/Y/Z 中心位移。确实需要原地动作时，改用 start_video_to_vmd_inplace.cmd；该入口同样会询问 static/moving，但会明确删除 X/Z 地面移动。

这些入口适合镜子前拍摄的舞蹈视频，以及没有“上半身2”骨骼的老 PMD 模型。

普通视频与现代 PMX 模型

在 PowerShell 中执行：

cd D:\Projects\GVHMR-Transfer

.\video_to_vmd.ps1 `
  -Video "D:\Videos\dance.mp4" `
  -Camera static `
  -Mirror keep `
  -Profile standard_mmd `
  -RootMotion global

如果两个项目不在同一父目录：

.\video_to_vmd.ps1 `
  -Video "E:\Videos\dance.mp4" `
  -GVHMRRoot "E:\AI\GVHMR" `
  -WslDistro "Ubuntu-22.04" `
  -WslPythonPath "/mnt/e/AI/GVHMR/.venv/bin/python"

-GVHMRRoot 使用 Windows 路径；-WslPythonPath 使用 WSL/Linux 路径。默认使用该发行版的默认用户；仅在环境确实安装在其他用户下时传入 -WslUser。

常用参数

参数	说明
`-Camera static`	固定机位、三脚架或镜子视频；PowerShell 默认，一键入口会询问
`-Camera moving`	手持、跟拍或明显移动的相机
`-Mirror keep`	保留画面中看到的左右方向
`-Mirror undo`	交换左右关节，并镜像根位置和旋转
`-RootMotion global`	保留 X/Y/Z 位移
`-RootMotion inplace`	去掉地面移动，保留跳跃与蹲起高度
`-RootMotion xz`	只保留地面平移
`-RootMotion none`	不写中心位移
`-Profile standard_mmd`	现代 PMX / 标准骨骼模型
`-Profile legacy_mmd`	没有“上半身2”的老 PMD 模型
`-Smooth off/light/medium/strong`	关闭或选择 3/5/9 帧平滑窗口
`-Scale 10`	根位移比例；不改变肢体骨骼长度
`-Crop "x,y,w,h"`	裁剪画面，隔离主要人物
`-StartSeconds 10 -DurationSeconds 20`	只处理指定片段
`-FocalLengthMm 24`	全画幅等效焦距
`-Output "D:\Motions\dance.vmd"`	指定最终文件
`-NoRecenter`	不把第一帧中心归零
`-KeepFootIK`	不自动关闭足/脚尖 IK
`-Fresh`	新建任务，不复用同设置缓存
`-GVHMRRoot`	GVHMR 的 Windows 路径
`-WslDistro`	WSL 发行版名
`-WslUser`	可选的 WSL 用户名
`-WslPythonPath`	可选的 GVHMR Python 解释器 WSL 路径

GVHMR 只跟踪一个主要人物。画面同时出现真人和镜像且跟踪错误时，请用 -Crop 隔离目标。程序不会自动判断视频是否拍摄自镜子。

输出、缓存与断点续跑

典型目录：

runs/<视频名_任务指纹>/
├─ input_30fps.mp4
├─ pipeline.log
├─ pipeline.report.json
├─ gvhmr/<视频名>/
│  └─ hmr4d_results.pt
└─ final/
   ├─ <视频名>.vmd
   └─ <视频名>.report.json

只有在输入不是恒定 30 fps、使用裁剪或截取片段时才会生成 input_30fps.mp4。相同视频和相同推理设置会复用 GVHMR 结果；修改镜像、根运动、平滑或目标配置时只重做 VMD。失败后修复环境并重新运行同一命令，流水线会从可复用阶段继续。

pipeline.report.json 记录各阶段状态、命令、环境、输入指纹和产物路径。<视频名>.report.json 还记录 root_motion_validation、转换前后位移统计及 VMD 中心骨回读一致性。global/xz 模式下若源轨迹明显存在但中心位移丢失，转换会直接失败。报告通过仍不代表已经针对某个 PMX 模型完成视觉验收。

所有 runs/、outputs/、视频、权重、日志和生成 VMD 都被 .gitignore 排除。

只转换已有的 GVHMR 结果

cd D:\Projects\GVHMR-Transfer

.\export_vmd.ps1 `
  -Input "D:\Projects\GVHMR\outputs\demo\dance\hmr4d_results.pt" `
  -Output "D:\Motions\dance.vmd" `
  -Mirror keep `
  -RootMotion global `
  -Profile standard_mmd

如果源视频不是 30 fps，用 -Fps 25 或 -Fps 60 告诉转换器源时间轴。程序会将位移线性插值、旋转进行四元数球面插值，再输出 30 fps VMD。

Python CLI

在含 NumPy 和 PyTorch 的环境中：

cd /mnt/d/Projects/GVHMR-Transfer
PYTHONPATH=src /mnt/d/Projects/GVHMR/.venv/bin/python -m gvhmr_transfer \
  /path/to/hmr4d_results.pt \
  /path/to/output.vmd \
  --space global \
  --mirror keep \
  --root-motion global \
  --smooth medium \
  --scale 10

也可安装命令行入口：

python -m pip install -e .
gvhmr-transfer /path/to/hmr4d_results.pt /path/to/output.vmd

本项目没有把 PyTorch 放入默认依赖，避免意外下载数 GB。需要独立安装时可使用 gvhmr-transfer[pt]，通常更建议复用 GVHMR 的 Python 环境。

骨骼映射与已知边界

GVHMR / SMPL	MMD
根朝向与根位移	センター
spine1 + 0.5 × spine2	上半身
0.5 × spine2 + spine3	上半身2
neck / head	首 / 頭
collar	左肩 / 右肩
shoulder	左腕 / 右腕
elbow	左ひじ / 右ひじ
wrist	左手首 / 右手首
hip	左足 / 右足
knee	左ひざ / 右ひざ
ankle	左足首 / 右足首

配置文件位于 src/gvhmr_transfer/profiles/。可以复制 JSON，修改骨骼名或脊柱权重，并通过 Python CLI 的 --profile 传入。

当前版本不读取目标 PMX 的静止骨架，因此模型肩宽、身高、局部轴或骨骼结构不同时可能需要调整。GVHMR 的结果不包含：

手指动作
表情、口型和眼睛
头发与服装物理
模型感知的高质量足部 IK 与足底锁定

故障排查

提示 unrecognized arguments: --no_render：GVHMR 集成补丁没有应用。
提示缺少模型文件：按错误列出的路径补齐权重，文件名大小写必须一致。
CUDA is not available：先在同一个 WSL 发行版和同一个 Python 中验证 torch.cuda.is_available()。
退出码 137 或 -9：通常是 WSL 内存/交换空间不足；关闭其他 WSL/Docker 工作负载并检查 .wslconfig。
找不到 .venv/bin/python：传入正确的 -WslPythonPath。
找不到发行版：用 wsl -l -v 查看名称，再传入 -WslDistro。
左右相反：切换 -Mirror keep 与 -Mirror undo；此操作会复用 GVHMR 推理。
追踪到错误人物：使用 -Crop；裁剪会触发新的 GVHMR 推理。
老模型上半身动作缺失：改用 -Profile legacy_mmd。

更完整的人工验收流程见 MANUAL_TEST.md。

开发与测试

cd /mnt/d/Projects/GVHMR-Transfer
PYTHONPATH=src /mnt/d/Projects/GVHMR/.venv/bin/python -m unittest discover -s tests -v

在已安装项目的环境中也可以执行：

python -m pytest

许可证与致谢

GVHMR-Transfer 使用 MIT License。GVHMR 及其模型、SMPL、SMPL-X、YOLO、ViTPose、HMR2 和 MikuMikuDance 相关资产均属于各自作者，其许可证与使用条款独立适用。

感谢 GVHMR 作者公开高质量的世界坐标人体动作恢复研究与实现。本项目不是 GVHMR 官方项目。

Navigation Menu

Repository files navigation

GVHMR-Transfer

功能概览

运行环境

完整安装：配置 GVHMR 与本插件

1. 安装 WSL2

2. 克隆两个仓库并锁定 GVHMR 版本

3. 创建 GVHMR Python 环境

4. 下载 GVHMR 权重与人体模型

5. 应用 GVHMR 集成补丁

6. 可选：限制 WSL 内存

一键把视频转换成 VMD

镜子视频与老版 MMD 模型

普通视频与现代 PMX 模型

常用参数

输出、缓存与断点续跑

只转换已有的 GVHMR 结果

Python CLI

骨骼映射与已知边界

故障排查

开发与测试

许可证与致谢

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
patches		patches
src/gvhmr_transfer		src/gvhmr_transfer
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
MANUAL_TEST.md		MANUAL_TEST.md
README.md		README.md
README_EN.md		README_EN.md
export_vmd.ps1		export_vmd.ps1
mirror_video_to_vmd.cmd		mirror_video_to_vmd.cmd
pyproject.toml		pyproject.toml
start_video_to_vmd.cmd		start_video_to_vmd.cmd
start_video_to_vmd_inplace.cmd		start_video_to_vmd_inplace.cmd
video_to_vmd.ps1		video_to_vmd.ps1
wslconfig-gvhmr.ini		wslconfig-gvhmr.ini

Latest commit

History

Folders and files

Repository files navigation

GVHMR-Transfer

功能概览

运行环境

完整安装：配置 GVHMR 与本插件

1. 安装 WSL2

2. 克隆两个仓库并锁定 GVHMR 版本

3. 创建 GVHMR Python 环境

4. 下载 GVHMR 权重与人体模型

5. 应用 GVHMR 集成补丁

6. 可选：限制 WSL 内存

一键把视频转换成 VMD

镜子视频与老版 MMD 模型

普通视频与现代 PMX 模型

常用参数

输出、缓存与断点续跑

只转换已有的 GVHMR 结果

Python CLI

骨骼映射与已知边界

故障排查

开发与测试

许可证与致谢

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages