NVlabs/SOMA-X

SOMA‑X – 可微分人体与手部模型

简介 – SOMA‑X 是一个 Python 库，提供参数化人体和手部的统一可微分表示。它将多种现有的身份模型（MHR、SMPL‑X、MANO 等）映射到通用的拓扑结构和绑定（rig）上，使您能够通过单一管线对模型进行动画制作、重定向和蒙皮。

主要组件

SOMALayer – 具有三个细节级别（超低、低、中）的全身模型。
SOMAHandLayer – 左手/右手模型，同样具有三个 LOD 级别。
内置的身份后端（原生 SOMA、MHR、Anny、GarmentMeasurements），并可选支持 SMPL 系列、MANO 等。
用于姿态逆解、程序化绑定控制、平滑处理、USD/NPZ 输入输出以及几何辅助工具。
使用 NVIDIA Warp 加速运行时蒙皮和拟合。

安装

pip install py-soma-x

首次运行该库时，它会自动从 NVIDIA Hugging Face 仓库下载所需的资源并在本地缓存。可选的后端可能需要额外的 pip 扩展包和单独的文件（例如，受许可的 SMPL 或 MANO 文件）。

快速入门示例

import torch
from soma import SOMALayer, SOMAHandLayer

# Full body
body = SOMALayer(identity_model_type="mhr", device="cpu")
poses = torch.zeros(1, 77, 3)               # 77 joints, axis‑angle
shape = torch.zeros(1, body.num_shape_components)
out = body(poses, shape)
vertices, joints = out.vertices, out.joints

# Hand
hand = SOMAHandLayer(hand_type="right", lod="mid", device="cpu")
hand_poses = torch.zeros(1, 25, 3)
hand_shape = torch.zeros(1, hand.num_shape_components)
hand_out = hand(hand_poses, hand_shape)
hand_vertices, hand_joints = hand_out.vertices, hand_out.joints

返回的对象包含网格顶点和关节位置，可直接用于下游渲染或物理模拟。

典型用例

动画与重定向 – 在多个身体/手部模型间复用单一姿态序列。
可微分拟合 – 将模型集成到优化循环中（例如，姿态估计、动作捕捉）。
合成数据生成 – 采样多样化的身体形状和姿态，用于训练视觉或机器人模型。
虚拟试穿与服装模拟 – 结合 GarmentMeasurements 用于服装管线。

相关 NVIDIA 项目

GEM‑X – 基于 SOMA 的视频姿态估计。
Kimodo – 使用 SOMA 作为基础角色的文本到动作生成。
ARDY、MotionBricks、GR00T Whole‑Body Control 等，均使用 SOMA‑X 数据。

文档与资源

完整文档: https://nvlabs.github.io/SOMA-X/stable/
PyPI 页面: https://pypi.org/project/py-soma-x/
Hugging Face 上的模型资源: https://huggingface.co/nvidia/SOMA-X
技术报告（arXiv 2603.16858）提供了数学背景。

许可证 – 库代码采用 Apache‑2.0 许可证。第三方模型文件保留其原始许可证。

以上所有信息均直接取自仓库的 README。