MHR 开发实践指南：如何用 pytest 运行测试、调试模型输出并参与开源贡献-开发者社区

【免费下载链接】MHR

Momentum Human Rig is an anatomically-inspired parametric full-body digital human model developed at Meta. It includes: A parametric body skeletal model; A realistic 3D mesh skinned to the skeleton with levels of detail;A body blendshape and pose corrective model; A facial blendshape model.Its design is friendly for both CG and CV communities.

项目地址：https://gitcode.com/gh_mirrors/mhr/MHR

点击查看免费下载

MHR（Momentum Human Rig）是 Meta 开发的参数化全身 3D 数字人模型，支持身份、姿态与面部表情三类参数化。本文面向新手，手把手讲解 MHR 开发实践：如何用 pytest 运行测试套件、如何调试模型输出，以及参与开源贡献的完整流程。

1. 先认识 MHR 项目结构

在跑测试之前，先花两分钟了解代码布局，遇到问题时能更快定位来源：

mhr/mhr.py：MHR 模型核心实现，包含MHR类与LOD枚举
mhr/io.py：模型资源（assets）加载工具
demo.py：官方演示脚本，生成测试网格并与 TorchScript 模型对比
tests/：pytest 单元测试目录
pyproject.toml：项目配置，测试任务test = pytest tests/ -v就定义在这里
CONTRIBUTING.md：开源贡献指南
web-viewer/：本地交互式 Web 查看器，自带一套更完整的后端测试

💡 MHR 依赖 Python ≥ 3.11、PyTorch 与 pymomentum。官方推荐使用 Pixi 管理环境，因为它能自动解析pymomentum等依赖，避免平台兼容问题。

2. 一键搭建可测试的开发环境

首次贡献前，先克隆仓库并初始化环境：

git clone https://gitcode.com/gh_mirrors/mhr/MHR cd MHR pixi install # 安装依赖（含 pytest>=8.0） pixi run download-assets # 下载模型资源 pixi shell # 进入隔离的 Python 环境

pyproject.toml中将 pytest 声明为可选依赖（[project.optional-dependencies] test = ["pytest>=8.0"]），Pixi 环境会自动装好，无需手动pip install pytest。

3. 用 pytest 运行测试套件：最快上手步骤

MHR 的测试套件由三个文件组成，覆盖了从"能 import"到"梯度可反传"的完整链路：

测试文件	测试内容
tests/test_basic.py	包导入与版本号检查
tests/test_mhr.py	模型前向、姿态校正开关、输入梯度（`requires_grad`）
tests/test_face_expression.py	72 个面部表情参数名称与索引映射

运行全部测试（-v参数会逐条打印测试名，新手强烈推荐）：

pixi run pytest tests/ -v

只跑某一个测试文件，快速缩小排查范围：

pixi run pytest tests/test_mhr.py

精准定位到单个用例，用"文件::类::方法"或"文件::函数"格式：

# 只跑梯度测试 pixi run pytest tests/test_mhr.py::TestMHRModel::test_model_supports_input_gradients # 只跑面部表情名称校验 pixi run pytest tests/test_face_expression.py

✅ 全部通过时，终端最后一行会显示类似7 passed in 3.2s的汇总。

常见问题速查

报错现象	原因与解决
`ModuleNotFoundError: No module named 'pymomentum'`	未进入 Pixi 环境，先执行`pixi shell`
`assets/ 目录不存在`	先执行`pixi run download-assets`
`requires-python >= 3.11`报错	用`pixi feature`或确认环境是 Python 3.12/3.13（项目默认 py312）
CUDA 相关警告	test_mhr.py 中会自动探测`torch.cuda.is_available()`，无 GPU 时回落到 CPU，属正常现象

4. 调试模型输出：三种实用技巧

技巧一：对比 TorchScript 基准输出

demo.py 是官方自带的"调试利器"——它先跑 Python 版模型生成网格，再与 TorchScript 模型逐顶点比对，打印平均与最大偏差（单位：厘米）：

pixi run demo

看到Averge per-vertex offsets ... cm.输出极小值，说明模型前向计算正确。若改动代码后偏差明显变大，即可确认是前向逻辑出了问题。

技巧二：用 web-viewer 做可视化调试

数值看不出问题时，用肉眼"看"模型。仓库内置 web-viewer/，在浏览器中实时调节 204 个姿态、45 个身份、72 个表情参数，并显示顶点数、面数与推理耗时：

cd web-viewer npm install python -m pip install -r requirements.txt python server.py

然后打开127.0.0.1:8891即可交互式检查形变是否符合预期。

web-viewer 自带一套覆盖元数据、LOD 切换、形变与 OBJ/GLB/USD 导出的测试，位于 web-viewer/tests/test_server.py：

cd web-viewer python -m pytest tests -q

技巧三：用 --pdb 交互式断点

测试失败时，加上--pdb可以让 pytest 在断言失败处自动进入调试器，直接检查张量形状与数值：

pixi run pytest tests/test_mhr.py -v --pdb

进入 pdb 后常用命令：n（下一步）、p tensor.shape（打印变量）、c（继续运行）、q（退出）。

5. 参与开源贡献：从 Fork 到合并

CONTRIBUTING.md 给出的贡献流程非常清晰，核心是这六步：

Fork 仓库，并从main分支创建自己的特性分支
为新代码补测试——这是 MHR 社区最看重的一点，tests/ 下的新文件会被纳入 CI
API 有变更时同步更新文档（README 或模块 docstring）
确保测试套件全部通过：pixi run pytest tests/ -v
保证代码通过 lint 检查
签署 CLA（贡献者许可协议），只需一次即可用于所有相关开源项目

新手友好型 Issue 推荐

为 tools/ 下的工具补充示例或文档（如 tools/mhr_LOD_conversion/example.py 对应的说明）
完善 docs/face-expressions.md 中 72 个表情参数的中文注释
给 scripts/test_wheel.py 这类发布验证脚本添加更友好的错误提示

📌 贡献前请先阅读 CODE_OF_CONDUCT.md，Issue 描述务必包含可复现步骤，方便维护者快速定位问题。

6. 发布前验证：wheel 测试流程

正式打包发布前，项目还提供了一条完整的验证链（同样定义在 pyproject.toml 的 Pixi 任务中）：

pixi run wheel-build # 用 build 构建源码包与 wheel pixi run wheel-test # 在 uv 创建的全新虚拟环境中安装并导入验证

scripts/test_wheel.py 会找到dist/下最新的 wheel，在干净环境中执行import mhr并打印版本号，确保分发包不依赖开发环境的隐式状态。

7. 常见问题 FAQ

Q1：必须用 Pixi 吗？能直接用 pip 装开发版吗？可以，pip install mhr+pip install pymomentum-cpu是官方支持的实验性路线，但部分平台依赖解析不稳定；贡献开发时 Pixi 环境最可靠。

Q2：pytest 和 unittest 在 MHR 里混用会冲突吗？不会。tests/test_mhr.py 使用unittest.TestCase风格，pytest 天然兼容并收集这类用例，无需改造。

Q3：没有 GPU 能跑全部测试吗？可以。测试代码会自动检测 CUDA 可用性，无 GPU 时在 CPU 上运行全部用例。

总结

MHR 的开发闭环可以概括为：Pixi 建环境 →pixi run pytest tests/ -v跑测试 → 用 demo.py 与 web-viewer 调试模型输出 → 补测试、过 lint、签 CLA 后提交 PR。掌握这条链路，你就具备了参与 Momentum Human Rig 开源贡献的完整能力。