NVlabs/SOMA-X

[](https://badge.fury.io/py/py-soma-x) [](https://opensource.org/licenses/Apache-2.0) [](https://arxiv.org/abs/2603.16858) **[文档](https://nvlabs.github.io/SOMA-X/stable/)** | [PyPI](https://pypi.org/project/py-soma-x/) | [更新日志](CHANGELOG.md) ## 概述 参数化人体模型，包括 SMPL、SMPL-X、MHR、Anny 和 GarmentMeasurements，是人体重建、动画和模拟等众多任务的核心。然而，这些模型本质上互不兼容：每个模型都定义了各自的网格拓扑、关节层级和参数化方式，无法实现无缝集成。因此，要利用不同模型之间的互补优势（例如将 Anny 的年龄范围控制与基于 SMPL 的运动数据相结合），必须为每一对模型定制 adapter，这阻碍了互操作性并限制了实际应用。 我们提出了 **SOMA**——一种规范的 body topology 和 rig，可作为所有受支持的参数化人体模型的通用枢纽。**SOMA 并非要取代现有模型，而是通过将其多样化的静态形状映射到一个单一的共享表示上来实现统一**。这种方法允许使用统一的动画 pipeline 对任何受支持的 identity model 进行动画处理，从而无需自定义 adapter 或特定于模型的 retargeting。借助 SOMA，你可以在推理时自由组合 identity 来源和 pose 数据，而无需额外的工程开发。整个 pipeline 通过 NVIDIA Warp 保持端到端的可微性及 GPU 加速。 查看 SOMA 的实际运行效果：

## 支持的 Identity 模型 SOMA 目前支持五种不同的 identity 模型，每种模型都提供独特的功能： 1. [MHR](https://github.com/facebookresearch/MHR)：SOMA 中的默认 identity 模型，提供高保真的人体形状表示。 2. [Anny](https://github.com/naver/anny)：特别适合儿童建模，将适用性扩展到了更年轻的对象。 3. [SMPL-Family](https://smpl.is.tue.mpg.de/)：支持 SMPL 和 SMPL-X 模型，实现了与该领域现有标准的互操作性。 4. **SOMA-shape**：作为本项目一部分开发的基于 PCA 的专有模型，旨在提供类似 SMPL 的功能，并使用 128 个 PCA 系数进行 identity 表示。 5. [GarmentMeasurements](https://github.com/mbotsch/GarmentMeasurements)：在 CAESAR 数据集上训练的基于 PCA 的 identity 模型，适用于涉及服装试穿和测量的特殊用例。 ## 统一的 Pose 修正（Beta） 得益于 SOMA 的统一框架，用于减轻 LBS 伪影的 pose 相关修正变形可无缝用于所有受支持的 identity 模型，包括那些自身不提供修正的模型（例如 Anny 和 GarmentMeasurements）。

## 已经支持 SOMA 的相关项目 SOMA 是实现人体动画、机器人技术、物理 AI 及其他应用的更广泛努力的一部分。我们还提供了以下支持 SOMA 的研究工作： * [GEM](https://github.com/NVlabs/GEM-X) - 基于 SOMA 的视频 pose 估计。 * [Kimodo](https://github.com/nv-tlabs/kimodo) - 基于 SOMA 的、针对 **human(oid)s** 的可控 text-to-motion 生成方法。 * [BONES-SEED Dataset](https://huggingface.co/datasets/bones-studio/seed) - 大规模的 SOMA 格式 human(oid) 动作捕捉数据集。还提供了 retargeted 后的 G1 数据。 * [SOMA Retargeter](https://github.com/NVIDIA/soma-retargeter) - 用于 SOMA 到 G1 的 retargeting。 * [ProtoMotion](https://github.com/NVlabs/ProtoMotions) - 用于训练物理模拟数字 human(oid)s 的模拟与学习框架。 * [GEAR SONIC](https://github.com/NVlabs/GR00T-WholeBodyControl) - 人形机器人行为基础模型。（即将推出） ## 安装 ### 从 PyPI 安装 安装 SOMA-X 最简单的方法是通过 [PyPI](https://pypi.org/project/py-soma-x/)： ``` pip install py-soma-x ``` 包含可选的附加组件： ``` pip install "py-soma-x[smpl]" # SMPL/SMPL-X support pip install "py-soma-x[anny]" # Anny support ``` Assets 会在首次使用时从 HuggingFace 自动下载（缓存在 `~/.cache/huggingface/hub/` 中）。

开发者安装（使用 Git LFS 克隆）

### 使用 Git LFS 克隆（Assets 必需） 此仓库对大型 asset 文件（例如 assets/Nova_neutral.npz）使用了 Git LFS。你必须安装 Git LFS 才能下载实际数据；否则，你将遇到文件加载错误。 1. 安装 Git LFS（如果尚未安装）： ``` git lfs install ``` 2. 克隆并拉取数据： ``` git clone https://github.com/NVlabs/SOMA-X.git cd SOMA-X git lfs pull ``` _(如果你已经克隆了仓库，只需运行 `git lfs pull` 即可获取缺失的 assets。)_ ### 准备 Python 环境 **Linux:** ``` pip install uv uv venv .venv source .venv/bin/activate # or: . .venv/bin/activate # 安装带有 CUDA 的 PyTorch — 调整版本 (cu124, cu126, cu130, …) # 以匹配你的 GPU 和驱动。参见 https://pytorch.org/get-started/locally/ uv pip install torch --index-url https://download.pytorch.org/whl/cu124 uv pip install ".[dev]" ``` **Windows (PowerShell):** ``` pip install uv uv venv .venv Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser # one-time setup .\.venv\Scripts\activate # 安装带有 CUDA 的 PyTorch — 调整版本 (cu124, cu126, cu130, …) # 以匹配你的 GPU 和驱动。参见 https://pytorch.org/get-started/locally/ uv pip install torch --index-url https://download.pytorch.org/whl/cu124 uv pip install ".[dev]" ``` 然后运行测试：`pytest tests/ -v`。 ### 可选依赖项 **对于 SMPL 和 SMPLX 支持：** ``` uv pip install ".[smpl]" pip install --no-build-isolation chumpy ``` _注意：`chumpy`（在 runtime 被 `smplx` 需要）的 PyPI 构建版本已损坏，必须使用 `--no-build-isolation` 安装。如果失败，请从源码安装：`pip install --no-build-isolation git+https://github.com/mattloper/chumpy@580566eafc9ac68b2614b64d6f7aaa8`_ 你还需要单独下载 `SMPL_NEUTRAL.pkl` 或 `SMPLX_NEUTRAL.npz`： 1. 访问 [SMPL](https://smpl.is.tue.mpg.de/) 或 [SMPLX](https://smpl-x.is.tue.mpg.de/) 网站。 2. 注册并下载 SMPL（适用于 Python 的 v1.1.0 版本）或 [SMPL-X](https://download.is.tue.mpg.de/download.php?domain=smplx&sfile=smplx_lockedhead_20230207.zip)（已移除头部发髻）模型文件。 3. 解压并将 `SMPL_NEUTRAL.pkl` 复制到 `./assets/SMPL/SMPL_NEUTRAL.pkl`，将 `SMPLX_NEUTRAL.npz` 复制到 `./assets/SMPLX/SMPLX_NEUTRAL.npz`。 **注意：** SMPL 模型受单独的许可证约束，不能随此仓库一起重新分发。 **对于 [Anny](https://github.com/naver/anny) 支持：** ``` uv pip install ".[anny]" ``` **对于 [GarmentMeasurements](https://github.com/mbotsch/GarmentMeasurements) 支持：** ``` git clone https://github.com/mbotsch/GarmentMeasurements python tools/convert_gm_pca_to_npz.py ./GarmentMeasurements/data/pca/point.pca assets/GarmentMeasurements/point.npz rm -rf GarmentMeasurements ```

## 使用方法 ### 全身模型 ``` import torch from soma import SOMALayer # 初始化层 — assets 会从 HuggingFace 自动下载 soma = SOMALayer( identity_model_type="mhr", # or "soma" "smpl", "smplx", "anny", "garment" device="cuda" ) # 或者使用本地 assets 目录 # soma = SOMALayer(data_root="./assets", identity_model_type="mhr", device="cuda") # 前向传播 # poses: (B, num_joints, 3) # identity: (B, num_coeffs) # scale_params: (B, soma.num_scale_params) - 可选，取决于模型类型。 # 对于原生 SOMA 骨骼缩放，soma.scale_param_names 定义了激活的子关节， # 而 soma.scale_param_segments 定义了匹配的局部父节点到子节点的边。 output = soma(poses, identity, scale_params=scale_params) vertices = output["vertices"] ``` ## 运行 Demo 安装 demo 环境（包括用于视频输出的 pyrender、tqdm、带有 ffmpeg 的 imageio）： ``` uv pip install ".[demo]" ``` 如果你想运行所有 identity 模型（soma、mhr、anny、smpl、smplx、garment），请安装全套组件并使用与测试相同的构建步骤： ``` uv pip install -e ".[all,demo]" pip install --no-build-isolation chumpy ``` 然后运行 demo 脚本： ``` # 运行所有模型（默认：soma, mhr, anny, smpl, smplx, garment） python tools/demo_soma_vis.py --data-root ./assets --output-dir ./out # 仅运行特定模型 python tools/demo_soma_vis.py --data-root ./assets --output-dir ./out --identity-model-type soma, mhr, smplx # 运行单个模型 python tools/demo_soma_vis.py --data-root ./assets --output-dir ./out --identity-model-type anny # 使用随机形状运行 MHR python tools/demo_soma_vis.py --data-root ./assets --output-dir ./out --identity-model-type mhr --random-shape # 渲染超低 LOD python tools/demo_soma_vis.py --data-root ./assets --output-dir ./out --identity-model-type soma,mhr --lod xlo ``` 这将在 `out/` 目录下为选定的模型生成示例动画视频。 **全身 demo 选项：** - `--identity-model-type`：以逗号分隔的模型列表（选项：`soma`、`mhr`、`anny`、`smplx`、`smpl`、`garment`，默认：所有模型） - `--lod`：要渲染的 body mesh 的 LOD（`mid`、`low` 或 `xlo`；默认：`mid`）。`xlo` 网格使用其自己的 USD topology/skinning，并使用 v0026 低 LOD 网格进行 identity 骨架拟合。 - `--random-shape`：平滑地为随机 body shape 添加动画，而不是使用中性 shape - `--motion-file`：自定义运动文件的路径（默认：`assets/ROM5.npy`） - `--image-size`：渲染分辨率（默认：`1920`） - `--device`：要使用的设备（默认：`cuda:0`） ## 将其他模型的 pose 参数转换为 SOMA 我们提供了转换工具，可以将 SMPL 和 MHR 的 pose 参数转换为 SOMA。 这两个工具都使用 `PoseInversion.fit()`，它支持两个互补的求解器——两者都通过单次 skeleton transfer 拟合进行初始化，以实现快速收敛： - **Analytical**（默认）：带有 Newton-Schulz 细化的迭代逆 LBS。速度极快（约 1200 FPS），且具有相当的精度。 - **Autograd FK**：通过反向传播 FK + LBS 进行 6D 旋转优化。速度慢但可控（例如对四肢增加额外权重）。 两者可以结合使用：analytical 求解为 autograd 细化进行热启动——结合了双方的优点。 ### SMPL 到 SOMA ``` # 将 SMPL 动画转换为 SOMA（渲染对比视频） python -m tools.smpl2soma # 将 SOMA poses 导出为 .npz python -m tools.smpl2soma --output-npz out/smpl_soma.npz # 调整 analytical 迭代次数（默认：--body-iters 2 --full-iters 1） python -m tools.smpl2soma --body-iters 3 --full-iters 1 --batch-size 64 # Analytical + autograd FK 优化（最佳精度） python -m tools.smpl2soma --body-iters 2 --full-iters 1 --autograd-iters 10 ``` **基准测试**（402 帧 SMPL 帧，RTX 5000 Ada）： | 方法 | 速度 | 平均值 | 中位数 | 最大值 | |---|---|---|---|---| | Analytical (body=2, full=1) — **默认** | **1279 FPS** | 0.65 cm | 0.52 cm | 17.8 cm | | Autograd FK (10 iters, lr=5e-3) | 199 FPS | 1.04 cm | 0.97 cm | 18.1 cm | | Autograd FK (100 iters) | 18 FPS | 0.49 cm | 0.39 cm | 16.8 cm | ### MHR 到 SOMA 适用于 [SAM 3D Body](https://huggingface.co/datasets/facebook/sam-3d-body-dataset) 或类似的 MHR 格式数据。 ``` # 转换包含 SAM 3D Body parquet 文件的目录 python -m tools.mhr2soma --input path/to/sam_3d_body/data/coco_train # 转换并导出为 .npz python -m tools.mhr2soma --input path/to/parquet_dir --output-npz out/mhr_soma.npz # 调整 analytical 迭代次数（默认：--body-iters 2 --full-iters 1） python -m tools.mhr2soma --input path/to/parquet_dir --max-samples 100 --body-iters 3 # Analytical + autograd FK 优化（最佳精度） python -m tools.mhr2soma --input path/to/parquet_dir --autograd-iters 10 ``` **基准测试**（200 个 SAM 3D Body 样本，RTX 5000 Ada）： | 方法 | 速度 | 平均值 | 中位数 | 最大值 | |---|---|---|---|---| | Analytical (body=2, full=1) — **默认** | **342 FPS** | 0.61 cm | 0.34 cm | 14.8 cm | | Autograd FK (10 iters, lr=5e-3) | 161 FPS | 1.05 cm | 0.76 cm | 13.5 cm | | Autograd FK (100 iters) | 16 FPS | 0.48 cm | 0.22 cm | 13.3 cm | ### AMASS 数据集到 SOMA 将 [AMASS](https://amass.is.tue.mpg.de/) 运动序列（SMPL 格式的 `.npz` 文件）转换为 SOMA。 ``` # 单个文件 — 转换并渲染对比视频 python -m tools.convert_amass_to_soma --input path/to/amass_sequence.npz # 单个文件 — 仅导出 .npz（跳过渲染） python -m tools.convert_amass_to_soma --input path/to/amass_sequence.npz --output-npz out/soma.npz --no-render # 批量转换整个数据集（镜像文件夹结构） python -m tools.convert_amass_to_soma --input-dir /data/amass/ --output-dir out/amass_soma/ # 打乱文件顺序（在并行运行多个 worker 时很有用） python -m tools.convert_amass_to_soma --input-dir /data/amass/ --output-dir out/amass_soma/ --shuffle # 调整 analytical 迭代次数 python -m tools.convert_amass_to_soma --input path/to/seq.npz --body-iters 3 --full-iters 1 # Analytical + autograd FK 优化（最佳精度） python -m tools.convert_amass_to_soma --input path/to/seq.npz --autograd-iters 10 ``` 输出的 `.npz` 文件包含： - `poses`：每个关节的 `(N, J, 3)` 旋转向量 - `root_translation`：以米为单位的 `(N, 3)` 根节点位置 - `joint_names`：SOMA 关节名称列表 - `per_vertex_error`：每个顶点的 `(N, V)` 重建误差 - `identity_coeffs` / `scale_params`：使用的 identity 参数 **基准测试** (A100): | 方法 | 速度 | 平均值 | 中位数 | 最大值 | |---|---|---|---|---| | Analytical (body=2, full=1) — **默认** | **17393 FPS** | 0.53 cm | 0.32 cm | 8.8 cm | | Autograd FK (10 iters, lr=5e-3) | 435 FPS | 0.78 cm | 0.64 cm | 8.8 cm | ## 引用 如果你在你的工作中使用了此代码，请引用： ``` @article{soma2026, title={SOMA: Unifying Parametric Human Body Models}, author={Jun Saito and Jiefeng Li and Michael de Ruyter and Miguel Guerrero and Edy Lim and Ehsan Hassani and Roger Blanco Ribera and Hyejin Moon and Magdalena Dadela and Marco Di Lucca and Qiao Wang and Xueting Li and Jan Kautz and Simon Yuen and Umar Iqbal}, eprint={2603.16858}, archivePrefix={arXiv}, year={2026}, url={https://arxiv.org/abs/2603.16858}, } ``` ## 致谢 - [SMPL-Body](https://smpl.is.tue.mpg.de/bodylicense.html) 用于创建 SMPL 和 SOMA 网格拓扑之间的插值器，由马克斯·普朗克智能系统研究所提供。 - [MHR](https://github.com/facebookresearch/MHR) 用于学习 pose 修正模型。 - [Anny](https://github.com/naver/anny) 提供了基于 [WARP](https://github.com/NVIDIA/warp) 的稀疏线性混合蒙皮。 - [GarmentMeasurements](https://github.com/mbotsch/GarmentMeasurements) 用于扩充我们 shape 模型中的数据。 ## 许可证 此代码库采用 [Apache-2.0](LICENSE) 许可。 本项目将下载并安装额外的第三方开源软件项目。在使用前，请查阅这些开源项目的许可条款。

标签：3D动画, Python, Vectored Exception Handling, 凭据扫描, 参数化人体模型, 无后门, 计算机图形学, 计算机视觉, 逆向工具