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。