FlowHMR 输出文件全解析:NPZ 动作数据到 FBX 导入 Mixamo/Blender 的完整指南

原创2026-11-15 09:10:411,976 阅读

FlowHMR 输出文件全解析:NPZ 动作数据到 FBX 导入 Mixamo/Blender 的完整指南

FlowHMR 是一个从单目视频生成物理合理人体动作(physically plausible motion capture from monocular video)的生成式模型。跑完推理后,它会在 output/ 目录生成一套文件:核心的 .npz 动作数据(SMPL-H 参数)、可选的 .fbx 动画(可直接导入 Mixamo / Blender),以及一批用于缓存复算的中间文件。本文将带你完整读懂每个输出文件,并一步步把动作导入 DCC 软件。

FlowHMR Web Demo 输出下载界面,支持下载 NPZ 动作文件和 FBX 动画

输出目录结构一览: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 SAM 特征提取的批处理流程示意图

这些缓存文件由推理引擎 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 场景:

  1. 读体型:用 betas 通过 blend shapes 计算带形状的 T-pose 顶点与骨骼静止位;
  2. 建网格:构建 SMPL-H 皮肤网格(含 UV 与蒙皮权重),缩放 100 倍(米→厘米);
  3. 建骨架:按 SMPL-H 的 52 关节层级(定义在 flowhmr/core/export/fbx_utils.py 的 SMPLH_JOINT2NUM)生成 Skeleton 节点;
  4. 打关键帧:把每帧的旋转矩阵与根节点平移逐帧写入 AnimStack,时间码设为 30 fps;
  5. 原子导出:先写临时文件再替换,避免导出中断留下损坏文件。

此外,脚本也可以单独作为命令行工具使用,把任意目录下的 .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 指南 与 参数说明。

登录后查看全文
flowhmr