SOMA-X 输入输出系统完整指南:如何保存与导出 USD 和 NPZ 动画的 5 个工程实践
SOMA-X 输入输出系统完整指南:如何保存与导出 USD 和 NPZ 动画的 5 个工程实践
SOMA-X 是 NVIDIA 开源的统一参数化人体模型库,它将 SMPL、MHR、Anny 等不同人体模型统一到同一套 SOMA 骨骼与拓扑约定上。它的输入输出(I/O)系统集中在 soma/io.py 模块,支持两种核心资产格式:NPZ 动画文件(参数化的"动作数据")和 USD 骨骼文件(引擎可直接使用的"角色资产")。掌握这两个格式的保存与导出方法,你就能把动作数据在 Python 管线、机器学习工作流和 Blender/Maya 等 DCC 工具之间自由流转。
一图看懂 SOMA-X 的两大输出格式:NPZ vs USD
| 对比项 | NPZ 动画(.npz) | USD 骨骼(.usd/.usda/.usdc) |
|---|---|---|
| 存的是什么 | 姿态参数 + 身份系数 + 元数据 | 骨骼层级 + 蒙皮网格 + 蒙皮权重 + 可选关键帧动画 |
| 典型用途 | 训练/推理管线存储、SOMALayer 直接回放 |
DCC 工具(Blender/Maya)、渲染引擎 |
| 文件体积 | 小(只有数值数组) | 大(含完整网格与关键帧) |
| 读取方式 | load_soma_npz() |
load_rig_from_usd() / DCC 直接打开 |
简单记:NPZ 存"参数",USD 存"角色"。两者互补——先用 NPZ 管理动作数据,需要进引擎时再导出为 USD。所有 I/O 功能都是这个模块的统一文件边界,官方 API 参考见 docs/api/io.rst。
NPZ 动画文件解剖:一个文件回放完整动画
save_soma_npz() 把一个动画的全部信息打包压缩(np.savez_compressed),load_soma_npz() 读回后既可当字典用(data["poses"])也可属性访问(data.poses)。
核心字段一览
| 字段 | 形状 | 说明 |
|---|---|---|
poses |
(N, J, 3) 或 (N, J, 3, 3) | 关节旋转,轴角(rotvec)或旋转矩阵 |
transl |
(N, 3) | 根关节平移 |
identity_model_type |
字符串 | 身份模型类型,如 smpl、mhr、anny |
identity_coeffs |
(N, C) | 身份形状系数 |
joint_names |
J | 关节名列表 |
rotation_repr / absolute_pose / unit / keep_root |
元数据 | 格式自描述,读取端据此还原 |
scale_params / joint_orient / global_scale / hand_type |
可选 | 仅在保存时提供才写入 |
保存前必知的 3 个约定 ⚠️
- 单位:
unit参数支持meters(默认)、centimeters、millimeters,文件内会记录写入时的单位,读取方按字段换算,跨团队交换动作时不会"厘米/米"踩坑。 - 旋转表示自动推断:
poses形状为(N, J, 3)时存 rotvec,(N, J, 3, 3)时存矩阵,无需手动指定。 - keep_root 与关节数:默认剔除虚拟 Root 关节(J=77),与
SOMALayer.pose()输入约定一致;CLI 加--keep-root则保留 78 关节。
最小示例(完整实现见 soma/io.py):
from soma.io import save_soma_npz, load_soma_npz
save_soma_npz("anim.npz", poses, transl,
joint_names=names, identity_model_type="mhr",
identity_coeffs=beta, unit="meters")
data = load_soma_npz("anim.npz")
USD 导出:写出引擎里能直接动的"角色"
save_soma_usd:一个函数生成 UsdSkel 骨骼资产
soma/io.py 中的 save_soma_usd() 负责写出完整 USD 骨骼资产,内部做了很多"脏活":
- 骨骼:自动生成
UsdSkelSkeleton(关节路径、bindTransforms、restTransforms) - 蒙皮网格:每个顶点保留 top-k(默认 8)个关节影响,稀疏化写入
skel:jointIndices/Weights - 动画(可选):提供
rotations与root_translation时写入SkelAnimation,旋转矩阵先经 SVD 修正再转四元数,并做跨帧符号连续性处理,避免播放时"骨骼乱跳" - 阶段元数据:自动写入
metersPerUnit与 Y 轴向上,保证 DCC 中比例、朝向正确
不提供动画参数时则写出静态 rig(仅绑定姿态 + 蒙皮网格)。
export_soma_usd:从 SOMALayer 一键导出 🚀
save_soma_usd 需要手动传一堆缓存数据,export_soma_usd() 则是高层便捷封装(soma/io.py):它直接从 SOMALayer 中提取已缓存的绑定变换、rest 形状、蒙皮权重与关节元数据。注意两点:
- 调用前必须先执行
layer.prepare_identity(identity_coeffs),否则报错No cached identity. Call prepare_identity() first. - 导出单位以 layer 的
output_unit为准,unit参数若指定必须与之一致
save_vertex_animation_usd:无骨骼的顶点动画
导出目标网格、blendshape 序列等拓扑不变的顶点动画时用它——只有关键帧顶点位置,无骨骼无蒙皮,适合喂给下游几何算法。
实战工作流:从动作数据到引擎资产
第 1 步:用 CLI 工具生成 NPZ 动画 📦
仓库自带一系列转换工具(详见 docs/tools.md):
# SMPL 动作 → SOMA NPZ
python -m tools.smpl2soma --output-npz out/smpl-soma.npz
# MHR parquet 数据 → SOMA NPZ
python -m tools.mhr2soma --input /path/to/parquet-directory --output-npz out/mhr-soma.npz
批量转换 AMASS 数据集用 tools/convert_amass_to_soma.py,支持目录树批量处理,导出 NPZ 中还附带重建误差便于质检。
第 2 步:(可选)转换身份后端
拿到规范 SOMA NPZ 后,tools/convert_identity_backend.py 能保留原动画、仅把身份参数优化到目标后端(如 SMPL-X betas → 原生 SOMA 系数 + 骨骼长度 scale),输出 NPZ 内含 loss 历史与逐身份绑定姿态顶点误差。手部模型另有 tools/hand/convert_identity_backend.py 与 MANO 互转工具 tools/hand/mano2soma.py、tools/hand/soma2mano.py。
第 3 步:导出 USD 进入 DCC
python -m tools.smpl2soma --output-npz out/anim.npz # 先出 NPZ
随后用 Python 一行调用 export_soma_usd(out_usd, layer, rotations, root_transl) 产出可在 Blender/Maya 直接打开的 USD。若需要程序化 twist 关节与 DCC 联动,Blender/Maya 集成见 tools/soma_procedural_blender/README.md 与 tools/soma_procedural_maya/README.md。
第 4 步:回放验证
load_soma_npz() 读回数据即可用 SOMALayer 逐帧回放;仓库自带示例动作 assets/example_animation.npy 可直接用于冒烟测试。MHR 数据转换效果参考:
关键资产与文档速查表
| 路径 | 用途 |
|---|---|
| assets/SOMA_template_rig.usda | 必需骨骼模板(关节层级、绑定/T-pose、蒙皮权重) |
| assets/SOMA_neutral.npz | 形状 PCA 模型 + 网格拓扑 |
| assets/SOMA_procedural_transforms.json | 程序化 twist 控制定义 |
| soma/io.py | I/O 模块全部实现 |
| docs/api/io.rst | I/O API 参考(含 LOD rig 加载函数) |
| docs/data_assets.md | 各资产字段详细文档 |
| docs/tools.md | 全部 CLI 工具用法 |
常见报错速查 ✅
| 报错 | 原因与解法 |
|---|---|
No cached identity. Call prepare_identity() first. |
导出 USD 前未调用 prepare_identity() |
USD export requires the 'usd-core' package |
安装依赖:pip install usd-core |
unit 不匹配 output_unit |
export_soma_usd 按 layer 的输出单位写数据,构造 layer 时就要指定期望单位 |
| 关节数 77 vs 78 对不上 | 检查 keep_root:默认存 77 关节(无虚拟 Root) |
小结
SOMA-X 的输入输出系统设计很清晰:NPZ 负责轻量的动作与身份参数流转,USD 负责与 DCC/引擎对接的完整骨骼资产,而 soma.io 模块提供了从 save_soma_npz、load_soma_npz 到 export_soma_usd 的全套工具。配合仓库内置的 SMPL/MHR/AMASS/MANO 转换 CLI,一条"原始数据 → NPZ → USD → 引擎"的工程化管线即可跑通。



