FlowHMR 输出文件全解析:NPZ 动作数据到 FBX 导入 Mixamo/Blender 的完整指南
FlowHMR 输出文件全解析:NPZ 动作数据到 FBX 导入 Mixamo/Blender 的完整指南
FlowHMR 是一个从单目视频生成物理合理人体动作(physically plausible motion capture from monocular video)的生成式模型。跑完推理后,它会在 output/ 目录生成一套文件:核心的 .npz 动作数据(SMPL-H 参数)、可选的 .fbx 动画(可直接导入 Mixamo / Blender),以及一批用于缓存复算的中间文件。本文将带你完整读懂每个输出文件,并一步步把动作导入 DCC 软件。
输出目录结构一览:output 里到底有什么?
用 CLI 跑一次推理(参见 docs/inference.md):
python run_v2m_demo_generation.py assets/example/example.mp4
最终结果保存在 output/<视频名>/<检查点名>.npz(例如 output/example/flowhmr_latest.npz),如果安装了 FBX SDK 还会额外生成同名 .fbx。整个目录里其实包含两类文件:
| 文件 | 类型 | 说明 |
|---|---|---|
<视频名>_<模型名>.npz |
✅ 最终结果 | SMPL-H 动作参数(本文主角) |
<视频名>_<模型名>.fbx |
✅ 最终结果 | 带动画与蒙皮的 FBX,需安装 fbxsdkpy 才会生成 |
<视频名>_30fps.mp4 |
缓存 | 统一转码为 30 fps 的工作视频 |
<视频名>_bbox.npz |
缓存 | 人物检测框(bbox、start_end) |
<视频名>_vggt_camera.npz / _static_camera.npz |
缓存 | 相机内参与外参 |
<视频名>_sam3d_feat.pt |
缓存 | SAM 3D Body 特征 token(T, 3072) |
<视频名>_seed<k>_origin.* |
中间产物 | 后处理前的原始输出(启用 --postprocess 时保留) |
💡 缓存机制:同一个视频再次运行(比如换检查点、换随机种子)会直接复用检测、相机与 SAM 特征缓存,无需重新计算;加
--overwrite可强制重算。
这些缓存文件由推理引擎 flowhmr/pipeline/v2m_inference.py 的 process_video 逐阶段写入,文件名规则也定义在同一文件中。
NPZ 动作文件全字段解析:poses / betas / trans 各是什么?
.npz 就是 NumPy 打包的压缩包,用 np.load 即可打开。以仓库自带的示例动作为参照(data/rendering_data/examples/motions/flowhmr_demo.npz),各字段含义如下:
| 字段 | 形状 | 含义 |
|---|---|---|
poses |
(T, 156) 或 (T, 52, 3) | 52 个关节的 axis-angle 旋转,第 0 个是根节点(Pelvis)朝向 |
betas |
(1, 16) | 16 维体型参数(SMPL-H 形状系数) |
trans |
(T, 3) | 根节点在世界坐标系下的平移,单位米,Y 轴向上 |
mocap_framerate |
标量 | 帧率,固定 30 |
num_frames |
标量 | 总帧数 T |
gender |
字符串 | 固定为 neutral |
可选字段(开启 --postprocess 后处理时才会出现):
| 字段 | 含义 |
|---|---|
foot_contacts |
(T, 4) 双脚接触状态,供下游物理约束使用 |
pelvis_world / smooth_root_pos / local_joints_positions |
骨盆世界坐标、平滑根轨迹、局部关节位置 |
几个新手最容易踩的坑:
- 单位是米:FBX 导出时内部会乘以 100 转成厘米,这是行业惯例;
- 坐标系:SMPL 本身是 Y-up、左手系。导出 FBX 前代码会绕 Y 轴旋转 180°(见 flowhmr/pipeline/v2m_inference.py 中的
_rotate_smplh_params_y180),使其对齐 Mixamo/Blender 的 Z-up 右手系——所以你直接拿 FBX 导入即可,不需要再手动转轴; - 帧率 30 fps:输入视频在预处理阶段已被强制转码为 30 fps(
<视频名>_30fps.mp4),动作帧数与之一致。
用几行 Python 快速验证你的输出:
import numpy as np
data = np.load("output/example/flowhmr_latest.npz")
for k in data.files:
print(k, data[k].shape, data[k].dtype)
# poses (155, 156) / betas (1, 16) / trans (155, 3) / mocap_framerate 30 ...
生成 FBX 动画:从 npz 到 Mixamo 的最后一公里
FBX 导出需要额外依赖
.fbx 导出依赖 Autodesk FBX SDK 的 Python 绑定,安装命令见 docs/install.md:
pip install fbxsdkpy==2020.1.post2 --extra-index-url https://gitlab.inria.fr/api/v4/projects/18692/packages/pypi/simple
没有装也没关系——.npz 照常保存,只是跳过 FBX。
转换管线内部做了什么
转换入口在 flowhmr/core/export/smplh2fbx.py 的 SMPLH2FBX.convert_npz_to_fbx,它从零构建一个完整的 FBX 场景:
- 读体型:用
betas通过 blend shapes 计算带形状的 T-pose 顶点与骨骼静止位; - 建网格:构建 SMPL-H 皮肤网格(含 UV 与蒙皮权重),缩放 100 倍(米→厘米);
- 建骨架:按 SMPL-H 的 52 关节层级(定义在 flowhmr/core/export/fbx_utils.py 的
SMPLH_JOINT2NUM)生成 Skeleton 节点; - 打关键帧:把每帧的旋转矩阵与根节点平移逐帧写入 AnimStack,时间码设为 30 fps;
- 原子导出:先写临时文件再替换,避免导出中断留下损坏文件。
此外,脚本也可以单独作为命令行工具使用,把任意目录下的 .npz 批量转成 .fbx(见 smplh2fbx.py 文件末尾的 __main__ 段)。
导入 Mixamo / Blender 实操
- Mixamo:登录 mixamo.com → Character → Upload Character,选择 FlowHMR 生成的
.fbx。由于骨骼命名与 SMPL-H 标准一致且已是 Z-up,通常能直接识别为角色;若识别失败,选 "Import without Rig" 走 Import Motion 流程上传动画即可。 - Blender:
File → Import → FBX (.fbx)导入,在右侧 Import 面板把 Scale 设为 1.0(文件内部已是厘米),应用后选中模型 →Object → Animation → Baked Animation可烘焙为关键帧。播放即可看到重建的动作。 - Houdini / UE 同理:直接拖入 FBX,注意 UE 导入时勾选 "Import Animations"。
Web Demo 一键下载
如果不想手动找文件,用 docs/web_demo.md 的 Web 演示更方便:python app.py 启动后上传视频,页面右上角直接提供 Download motion (.npz) 按钮。任务目录 output/web_jobs/<job_id>/ 下会固定生成 tools/web/server.py 统一命名的文件:
| 文件 | 说明 |
|---|---|
motion.npz |
最终动作(固定命名,方便脚本处理) |
motion.fbx |
最终 FBX(安装了 FBX SDK 时存在) |
mesh/vertices.bin + faces.bin + meta.json |
逐帧网格顶点流(float16 / uint32),供 3D 播放器使用 |
常见问题速查(FAQ)
Q1:为什么我的目录里没有 .fbx?
没装 fbxsdkpy(见上文安装命令),或者你用的是旧版检查点。确认 docs/install.md 中 Optional: FBX export 一节完成后再重跑。
Q2:为什么有两份 npz(_origin 和正式版)?
启用 --postprocess 后,原始模型输出保留为 _origin(原始结果),后处理版(接触规划 + 解剖学 IK,基于 third_party/RGBMocapCorrection)作为最终结果。需要对比时两个都看;只想要干净数据就用正式版。
Q3:不同 seed 的 _seed<N> 后缀是什么?
FlowHMR 是生成式模型,非零 --seed 会在文件名追加 _seed<N>,方便多次采样对比;seed=0 是默认确定性结果。
Q4:想只重跑动作生成(不换模型参数),能省时间吗?
可以。检测框、相机、SAM 特征都缓存在 output/<视频名>/ 下,二次运行直接跳过 Step 1~3,只执行 Step 4 生成。
小结:从视频到 DCC 软件的一条龙
| 步骤 | 产物 | 位置 |
|---|---|---|
| 1. 推理 | <video>.npz / .fbx |
output/<video>/ |
| 2. 校验 | poses/betas/trans |
np.load 打开 |
| 3. 转 FBX | 自动或手动跑 smplh2fbx.py |
与 npz 同目录 |
| 4. 导入 | Mixamo / Blender / UE | 直接拖拽,Scale 1.0 |
完整流程参考:安装指南、推理指南、Web Demo 指南 与 参数说明。

