Kimodo 入门教程（二）英伟达开源人形机器人动捕数据集训练运动学动作扩散模型

多角色支持：支持使用 Kimodo 的 SOMA、G1 和 SMPL-X 版本进行生成
文本提示：在时间轴上输入一个或多个描述所需动作的自然语言描述
时间轴编辑器：在多个约束轨道上添加和编辑关键帧及受约束区间
约束类型：
- 全身约束：在特定帧设置完整的关节位置约束
- 2D 根点：在地面平面上定义路径点或完整路径以供跟随
- 末端执行器：控制手部和脚部的位置/旋转角度
约束编辑：编辑模式支持重新调整约束姿势或修改路径点
3D 可视化：实时渲染生成的动作，支持骨骼和蒙皮网格选项
播放控制：以可调节的播放速度预览生成的动作
多重样本：生成并比较多种动作变体
示例：加载现成示例以更好地了解 Kimodo 的功能
导出：保存约束和生成的动作以备后用

1.1 运行演示程序

按照安装说明操作后，可通过以下命令启动演示程序。演示程序将在网页浏览器中运行，地址为 http://localhost:7860。

若在服务器上运行演示程序，可使用端口转发进行访问。

若要在远程服务器上访问演示程序的 Web 界面，请设置 SSH 端口转发，以便您的 Web 浏览器能够像访问本地服务器一样访问 http://localhost:7860。

在 SSH 配置文件中添加 LocalForward
编辑（或创建）您的 SSH 配置文件（通常位于 ~/.ssh/config）：
```
Host your-server-name
    HostName your.server.address
    User username
    LocalForward 7860 localhost:7860
```
然后连接到：
```
ssh your-server-name
```
直接使用 SSH 命令行
在您的本地计算机上运行：
```
ssh -N -L 7860:localhost:7860 username@your.server.address
```
这将把您的本地端口 7860 转发到服务器的端口 7860。连接成功后，请在网页浏览器中打开 http://localhost:7860。

请将 username 和 your.server.address 替换为您实际的用户名和服务器地址。

如果您需要频繁重启演示，建议先按照快速入门指南中的说明，在后台启动文本编码器服务。如果文本编码器服务未运行，演示将自动加载文本编码器模型。

演示在启动时以及用户界面中更改模型首选项时，也会自动下载 Kimodo 模型检查点。

1.1.1 从命令行启动

无论您是通过软件包还是源代码安装的 Kimodo，均可使用以下命令启动演示程序：

kimodo_demo

1.1.2 使用 Docker 启动

如果您是通过 Docker 安装的，可以使用以下命令启动演示：

docker compose up demo

如果您在 Docker 容器中运行 Kimodo，以下命令可能会对您有所帮助。在下面的示例命令中，您也可以将 demo 替换为 text-encoder：

查看日志：

docker compose logs demo

停用服务：

docker compose stop demo

重启服务：

docker compose restart demo

停止并移除所有内容：

docker compose down

1.2 UI 概述

本页面概述了演示界面的各个主要元素及其使用方法。

1.2.1 查看器

3D 查看器显示当前生成的运动。它支持骨骼或蒙皮网格渲染，相关设置可在“可视化”面板中进行配置。

1.2.1.1 摄像机

向左拖动：旋转
向右拖动：平移
滚动：缩放

1.2.1.2 播放

空格键播放/暂停
←/→ 逐帧播放，或点击帧号。

1.2.2 时间轴

时间轴是您：

添加、编辑和删除提示片段
在帧或时间间隔处添加和删除约束条件，并调整时间

1.2.2.1 时间轴导航

在时间轴上滚动上下：左右移动
按住 Shift 键并滚动时间轴：放大/缩小

1.2.2.2 提示

双击文本提示以编辑文本
点击并拖动提示框的右边缘以延长/缩短其时长（2-10 秒）
点击空白处以添加提示
右键点击提示以删除它

1.2.2.3 约束

在查看器中存在活动动作时，首次生成后可添加约束：

在时间轴轨道（全身/2D根等）上单击，以使用该帧的姿势添加该类型的约束条件
按住 Ctrl/Cmd 键并单击拖动以添加间隔约束，或将关键帧扩展为间隔
单击并拖动现有约束将其移动到其他帧
右键单击约束以删除它
要编辑约束：
- 将播放光标移至目标帧
- 在“设置”面板的“约束”选项卡中点击“进入编辑模式”。请注意，再次生成前必须退出编辑模式。

1.2.3 设置面板

设置面板包含：

模型选择
加载示例
用于生成和后处理的模型参数选择
约束编辑参数
运动加载和保存
可视化选项

后续页面将分别对重要设置面板进行详细说明。

1.3 模型选择

模型选择功能允许您在快速入门指南中详细介绍的Kimodo模型之间进行选择。

这些模型决定了场景中加载的角色以及可用的导出选项。

SOMA：默认人体骨骼
G1：支持MuJoCo格式的导出
SMPL-X：支持SMPL-X格式的输出

有关各骨骼的详细信息，请参阅“骨骼”部分。

1.4 示例

设置面板中的“示例”选项卡包含多个示例，这些示例突出了 Kimodo 的关键功能及其潜在的工作流程。其中包含了针对 Kimodo-SOMA-RP 和 Kimodo-G1-RP 模型的示例。

从下拉菜单中选择一个示例后，点击“加载示例”将示例配置加载到查看器中。

查看器将在时间轴上显示预生成的运动，以及用于生成该运动的提示和约束条件。用于生成模型的所有设置（例如初始值、无分类器引导设置）也会随示例一并加载，因此您只需在面板中点击“生成”即可恢复相同的结果。

这些示例涵盖了多种生成方式，包括使用一个或多个文本提示以及运动学约束进行生成。

保存新示例：生成动作后，您可以在“设置”面板的“加载/保存”选项卡下保存一个新示例。您应能立即看到“示例”下拉菜单更新为新保存的示例，以便日后加载。

本节将逐步介绍常见的工作流程以及如何使用该网络应用。每个工作流程都有独立的章节和配套视频。

1.5 生成

最重要的面板是“生成”面板，它允许您调用 Kimodo，根据提供的提示、约束和设置生成一个或多个动作。

采样数量：根据当前设置生成的动作数量。当生成多个采样时，在编辑约束或生成新动作之前，必须通过在查看器中点击角色来选择其中一个采样。
SOMA 层：若使用 Kimodo-SOMA 模型，此选项将显示。它允许您使用 SOMA 身体层为角色贴皮，而非使用 SOMA 骨骼系统。有关两者的区别，请参阅“骨骼”页面。
种子：用于可重复生成的随机种子
去噪步骤：DDIM 所使用的步骤数
CFG 文本/约束权重：用于无分类器引导的权重值
后处理：是否使用脚部滑动清理和约束后优化来改善生成后的动作
- 根节点容差：如果骨骼根节点偏离约束的幅度超过此容差值，后处理将进行修正

1.6 约束条件

约束条件用于引导特定帧或时间间隔内的运动。如需了解各种约束类型的详细信息，请参阅“约束概念”和“约束格式”页面。

约束面板允许您配置约束和编辑设置：

进入编辑模式：在查看器中启用前向约束（FK）姿势编辑。可编辑的关节上将显示操作控件。如果当前帧的时间轴上已有约束，任何姿势编辑都会调整该约束；否则，您需要在调整姿势后在时间轴上添加约束。
操作控件空间：编辑时在本地或全局关节空间中显示旋转操作控件。
吸附到约束：将当前帧的运动吸附到该帧的约束上。当生成的姿势与约束不完全吻合，且您希望继续编辑约束时，此功能非常有用。
重置约束：执行相反操作，将姿势从受约束的姿势吸附回最初生成的运动。
根节点 2D 选项 > 生成平滑路径：若已设置根节点路径点约束，勾选此框将把路径点转换为平滑的密集路径约束。若运动的首帧和末帧没有路径点，系统将自动添加，因为 Kimodo 仅针对完整序列路径进行过训练。
清除所有约束：从查看器和时间轴中清除所有当前约束。

1.7 保存/加载

“加载/保存”和“导出”面板可用于保存生成的结果以及加载先前生成的结果

加载/保存
- 运动：将当前运动以 NPZ 格式保存到指定路径。也可通过此面板将运动 NPZ 文件加载到查看器中。此功能可用于加载通过命令行界面 (CLI) 生成的运动。
- 约束：将当前约束以 JSON 格式保存至指定路径。约束 JSON 文件也可加载到查看器中。
- 示例：允许保存包含当前运动、约束及所有设置的新示例。这对于重新加载先前的工作非常有用。如果示例保存到演示示例目录中，则可从“示例”下拉菜单加载；否则，您可通过此菜单中的文件路径加载。
导出功能
- 截图：将当前画布保存为图像，可通过浏览器下载
- 视频：将当前运动录制为视频，可通过浏览器下载
- 运动数据：根据骨骼类型，将当前运动保存为指定格式。包括输出格式中所述的 NPZ、BVH、CSV 和 AMASS NPZ 格式。

二、命令行界面 (CLI)

CLI 的主要入口是 kimodo_gen 命令。该命令对应于位于 kimodo/scripts/generate.py 中的脚本，因此您也可以使用 python -m kimodo.scripts.generate 来实现相同的效果。

Docker 使用方法：如果您使用 Docker 部署 Kimodo，则可以在 Docker 容器内运行生成操作，将 `kimodo_gen XXX` 替换为 `docker compose run --rm demo kimodo_gen XXX`。如果您需要多次运行生成操作，建议先启动 demo 容器（例如在另一个终端或后台运行），然后在容器内执行命令，使用 `docker compose exec demo kimodo_gen XXX`。

单提示符生成：

kimodo_gen "A person walks forward." \
    --model Kimodo-SOMA-RP-v1 \
    --duration 5.0 \
    --output output

--model 命令对应用于生成的 Kimodo 模型检查点。如果未指定，默认使用 Kimodo-SOMA-RP-v1。生成的运动轨迹将使用 --output 指定的文件名，以 Kimodo 输出格式保存。若使用 G1 或 SMPL-X 模型进行生成，您还可以保存为其他输出格式，例如 MuJoCo qpos CSV 文件和 AMASS NPZ 格式。

多提示生成：

通过使用以句点分隔的多个句子（并附带相应的持续时间），可以实现基于文本提示序列的生成：

kimodo_gen "A person walks forward. A person is walking backwards." \
    --duration "5.0 4.0" \

此命令将使用 Kimodo 按顺序生成每个提示，并在第二个提示的开头添加约束条件，以确保与第一个生成的动作保持连续性。您可以通过 --num_transition_frames 参数控制用于混合连续动作的帧数。

带约束条件的单个提示：

可以通过提供一个约束条件 JSON 文件（参见《约束条件格式定义》）来对生成过程进行约束。

kimodo_gen "A person walks forward and picks something up from the ground." \
    --model Kimodo-SOMA-RP-v1 \
    --duration 5.0 \
    --constraints kimodo/assets/demo/examples/kimodo-soma-rp/03_full_body_keyframes/constraints.json

约束文件可通过交互式演示创建并保存，也可按照约束格式指南手动定义。

2.1 可视化生成的运动轨迹

使用命令行界面（CLI）生成的运动轨迹可在演示界面中进行可视化。操作方法如下：在“加载/保存” > “运动轨迹”下，输入生成的 npz 输出文件的路径，然后点击“加载运动轨迹”将其加载到查看器中。若生成时使用了约束，也可通过类似方式加载这些约束。

2.2 参数

要查看所有可用参数，请运行 kimodo_gen --help。参数包括：

prompt：所需运动的文本描述（必填）
--model：要使用的模型名称（默认：Kimodo-SOMA-RP-v1；选项为该表中的模型）
--duration: 动作持续时间（单位：秒）（默认：5.0）。若包含多个提示，请将持续时间以空格分隔的形式作为字符串传入。
--diffusion_steps: 去噪步骤数（默认：100）
--num_samples: 要生成的动作变体数量（默认：1）
--num_transition_frames：用于提示词之间过渡的帧数（默认：5）
--constraints：包含约束条件的 JSON 文件路径
--output：输出干名（默认：output）。适用于所有格式（NPZ、AMASS NPZ、CSV、BVH）。若仅有一个样本，则按格式分别生成单个文件（例如 test.npz、test.csv）。若有多个样本，则创建一个文件夹并在其中生成 test_00.npz、test_01.npz 等文件。对于仅含一个样本的 SMPLX，AMASS 数据将写入 stem_amass.npz，以免覆盖主 NPZ 文件。
--bvh：可选标志。启用时，将使用与 --output 相同的文件名后缀导出 BVH（仅限 SOMA 模型）。
--seed：用于确保结果可重现的种子值
--no-postprocess：禁用后处理（包括足部滑动清理和约束优化）
--input_folder：包含 meta.json 和可选 constraints.json 的文件夹。若设置此选项，生成设置将从 meta.json 加载。这些文件可在演示示例文件夹中找到。

2.3 Python API

如果您希望直接使用 Kimodo 的 Python API，建议从 kimodo/scripts/generate.py 脚本开始熟悉。完整的模型 API 详见 API 文档。

三、约束 JSON 格式

CLI 中的 --constraints 标志需要一个包含约束对象列表的 JSON 文件。查看演示中提供的示例是了解其格式最简单的方法。您可以在 kimodo/assets/demo/examples 中查看各种模型类型的示例。

提示：获取有效约束文件的最简单方法是在交互式演示中创建约束，然后点击“保存约束”。

3.1 总体结构

该文件是一个 JSON 数组：[{...}, {...}, ...]
每个元素都是一个对象，至少包含：
- type（字符串）
  - root2d、fullbody、left-hand、right-hand、left-foot、right-foot、end-effector
- frame_indices（整数数组）：生成片段中以 0 为起点的帧索引。

3.2 约束类型

根据类型不同，某些字段为必填项，某些为可选项。所有数值数组均为普通的嵌套 JSON 列表。在以下定义中，T 表示帧数，J 表示骨骼关节数。

3.2.1 root2d

该类型用于捕获 2D 根节点路点和 2D 根路径。它需要：

smooth_root_2d（数组形状 [T, 2]）：在给定 frame_indices 帧号处，地面平面上经过平滑处理的根节点位置 [x, z]。

以及可选参数：

global_root_heading（数组形状 [T, 2]）：在给定 frame_indices 帧号处，根节点的全局航向 [cos, sin]。

3.2.2 fullbody

此参数捕获关节位置上的全身关键帧约束。其包含：

local_joints_rot（数组形状 [T, J, 3]）：每帧每个关节的轴-角局部旋转（弧度）。受约束的关节位置将由此推导得出。
root_positions (数组形状 [T, 3])：根部（髋部）平移 [x, y, z]。
smooth_root_2d (可选；数组 [T, 2])：平滑后的根部位置 [x, z]。若省略，则默认取自 root_positions 的 [x, z] 分量。

3.2.3 左手 / 右手 / 左脚 / 右脚

捕获针对手/脚关节位置和旋转的末端执行器约束。

这些使用与 fullbody 相同的字段。但在底层实现中，它们仅会影响相应的末端执行器和髋关节。

3.3 最小示例

[
  {
    "type": "root2d",
    "frame_indices": [0, 30, 60],
    "smooth_root_2d": [[0.0, 0.0], [0.5, 0.0], [1.0, 0.1]]
  }
]

四、输出格式

命令行生成使用单一输出根目录（--output）来存储所有格式（NPZ、AMASS NPZ、CSV 和 BVH）。根据样本数量的不同，它可以写入单个文件或一组文件：

单个样本（--num_samples 1）：在输出路径下为每种格式生成一个文件（例如 --output test → test.npz, test.csv）。不创建文件夹。对于 SMPLX，AMASS 格式将写入 test_amass.npz。
多个样本：创建一个以该主文件名命名的文件夹，并为每个样本生成一个文件，文件名后缀为 _00、_01 等（例如：--output my_run → my_run/my_run_00.npz, my_run/amass_00.npz, …）。

使用 --bvh 标志可同时将 BVH（仅限 SOMA）导出到同一主文件中。

4.1 Kimodo NPZ 格式

生成的运动数据以 NPZ 文件形式存储（每个样本一个文件，例如 motion_00.npz），包含：

posed_joints：全局关节位置 [T, J, 3]
global_rot_mats：全局关节旋转矩阵 [T, J, 3, 3]
local_rot_mats：局部（相对于父关节）关节旋转矩阵 [T, J, 3, 3]
foot_contacts：脚部接触标签 [左脚跟、左脚趾、右脚跟、右脚趾] [T, 4]
smooth_root_pos：模型输出的平滑根关节表示 [T, 3]
root_positions：实际根关节（如骨盆）的（未平滑）轨迹 [T, 3]
global_root_heading：模型输出的根关节航向 [T, 2]

其中：

T：帧数
J：关节数

若生成多个样本，文件将以 _00、_01 等后缀保存。

4.2 Kimodo-G1 的 CSV 格式

在使用 Kimodo-G1 模型并通过 CLI 生成时，若指定 --output 参数，导出器会将 MuJoCo qpos 数据写入 CSV 文件。每行对应运动中的一个姿态，包含 36 个值：

根节点平移 [x, y, z]
根节点旋转四元数 [w, x, y, z]
29 个关节的 1-DoF 值（按 G1 关节顺序排列）

该 CSV 采用 MuJoCo 坐标系（z 轴向上，+x 轴向前）。若生成多个样本，文件将以 _00、_01 等后缀保存。

4.3 适用于 Kimodo-SMPLX 的 AMASS NPZ 格式

当使用 Kimodo-SMPLX-RP 模型且 --output 参数指定为 CLI 生成时，导出器将写入一个 AMASS 风格的 SMPL-X .npz 文件。键包括：

trans: 根节点平移 [T, 3]
root_orient: 根节点方向（轴-角）[T, 3]
pose_body: 身体姿态（轴-角）[T, 63]（21 个关节 × 3）
pose_hand: 手部姿态（轴-角）[T, 90]（15 个关节 × 2 只手 × 3）
pose_jaw：下颌姿态轴角 [T, 3]
pose_eye：眼部姿态轴角 [T, 6]
betas：形状系数
num_betas：形状系数数量
gender：中性
surface_model_type：smplx
mocap_frame_rate：帧率 (fps)
mocap_time_length: 动作持续时间（秒）

导出器将 Kimodo 坐标系（y 轴向上，+z 轴向前）转换为 AMASS 坐标系（z 轴向上，+y 轴向前）。如果生成了多个样本，文件将以 _00、_01 等后缀保存。

五、生成参数

在演示界面和低级 Python API 中，Kimodo 支持对动作生成进行一些高级配置。

5.1 无分类器引导

控制文本和约束引导的强度：

output = model(
    prompt="A person jumps",
    num_frames=150,
    cfg_weight=[2.0, 2.0],  # [text_weight, constraint_weight]
    cfg_type="separated",  # Options: "nocfg", "regular", "separated"
    num_denoising_steps=100,
)

当遵循提示与满足约束之间存在权衡时，这些选项会很有帮助。

CFG 选项包括：

cfg_type="nocfg": 不提供引导（速度更快，可控性较低）
cfg_type="regular": “标准”无分类器引导
- 公式：out_uncond + w * (out_text_and_constraint - out_uncond)
cfg_type="separated"：文本和约束采用独立权重
- 公式：out_uncond + w_text * (out_text - out_uncond) + w_constraint * (out_constraint - out_uncond)