企业官网建设流程全解析

• 人工智能
• 图形学
• 计算机视觉
• 数字人

SOMA-X 是 NVIDIA 开源的统一参数化人体模型（Unifying Parametric Human Body Models），它将身份表示（identity）与姿态参数化（pose）解耦，把 SMPL、SMPL-X、MHR、ANNY 等六种身份后端统一映射到同一套拓扑与骨架上。本文以 API 参考的形式，详解 SOMA-X 的输入输出接口：身份系数、姿态参数的张量形状（如(B, K)、(B, 77, 3)）、网格输出的顶点数以及所有几何量的单位约定，帮助你在接入管线时一次配对接口。

一、输入输出总览：一张表看懂 SOMA-X 张量接口

SOMA-X 的所有输入输出都是PyTorch float32 张量，批次维度统一记为B。核心接口一览：

💡 关键记忆点：关节数固定为 77（不含 root 虚拟关节），所有几何输出的单位都是米，姿态角度一律用弧度。

二、身份系数详解：(B, K)形状系数向量

身份系数（Identity Coefficients）描述"这个人长什么样"，是一维系数向量，不同后端维度K不同：

• SOMA-shape（原生后端）：K = 128，对应 128 个 PCA 主成分，作用于约 18,000 个中 LOD 顶点，权重文件见 SOMA_neutral.npz。
• SMPL / SMPL-X / MHR / ANNY / GarmentMeasurements：K为各后端模型的 shape 维度（例如 SMPL 通常为 10）。各后端的"身份网格 → SOMA 网格"映射由预计算的稀疏重心坐标对应矩阵完成，资产文件如 SMPL/SOMA_wrap.obj、MHR/mhr_model_lod1.pt、GarmentMeasurements/SOMA_wrap.obj。

⚠️使用注意：身份系数没有硬性截断（no hard clipping），应落在对应后端的形状空间内；超出分布的极端值可能产生破面或几何伪影。

三、姿态参数详解：77 关节的轴角与旋转矩阵

姿态参数（Pose Parameters）覆盖77 个可动关节（不含 root dummy joint），支持两种等价的输入形式：

• 轴角（axis-angle）：(B, 77, 3)，每关节一个 3D 轴角向量，遵循标准 axis-angle 约定，不做任何夹取（clamping），角度单位为弧度；
• 旋转矩阵：(B, 77, 3, 3)，右手法则。

可选地传入根节点平移(B, 3)，单位为米。

SOMA-X 的内部管线是"关节朝向（相对 T-pose）参数化 + 线性混合蒙皮（LBS）"，因此同一套轴角姿态可以直接复用到任意身份后端——这正是 SOMA-X"统一姿态接口"的核心价值：运动数据只需采集一次，即可驱动 SMPL、MHR、ANNY 等不同身份的网格。

四、手部层接口：25 关节姿态与 20 维手身份系数

SOMA-X v0.3 新增腕部局部（wrist-local）的左右手层（SOMAHandLayer），支持 mid / low / xlo 三级 LOD 以及采样姿态先验，手部资产见 SOMAHand.npz 与 MANO/SOMA_wrap_left.obj：

• 手姿态：轴角(B, 25, 3)或旋转矩阵(B, 25, 3, 3)，其中第 0 号关节表示腕部（wrist）；
• 手身份系数：原生 SOMA 手 PCA 为(B, 20)，也可使用 MANO/MHR 后端的对应维度；
• 手部输出：腕部局部坐标系下的顶点(B, V_h, 3)，其中V_h为 2,859（mid）、718（low）、134（xlo）；关节位置(B, 25, 3)与关节变换(B, 25, 4, 4)。

🖐️ 若你已有 MANO 模型（独立许可，需自行提供），SOMA-X 提供了 MANO 互操作路径，可以直接复用现有的手部估计结果。

五、网格输出详解：顶点数由 LOD 决定

姿态化网格顶点的形状为(B, N_h, 3)，N_h由构造SOMALayer(lod=...)时的 LOD 参数决定：

其余输出约定：

• 关节位置(B, 77, 3)：世界空间 3D 关节位置，单位米；
• 静息形状顶点(B, N_h, 3)：按身份（未加姿态）生成的顶点，属于中间输出，按需获取；
• low_lod=True是lod="low"的旧版别名，新代码建议直接使用lod参数。

得益于闭式解析管线（重心网格迁移 + RBF 骨架拟合 + LBS），SOMA-X 在 A100（batch=128）上可达 7,000+ 网格/秒，单张网格 GPU 延迟约 2.1 ms，非常适合实时仿真与大规模批处理。

六、单位与坐标约定：米、弧度与 float32

把以下三条写进你的代码注释，可以避免 90% 的单位 bug：

1. 长度单位统一为米（meters）：根平移、身体/手部顶点、关节位置全部是米。注意与动画工具链（如 USD 工程文件）对接时可能遇到厘米单位——例如 SOMA_procedural_transforms.json 中 rig 侧约定units为 centimeters，跨域时记得换算；
2. 角度单位统一为弧度（radians）：轴角、欧拉角、四元数转换都不需要额外缩放；
3. 精度统一为 float32：所有输入输出均为标准 float32 PyTorch 张量，各后端身份模型内部完成归一化，无需额外预处理。

七、文件资产对照：输入系数与权重从哪来

仓库中的每个目录对应一类输入来源，方便你按后端定位文件：

完整的输入输出规格与许可信息（Apache 2.0）可查阅仓库根目录的 README.md。

八、常见问题速查：SOMA-X 张量接口避坑清单

• Q：姿态张量为什么是 77 而不是 78 或更多？A：77 是剔除 root dummy joint 后的可动关节数，根位移由可选的(B, 3)根平移单独提供，关节数在所有后端下固定为 77。
• Q：输出的顶点是 T-pose 还是姿态后的？A：(B, N_h, 3)是姿态化（posed）顶点；静息形状（rest-shape）顶点是另一个中间输出，默认不提供、按需获取。
• Q：身份系数超范围会报错吗？A：不会报错，系统不做硬截断，但极端越界值会产生伪影几何，建议对系数做范围监控。
• Q：手部坐标系是全局的还是局部的？A：手部顶点输出在腕部局部坐标系下，需要与身体对齐时请用输出中的手部关节变换(B, 25, 4, 4)进行变换。
• Q：能否纯 CPU 运行？A：可以。核心管线为闭式解析计算，提供 PyTorch CPU 回退路径，无需 CUDA。

掌握以上张量形状、LOD 顶点数与"米 + 弧度 + float32"三大约定，你即可在 PyTorch / NVIDIA Warp 等后端中顺畅接入 SOMA-X 的统一身份与姿态管线。

• 人工智能
• 图形学
• 计算机视觉
• 数字人