SOMA 30关节骨架与stats归一化：Kimodo-SOMA-RP-ArdyRep-v1.2数据管线深度剖析
SOMA 30关节骨架与stats归一化：Kimodo-SOMA-RP-ArdyRep-v1.2数据管线深度剖析
本文带你深度剖析 Kimodo-SOMA-RP-ArdyRep-v1.2 的数据管线：这个 NVIDIA 的 3D 人体动作扩散模型如何用 SOMA 30 关节骨架描述人体、如何用 stats/ 目录下的 mean/std 归一化把动作数据喂给扩散模型，以及 config.yaml 中每一项配置如何串起整条"骨架 → 表示 → 归一化 → 去噪"的链路。
📦 一、项目结构总览：4 个文件撑起一条管线
整个仓库非常精简，全部核心资产只有下面几项：
| 文件 / 目录 | 作用 | 说明 |
|---|---|---|
| model.safetensors | 模型权重 | 282M 参数，实际大小约 1.1 GB |
| config.yaml | 构建配置 | Hydra 风格配置，声明骨架、表示、去噪器 |
| stats/motion/ | 归一化统计量 | body、global_root、local_root 三组 mean/std |
| README.md | 模型卡 | 输入输出规格、评测与许可信息 |
⚠️ 新手注意：仓库里的
*.npy与*.safetensors默认是 Git LFS 指针文件（见 .gitattributes），本地只有一两百字节的占位文本。要拿到真实数据，需要通过支持 LFS 的客户端或 HuggingFace 下载工具拉取完整文件。
🦴 二、SOMA 30关节骨架：模型到底在生成什么
Kimodo-SOMA-RP-ArdyRep-v1.2 属于 Kimodo 模型家族中基于 SOMA 骨架的分支。config.yaml 中直接指定了骨架类型：
skeleton:
_target_: kimodo.skeleton.SOMASkeleton30
它的输出规格在 README.md 中写得很清楚：
- Root Translation：根节点平移，形状为
num_frames × 3 - Joint Rotations：关节旋转矩阵，形状为
num_frames × 30 × 3 × 3（即 30 个关节、每个关节一个 3×3 旋转矩阵） - 帧率固定 30 fps，最长生成 10 秒（300 帧）
也就是说，"SOMA 30关节"并不是抽象概念，而是实打实的 30 个关节自由度，最终可以直接驱动数字人、游戏角色或人形机器人演示。
🎯 三、Ardy 动作表示：raw hip trajectory 是关键差异点
这个变体叫 ArdyRep，对应 config.yaml 中的 kimodo.motion_rep.ArdyMotionRep：
motion_rep:
_target_: kimodo.motion_rep.ArdyMotionRep
fps: 30
stats_path: ${oc.select:checkpoint_dir}/stats/motion/
根据 README.md 的说明，Ardy 表示与其他 Kimodo 模型最大的区别是：
它预测 Ardy motion representation——使用原始髋部轨迹（raw hip trajectory）作为根节点，而不是其他模型使用的平滑根轨迹（smoothed root）。
这样做的好处是与 NVIDIA 的 ARDY 系列模型输出与约束约定直接互通：根约束直接作用于原始髋部轨迹，方便做动作编辑、重定向（retargeting）等下游任务。评测时需使用 create_benchmark.py --motion_rep ardy 构建测试集。
Ardy 表示被拆成了三个统计通道，正好对应 stats/motion/ 下的三个子目录：
| 通道 | 目录 | 统计量真实数据量 | 含义 |
|---|---|---|---|
| 关节体 | stats/motion/body/ | 约 3 KB（722 个统计值） | 30 个 SOMA 关节的旋转表示 |
| 全局根 | stats/motion/global_root/ | 约 168 B（10 个值） | 全局坐标系下的根节点（原始髋部轨迹相关量） |
| 局部根 | stats/motion/local_root/ | 约 160 B（8 个值） | 局部坐标系下的根节点表示 |
💡 每组都是
mean.npy+std.npy两个文件，例如 stats/motion/body/mean.npy 与 stats/motion/body/std.npy。
📊 四、stats 归一化深度剖析：mean/std 如何变成"标准分"
这是整条数据管线中最容易被新手忽略、却至关重要的一环。原理就是最经典的 z-score 标准化：
标准化: x' = (x - mean) / std
反标准化: x = x' * std + mean
整条链路可以概括为三步：
- 训练前统计：从 700 小时 SOMA 骨架动作捕捉数据上，按
body、global_root、local_root三个通道分别统计均值mean和标准差std，保存为.npy文件； - 喂给扩散模型：训练时先把动作数据做 z-score 标准化，让各通道数据接近零均值、单位方差——这是扩散模型（diffusion model）能稳定学习噪声分布的前提；
- 生成后还原：config.yaml 中
stats_path: ${oc.select:checkpoint_dir}/stats/motion/让ArdyMotionRep在推理时加载同一份统计量，把去噪器输出的标准分动作反标准化回真实物理量（真实位置的髋部轨迹、真实量级的关节旋转）。
正因为三组统计文件总共只有几 KB，模型才能用极小的代价完成"表示层 ↔ 物理层"的双向换算——这也是这类模型卡把 stats/ 目录与权重放在同一仓库的原因：缺了 stats，权重只是无意义的数字。
⚙️ 五、配置走读：数据管线的"最后一公里"
config.yaml 全文只有 27 行，但信息密度很高，逐块看：
_target_: kimodo.model.Kimodo
num_base_steps: 1000 # 扩散基步骤数
cfg_type: separated # Classifier-free guidance 采用分离模式
denoiser:
_target_: kimodo.model.twostage_denoiser.TwostageDenoiser
- TwostageDenoiser：对应 README 中宣称的 Novel Two-Stage Transformer 架构；
- latent_dim: 1024 / ff_size: 2048 / num_layers: 16 / num_heads: 8（config.yaml）：去噪主干 Transformer 的规模；
- motion_mask_mode: concat：姿态约束（pose constraints）通过拼接方式注入，支持关节位置、旋转矩阵、朝向、根位置等约束（见 README.md）；
- input_first_heading_angle: true：输入携带首帧朝向角，方便控制起始朝向；
- llm_shape: [1, 4096] 与 num_text_tokens_override: 50：文本分支处理文本提示（text prompt），统一压成 50 个 token 送入主干；
- ckpt_path: ${oc.select:checkpoint_dir}/model.safetensors（config.yaml）：权重加载入口，指向仓库根目录的 model.safetensors。
至此，一条完整的数据管线就拼齐了：
SOMA 30关节骨架 → ArdyMotionRep 三通道表示 → stats mean/std 标准化
→ 文本 + 约束拼接 → TwostageDenoiser 去噪 → 反标准化 → 30fps 骨骼动作输出
✅ 六、新手上手避坑清单
- 先拉全 LFS 文件再运行：若
model.safetensors只有 135 字节、stats下的.npy读起来报错（如 numpy 报 pickle 相关错误），说明你拿到的是 LFS 指针而非真实数据； - stats 目录不可省略：
stats_path是相对checkpoint_dir解析的，下载模型时请保留stats/motion/的原始目录结构； - 许可：模型基于 LICENSE（NVIDIA Open Model License）发布，README 中注明 This model is ready for commercial use，商用前建议完整阅读许可条款。
📌 七、总结
Kimodo-SOMA-RP-ArdyRep-v1.2 的数据管线看似只有"骨架 + 权重 + 几 KB 统计文件"，实则环环相扣：
- SOMA 30关节骨架定义了动作的"形状"（
num_frames × 30 × 3 × 3的关节旋转）； - Ardy 表示以原始髋部轨迹为根，与 ARDY 生态直接互通；
- stats 归一化用
body / global_root / local_root三组 mean/std 完成"物理量 ↔ 标准分"的换算，是扩散模型稳定训练与正确解码的基石。
理解这条管线后，你就可以放心地把它接入自己的动作生成、动作编辑或机器人演示工作流了。