SOMA-X 输入输出系统完整指南:如何保存与导出 USD 和 NPZ 动画的 5 个工程实践

原创2026-10-25 17:58:541,636 阅读

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 统一骨骼驱动身体与手部身份模型动画演示

一图看懂 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 个约定 ⚠️

  1. 单位:unit 参数支持 meters(默认)、centimeters、millimeters,文件内会记录写入时的单位,读取方按字段换算,跨团队交换动作时不会"厘米/米"踩坑。
  2. 旋转表示自动推断:poses 形状为 (N, J, 3) 时存 rotvec,(N, J, 3, 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 序列等拓扑不变的顶点动画时用它——只有关键帧顶点位置,无骨骼无蒙皮,适合喂给下游几何算法。

SOMA-X 姿态校正(pose correctives)蒙皮变形效果演示

实战工作流:从动作数据到引擎资产

第 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 中还附带重建误差便于质检。

SMPL 动作转换为 SOMA-X 格式的效果演示

第 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 数据转换效果参考:

MHR 数据转换为 SOMA-X NPZ 动画的效果演示

关键资产与文档速查表

路径 用途
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 → 引擎"的工程化管线即可跑通。

登录后查看全文
SOMA-X