UniMate 推理输出全解析：motions 与 animations 目录的 npy/mp4 文件快速上手指南
【免费下载链接】UniMate[SIGGRAPH Asia 2026] UniMate: One Unified Model to Animate Diverse Skeletons项目地址: https://gitcode.com/GitHub_Trending/un/UniMate
跑完 UniMate 的文本生成动画推理后，输出目录里会同时出现motions文件夹中的.npy文件和animations文件夹中的.mp4视频，新手常常分不清它们各是什么、能不能直接给 3D 角色用。本文带你 10 分钟拆解 UniMate 推理输出的完整目录结构：逐文件讲清 npy 运动特征的形状、命名规则与两种 mp4 预览的来源，并说明manifest.json如何成为把结果一键变成 GLB/FBX 角色动画的"账本"。
UniMate 是 SIGGRAPH Asia 2026 的"一个统一模型驱动任意骨骼"文本生成动画模型。给它一个带骨骼的 3D 资产和一句提示词（如 "An object flaps its wings."），它就能生成带动画。推理入口是 unimate/inference/sample.py，所有落盘行为都在 unimate/utils/visualization.py 的visualize_and_save_motions中完成。
输出目录长什么样：一次推理的完整文件树
运行推理命令（--output_dir缺省为<exp_dir>/samples）后，目录结构固定为：
outputs/samples/ ├── manifest.json # 输出"账本"：资产、样本、运行记录 ├── captions.json # npy 文件名 → 所用提示词 ├── motions/ # 运动特征本体（模型真正的输出） │ ├── mixamo-run-rep_0-0.npy │ └── mixamo-run-rep_1-0.npy └── animations/ # 可视化预览 ├── mixamo-run-rep_0-sample0_fk.mp4 ├── mixamo-run-rep_0-sample0_ric.mp4 # 可选，默认不生成 └── mixamo_tpos.png # 该骨骼的 T-pose 静止图一句话分工：motions/存数据，animations/给人看，两个 JSON 管索引。
motions 目录：npy 运动特征文件详解
命名规则拆解
文件名遵循{case_id}-rep_{r}-{i}.npy模板（测试用例无 id 时为{object_type}-rep_{r}-{i}.npy）：
| 片段 | 含义 | 示例 |
|---|---|---|
case_id | 测试用例名，来自examples.json的id字段或提示词 slug | mixamo-run |
rep_{r} | 第 r 次重复采样（--num_repetitions） | rep_0 |
{i} | 批次内序号，保证同批不重名 | 0 |
分隔符统一用-而非_，这是为了与训练数据的{object_type}-{motion}-{clip}命名对齐，方便下游按第一个-切出骨骼类型。同一用例重复采样 3 次，就会得到rep_0、rep_1、rep_2三个文件——这正是官方建议的"多采样几个挑好的"工作流。
npy 里存的是什么：(帧, 关节, 12) 的规范特征
用np.load读进来后，形状为(F, J, 12)：
- F：帧数，最长 60 帧（配置的
max_motion_length）； - J：该骨骼的实际关节数（已按
n_joints裁掉 padding）； - 12：每关节特征宽度
feature_len，固定为 12（unimate/configs/schema.py 中强制），由前 3 维全局位置 + 局部旋转四元数(4) + 根朝向四元数(4) + 1 维占位拼成。
关键点：文件里是已反归一化的规范空间（canonical space）数据——保存前做了motion * std + mean，可直接被动画阶段消费，不需要再碰归一化统计量。这份 12 维格式与数据管线 Stage 4 提取的global_positions / local_rotations / root_facing_quat完全同构（见 data_process/utils/motion_features.py），也就是说模型输出和训练数据"长得一模一样"。
animations 目录：mp4 预览与 T-pose 图
同一次保存会在animations/写三类文件，视频均为640×640、30 FPS，画面标题带上 case_id 和提示词：
..._fk.mp4（默认必出）：用前向运动学（FK）从 npy 的旋转恢复关节位置后渲染的骨架动画——这是你最先该打开看效果的文件；..._ric.mp4（可选）：用 RIC（刚体插值曲线）恢复位置的另一版渲染。由于与 FK 结果高度重叠，推理时save_ric默认关闭；{object_type}_tpos.png：该骨骼的 T-pose 静止图，每种骨骼只渲染一次，作为动态视频的参照底图。
如果你只想省磁盘、跳过全部渲染，加--only_save_motion即可，此时只写motions/下的 npy。
manifest.json 与 captions.json：输出的"索引账本"
两个 JSON 是理解输出的钥匙，也是后续自动化流程的入口：
captions.json：npy 文件名 → 提示词的映射，每个批次写一次，中途退出也是合法索引；manifest.json：格式unimate-samples/1，包含四部分——assets（每个资产的 cond 文件、关节顺序、规范 GLB、统计数据集）、samples（每条样本的资产、case_id、提示词、类型sample/ground_truth）、runs（每次运行的 checkpoint、cfg_scale、seed、模式）。重复运行进同一目录会追加而非覆盖，早期样本保持可驱动；若同名资产换了骨骼（关节顺序不同），旧样本会自动从账本中移除。
run_animate_motion.sh正是靠这份 manifest 知道"哪个 npy 该用哪个骨骼资产、哪个 cond 来驱动"，而无需你手动再报一遍数据集和角色。
三种应用模式：专属子目录与 gt 文件
in-betweening、运动编辑、运动扩展三种模式会各自写入--output_dir下的子目录，避免与常规采样产物撞名：
关键帧补间（inbetween/）
固定--keep_frames指定的关键帧，其余帧由模型补全。生成的 GT 参考会另存为{case_id}-gt_rep_{r}-{i}.npy放在同一motions/下，并附一份inbetween_keep.json记录保留帧。注意补间模式的生成样本始终保持完整 60 帧，而 GT 被裁剪到真实长度——对比时请从第 0 帧对齐。
文本引导运动编辑（motion_edit/）
--keep_joints列出的关节全程锁在原轨迹上，其余关节按新提示词重新生成，motion_edit_keep.json记录关节名。编辑模式下样本与 GT一起裁剪到片段真实长度。
运动扩展（motion_expand/）
多段提示词链式拼接成长动作，motion_expand.json记录重叠帧数（--expand_overlap）。captions.json 中该样本的提示词是各段用|拼接而成，方便回溯每段意图。
下一步：把 npy 变成带动画的 GLB / FBX
motions/里的 npy 不只是存档——scripts/run_animate_motion.sh 可以直接吃整个输出目录（检测到manifest.json即进入清单模式），先校验运动、cond、网格三者关节顺序一致，再用规范资产驱动出每条运动一份的动画 GLB + FBX，落到<输出目录>/animated/：
bash scripts/run_animate_motion.sh outputs/samples/examples # 跳过无网格的运动：SKIP_INVALID=1 bash scripts/run_animate_motion.sh outputs/samples底层由 data_process/mesh_animation/animate_motion.py 在 Blender 无头模式执行，清单解析逻辑在 data_process/mesh_animation/sample_manifest.py。
常见问题速查（FAQ）
Q：为什么有的文件名带-gt_？那是 in-betweening / 运动编辑模式存下的 ground truth 参考（manifest.json中kind: ground_truth），用来和生成结果并排对比。
Q：一条动作为什么有两个 mp4？_fk.mp4与_ric.mp4是两种关节位置恢复方式的渲染，内容高度重合；默认只出 FK 版。
Q：可以只保留 npy 不要视频吗？可以，加--only_save_motion跳过全部渲染。
Q：往同一目录反复运行会互相覆盖吗？会追加写入并更新 manifest；rep_{r}前缀保证重复采样不撞名，但同名 npy（相同 r、i）会被后一次覆盖，这也是账本中同名资产校验存在的原因。
Q：npy 能直接导入 Blender 吗？不能直接导入，但run_animate_motion.sh一步就能把它变成带动画的关键帧 GLB/FBX；也可以参考 data_process/mesh_animation/ 下的animate_lbs.py等入口自行消费。
掌握motions（数据）、animations（预览）、双 JSON（索引）这三层结构后，UniMate 的推理输出就再无黑盒：看效果打开_fk.mp4，做程序化处理读 npy，批量出角色动画交给 manifest 驱动的脚本即可。
【免费下载链接】UniMate[SIGGRAPH Asia 2026] UniMate: One Unified Model to Animate Diverse Skeletons项目地址: https://gitcode.com/GitHub_Trending/un/UniMate
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
