Kimodo Motion Diffusion：基于文本和约束生成3D人体与机器人运动 | AI运动生成模型

kimodo-motion-diffusion by aradotso/trending-skills

432 周安装量

15 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/aradotso/trending-skills --skill kimodo-motion-diffusion

AI/机器学习内容创作自动化

🇨🇳中文介绍

Kimodo Motion Diffusion

Skill by ara.so — Daily 2026 Skills collection.

Kimodo 是一个基于 700 小时商业友好的光学动作捕捉数据训练的动力学运动扩散模型。它通过文本提示和运动学约束（全身关键帧、末端执行器位置/旋转、2D 路径、2D 路径点）控制，生成高质量的 3D 人体和人形机器人运动。

安装

# 克隆仓库
git clone https://github.com/nv-tlabs/kimodo.git
cd kimodo

# 使用 pip 安装（创建 kimodo_gen 和 kimodo_demo CLI 命令）
pip install -e .

# 或使用 Docker（推荐用于 Windows 或干净环境）
docker build -t kimodo .
docker run --gpus all -p 7860:7860 kimodo

要求：

~17GB 显存（GPU：推荐 RTX 3090/4090, A100）
Linux（通过 Docker 支持 Windows）
模型首次使用时从 Hugging Face 自动下载

可用模型

模型	骨架	数据集	用例
`Kimodo-SOMA-RP-v1`	SOMA（人体）

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

812,900 周安装

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

117,000 周安装

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

109,600 周安装

# 使用文本提示生成单个运动（默认使用 SOMA 模型）
kimodo_gen "a person walks forward at a moderate pace"

# 指定持续时间和样本数量
kimodo_gen "a person jogs in a circle" --duration 5.0 --num_samples 3

# 使用 G1 机器人模型
kimodo_gen "a robot walks forward" --model Kimodo-G1-RP-v1 --duration 4.0

# 使用 SMPL-X 模型（用于 AMASS 兼容导出）
kimodo_gen "a person waves their right hand" --model Kimodo-SMPLX-RP-v1

# 设置种子以确保可复现性
kimodo_gen "a person sits down slowly" --seed 42

# 控制扩散步数（步数越多越慢，但质量越高）
kimodo_gen "a person does a jumping jack" --diffusion_steps 50

# 默认：保存与 Web 演示兼容的 NPZ 文件
kimodo_gen "a person walks" --output ./outputs/walk.npz

# G1 机器人：保存 MuJoCo qpos CSV
kimodo_gen "robot walks forward" --model Kimodo-G1-RP-v1 --output ./outputs/walk.csv

# SMPL-X：保存 AMASS 兼容的 NPZ（stem_amass.npz）
kimodo_gen "a person waves" --model Kimodo-SMPLX-RP-v1 --output ./outputs/wave.npz
# 同时写入：./outputs/wave_amass.npz

# 禁用后处理（脚部滑动校正、约束清理）
kimodo_gen "a person walks" --no-postprocess

from kimodo.model import Kimodo

# 初始化模型（自动下载）
model = Kimodo(model_name="Kimodo-SOMA-RP-v1")

# 简单的文本到运动生成
result = model(
    prompts=["a person walks forward at a moderate pace"],
    duration=4.0,
    num_samples=1,
    seed=42,
)

# 结果包含姿态关节、旋转矩阵、脚部接触
print(result["posed_joints"].shape)       # [T, J, 3]
print(result["global_rot_mats"].shape)    # [T, J, 3, 3]
print(result["local_rot_mats"].shape)     # [T, J, 3, 3]
print(result["foot_contacts"].shape)      # [T, 4]
print(result["root_positions"].shape)     # [T, 3]

from kimodo.model import Kimodo
import numpy as np

model = Kimodo(model_name="Kimodo-SOMA-RP-v1")

# 多提示，带分类器自由引导控制
result = model(
    prompts=["a person stands", "a person walks forward", "a person sits"],
    duration=9.0,
    num_samples=3,
    diffusion_steps=50,
    guidance_scale=7.5,           # 分类器自由引导权重
    seed=0,
)

# 访问每个样本的结果
for i in range(3):
    joints = result["posed_joints"][i]   # [T, J, 3]
    print(f"Sample {i}: {joints.shape}")

from kimodo.model import Kimodo
from kimodo.constraints import ConstraintSet, FullBodyKeyframe, EndEffectorConstraint
import numpy as np

model = Kimodo(model_name="Kimodo-SOMA-RP-v1")

# 创建约束集
constraints = ConstraintSet()

# 在第 30 帧（30fps 下为 1 秒）添加全身关键帧
# keyframe_pose: [J, 3] 关节位置
keyframe_pose = np.zeros((model.num_joints, 3))  # 替换为实际姿态
constraints.add_full_body_keyframe(frame=30, joint_positions=keyframe_pose)

# 为右手添加末端执行器约束
constraints.add_end_effector(
    joint_name="right_hand",
    frame_start=45,
    frame_end=60,
    position=np.array([0.5, 1.2, 0.3]),   # [x, y, z] 单位：米
    rotation=None,                           # 可选的旋转矩阵 [3,3]
)

# 为根路径添加 2D 路径点
constraints.add_root_waypoints(
    waypoints=np.array([[0, 0], [1, 0], [1, 1], [0, 1]]),  # [N, 2] 单位：米
)

# 使用约束生成
result = model(
    prompts=["a person walks in a square"],
    duration=6.0,
    constraints=constraints,
    num_samples=2,
)

from kimodo.model import Kimodo
from kimodo.constraints import ConstraintSet
import json

model = Kimodo(model_name="Kimodo-SOMA-RP-v1")

# 加载从 Web 演示保存的约束
with open("constraints.json") as f:
    constraint_data = json.load(f)

constraints = ConstraintSet.from_dict(constraint_data)

result = model(
    prompts=["a person performs a choreographed sequence"],
    duration=8.0,
    constraints=constraints,
)

import numpy as np

# 保存结果
result = model(prompts=["a person walks"], duration=4.0)
np.savez("walk_motion.npz", **result)

# 加载并检查保存的运动
data = np.load("walk_motion.npz")
posed_joints = data["posed_joints"]       # [T, J, 3] 全局关节位置
global_rot_mats = data["global_rot_mats"] # [T, J, 3, 3]
local_rot_mats = data["local_rot_mats"]   # [T, J, 3, 3]
foot_contacts = data["foot_contacts"]     # [T, 4] [左后跟, 左前脚掌, 右后跟, 右前脚掌]
root_positions = data["root_positions"]   # [T, 3] 实际根关节轨迹
smooth_root_pos = data["smooth_root_pos"] # [T, 3] 模型平滑后的根位置
global_root_heading = data["global_root_heading"]  # [T, 2] 朝向方向

# 生成 G1 运动并保存为 MuJoCo qpos CSV
kimodo_gen "a robot walks forward and waves" \
  --model Kimodo-G1-RP-v1 \
  --output ./robot_walk.csv \
  --duration 5.0

# 在 MuJoCo 中可视化（编辑脚本以指向你的 CSV）
python -m kimodo.scripts.mujoco_load



# mujoco_load.py 自定义模式
import mujoco
import numpy as np

# 在脚本中编辑这些路径
CSV_PATH = "./robot_walk.csv"
MJCF_PATH = "./assets/g1/g1.xml"  # G1 MuJoCo 模型路径

# 加载 qpos 数据
qpos_data = np.loadtxt(CSV_PATH, delimiter=",")

# 标准 MuJoCo 播放循环
model = mujoco.MjModel.from_xml_path(MJCF_PATH)
data = mujoco.MjData(model)
with mujoco.viewer.launch_passive(model, data) as viewer:
    for frame_qpos in qpos_data:
        data.qpos[:] = frame_qpos
        mujoco.mj_forward(model, data)
        viewer.sync()

键	形状	描述
`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]`	朝向方向（2D 单位向量）

from kimodo.model import Kimodo
import numpy as np
from pathlib import Path

model = Kimodo(model_name="Kimodo-SOMA-RP-v1")
output_dir = Path("./batch_outputs")
output_dir.mkdir(exist_ok=True)

prompts = [
    "a person walks forward",
    "a person runs",
    "a person jumps in place",
    "a person sits down",
    "a person picks up an object from the floor",
]

for i, prompt in enumerate(prompts):
    result = model(
        prompts=[prompt],
        duration=4.0,
        num_samples=1,
        seed=i,
    )
    out_path = output_dir / f"motion_{i:03d}.npz"
    np.savez(str(out_path), **result)
    print(f"Saved: {out_path}")

提示要具体："a person walks forward at a moderate pace" > "walking"
对于复杂运动，使用交互式演示添加关键帧约束
增加 --diffusion_steps（默认约 20-30，尝试 50 以获得更高质量）
生成多个样本（--num_samples 5）并选择最佳结果
避免提示包含极快或物理上不可能的动作
模型以 30fps 运行；非常短的持续时间（<1 秒）可能导致结果不佳

🇺🇸English

Kimodo Motion Diffusion

Skill by ara.so — Daily 2026 Skills collection.

Kimodo is a kinematic motion diffusion model trained on 700 hours of commercially-friendly optical mocap data. It generates high-quality 3D human and humanoid robot motions controlled through text prompts and kinematic constraints (full-body keyframes, end-effector positions/rotations, 2D paths, 2D waypoints).

Installation

# Clone the repository
git clone https://github.com/nv-tlabs/kimodo.git
cd kimodo

# Install with pip (creates kimodo_gen and kimodo_demo CLI commands)
pip install -e .

# Or with Docker (recommended for Windows or clean environments)
docker build -t kimodo .
docker run --gpus all -p 7860:7860 kimodo

Requirements:

~17GB VRAM (GPU: RTX 3090/4090, A100 recommended)
Linux (Windows supported via Docker)
Models download automatically on first use from Hugging Face

Available Models

Model	Skeleton	Dataset	Use Case
`Kimodo-SOMA-RP-v1`	SOMA (human)	Bones Rigplay 1 (700h)	General human motion
`Kimodo-G1-RP-v1`	Unitree G1 (robot)	Bones Rigplay 1 (700h)	Humanoid robot motion
`Kimodo-SOMA-SEED-v1`	SOMA	BONES-SEED (288h)	Benchmarking
`Kimodo-G1-SEED-v1`	Unitree G1	BONES-SEED (288h)	Benchmarking
`Kimodo-SMPLX-RP-v1`	SMPL-X	Bones Rigplay 1 (700h)	Retargeting/AMASS export

CLI: `kimodo_gen`

Basic Text-to-Motion

# Generate a single motion with a text prompt (uses SOMA model by default)
kimodo_gen "a person walks forward at a moderate pace"

# Specify duration and number of samples
kimodo_gen "a person jogs in a circle" --duration 5.0 --num_samples 3

# Use the G1 robot model
kimodo_gen "a robot walks forward" --model Kimodo-G1-RP-v1 --duration 4.0

# Use SMPL-X model (for AMASS-compatible export)
kimodo_gen "a person waves their right hand" --model Kimodo-SMPLX-RP-v1

# Set a seed for reproducibility
kimodo_gen "a person sits down slowly" --seed 42

# Control diffusion steps (more = slower but higher quality)
kimodo_gen "a person does a jumping jack" --diffusion_steps 50

Output Formats

# Default: saves NPZ file compatible with web demo
kimodo_gen "a person walks" --output ./outputs/walk.npz

# G1 robot: save MuJoCo qpos CSV
kimodo_gen "robot walks forward" --model Kimodo-G1-RP-v1 --output ./outputs/walk.csv

# SMPL-X: saves AMASS-compatible NPZ (stem_amass.npz)
kimodo_gen "a person waves" --model Kimodo-SMPLX-RP-v1 --output ./outputs/wave.npz
# Also writes: ./outputs/wave_amass.npz

# Disable post-processing (foot skate correction, constraint cleanup)
kimodo_gen "a person walks" --no-postprocess

Multi-Prompt Sequences

# Sequence of text prompts for transitions
kimodo_gen "a person stands still" "a person walks forward" "a person stops and turns"

# With timing control per segment
kimodo_gen "a person jogs" "a person slows to a walk" "a person stops" \
  --duration 8.0 --num_samples 2

Constraint-Based Generation

# Load constraints saved from the interactive demo
kimodo_gen "a person walks to a table and picks something up" \
  --constraints ./my_constraints.json

# Combine text and constraints
kimodo_gen "a person performs a complex motion" \
  --constraints ./keyframe_constraints.json \
  --model Kimodo-SOMA-RP-v1 \
  --num_samples 5

Interactive Demo

# Launch the web-based demo at http://127.0.0.1:7860
kimodo_demo

# Access remotely (server setup)
kimodo_demo --server-name 0.0.0.0 --server-port 7860

The demo provides:

Timeline editor for text prompts and constraints
Full-body keyframe constraints
2D root path/waypoint editor
End-effector position/rotation control
Real-time 3D visualization with skeleton and skinned mesh
Export of constraints as JSON and motions as NPZ

Low-Level Python API

Basic Model Inference

from kimodo.model import Kimodo

# Initialize model (downloads automatically)
model = Kimodo(model_name="Kimodo-SOMA-RP-v1")

# Simple text-to-motion generation
result = model(
    prompts=["a person walks forward at a moderate pace"],
    duration=4.0,
    num_samples=1,
    seed=42,
)

# Result contains posed joints, rotation matrices, foot contacts
print(result["posed_joints"].shape)       # [T, J, 3]
print(result["global_rot_mats"].shape)    # [T, J, 3, 3]
print(result["local_rot_mats"].shape)     # [T, J, 3, 3]
print(result["foot_contacts"].shape)      # [T, 4]
print(result["root_positions"].shape)     # [T, 3]

Advanced API with Guidance and Constraints

from kimodo.model import Kimodo
import numpy as np

model = Kimodo(model_name="Kimodo-SOMA-RP-v1")

# Multi-prompt with classifier-free guidance control
result = model(
    prompts=["a person stands", "a person walks forward", "a person sits"],
    duration=9.0,
    num_samples=3,
    diffusion_steps=50,
    guidance_scale=7.5,           # classifier-free guidance weight
    seed=0,
)

# Access per-sample results
for i in range(3):
    joints = result["posed_joints"][i]   # [T, J, 3]
    print(f"Sample {i}: {joints.shape}")

Working with Constraints Programmatically

from kimodo.model import Kimodo
from kimodo.constraints import ConstraintSet, FullBodyKeyframe, EndEffectorConstraint
import numpy as np

model = Kimodo(model_name="Kimodo-SOMA-RP-v1")

# Create constraint set
constraints = ConstraintSet()

# Add a full-body keyframe at frame 30 (1 second at 30fps)
# keyframe_pose: [J, 3] joint positions
keyframe_pose = np.zeros((model.num_joints, 3))  # replace with actual pose
constraints.add_full_body_keyframe(frame=30, joint_positions=keyframe_pose)

# Add end-effector constraints for right hand
constraints.add_end_effector(
    joint_name="right_hand",
    frame_start=45,
    frame_end=60,
    position=np.array([0.5, 1.2, 0.3]),   # [x, y, z] in meters
    rotation=None,                           # optional rotation matrix [3,3]
)

# Add 2D waypoints for root path
constraints.add_root_waypoints(
    waypoints=np.array([[0, 0], [1, 0], [1, 1], [0, 1]]),  # [N, 2] in meters
)

# Generate with constraints
result = model(
    prompts=["a person walks in a square"],
    duration=6.0,
    constraints=constraints,
    num_samples=2,
)

Loading and Using Saved Constraints

from kimodo.model import Kimodo
from kimodo.constraints import ConstraintSet
import json

model = Kimodo(model_name="Kimodo-SOMA-RP-v1")

# Load constraints saved from web demo
with open("constraints.json") as f:
    constraint_data = json.load(f)

constraints = ConstraintSet.from_dict(constraint_data)

result = model(
    prompts=["a person performs a choreographed sequence"],
    duration=8.0,
    constraints=constraints,
)

Saving and Loading Generated Motions

import numpy as np

# Save result
result = model(prompts=["a person walks"], duration=4.0)
np.savez("walk_motion.npz", **result)

# Load and inspect saved motion
data = np.load("walk_motion.npz")
posed_joints = data["posed_joints"]       # [T, J, 3] global joint positions
global_rot_mats = data["global_rot_mats"] # [T, J, 3, 3]
local_rot_mats = data["local_rot_mats"]   # [T, J, 3, 3]
foot_contacts = data["foot_contacts"]     # [T, 4] [L-heel, L-toe, R-heel, R-toe]
root_positions = data["root_positions"]   # [T, 3] actual root joint trajectory
smooth_root_pos = data["smooth_root_pos"] # [T, 3] smoothed root from model
global_root_heading = data["global_root_heading"]  # [T, 2] heading direction

Robotics Integration

MuJoCo Visualization (G1 Robot)

# Generate G1 motion and save as MuJoCo qpos CSV
kimodo_gen "a robot walks forward and waves" \
  --model Kimodo-G1-RP-v1 \
  --output ./robot_walk.csv \
  --duration 5.0

# Visualize in MuJoCo (edit script to point to your CSV)
python -m kimodo.scripts.mujoco_load



# mujoco_load.py customization pattern
import mujoco
import numpy as np

# Edit these paths in the script
CSV_PATH = "./robot_walk.csv"
MJCF_PATH = "./assets/g1/g1.xml"  # path to G1 MuJoCo model

# Load qpos data
qpos_data = np.loadtxt(CSV_PATH, delimiter=",")

# Standard MuJoCo playback loop
model = mujoco.MjModel.from_xml_path(MJCF_PATH)
data = mujoco.MjData(model)
with mujoco.viewer.launch_passive(model, data) as viewer:
    for frame_qpos in qpos_data:
        data.qpos[:] = frame_qpos
        mujoco.mj_forward(model, data)
        viewer.sync()

ProtoMotions Integration

# Generate motion with Kimodo
kimodo_gen "a person runs and jumps" --model Kimodo-SOMA-RP-v1 \
  --output ./run_jump.npz --duration 5.0

# Then follow ProtoMotions docs to import:
# https://github.com/NVlabs/ProtoMotions#motion-authoring-with-kimodo

GMR Retargeting (SMPL-X to Other Robots)

# Generate SMPL-X motion (saves stem_amass.npz automatically)
kimodo_gen "a person performs a cartwheel" \
  --model Kimodo-SMPLX-RP-v1 \
  --output ./cartwheel.npz

# Use cartwheel_amass.npz with GMR for retargeting
# https://github.com/YanjieZe/GMR

NPZ Output Format Reference

Key	Shape	Description
`posed_joints`	`[T, J, 3]`	Global joint positions in meters
`global_rot_mats`	`[T, J, 3, 3]`	Global joint rotation matrices
`local_rot_mats`	`[T, J, 3, 3]`	Parent-relative joint rotation matrices
`foot_contacts`

T = number of frames (30fps), J = number of joints (skeleton-dependent)

Scripts Reference

# Direct script execution (alternative to CLI)
python scripts/generate.py "a person walks" --duration 4.0

# MuJoCo visualization for G1 outputs
python -m kimodo.scripts.mujoco_load

# All kimodo_gen flags
kimodo_gen --help

Common Patterns

Batch Generation Pipeline

from kimodo.model import Kimodo
import numpy as np
from pathlib import Path

model = Kimodo(model_name="Kimodo-SOMA-RP-v1")
output_dir = Path("./batch_outputs")
output_dir.mkdir(exist_ok=True)

prompts = [
    "a person walks forward",
    "a person runs",
    "a person jumps in place",
    "a person sits down",
    "a person picks up an object from the floor",
]

for i, prompt in enumerate(prompts):
    result = model(
        prompts=[prompt],
        duration=4.0,
        num_samples=1,
        seed=i,
    )
    out_path = output_dir / f"motion_{i:03d}.npz"
    np.savez(str(out_path), **result)
    print(f"Saved: {out_path}")

Comparing Model Variants

from kimodo.model import Kimodo
import numpy as np

prompt = "a person walks forward"
models = ["Kimodo-SOMA-RP-v1", "Kimodo-SOMA-SEED-v1"]

results = {}
for model_name in models:
    model = Kimodo(model_name=model_name)
    results[model_name] = model(
        prompts=[prompt],
        duration=4.0,
        seed=0,
    )
    print(f"{model_name}: joints shape = {results[model_name]['posed_joints'].shape}")

Troubleshooting

Out of VRAM (~17GB required):

# Check available VRAM
nvidia-smi

# Use fewer samples to reduce peak VRAM
kimodo_gen "a person walks" --num_samples 1

# Reduce diffusion steps to speed up (less quality)
kimodo_gen "a person walks" --diffusion_steps 20

Model download issues:

# Models download from Hugging Face automatically
# If behind a proxy, set:
export HF_ENDPOINT=https://huggingface.co
export HUGGINGFACE_HUB_VERBOSITY=debug

# Or manually specify cache directory
export HF_HOME=/path/to/your/cache

Motion quality issues:

Be specific in prompts: "a person walks forward at a moderate pace" > "walking"
For complex motions, use the interactive demo to add keyframe constraints
Increase --diffusion_steps (default ~20-30, try 50 for higher quality)
Generate multiple samples (--num_samples 5) and select the best
Avoid prompts with extremely fast or physically impossible actions
The model operates at 30fps; very short durations (<1s) may yield poor results

Foot skating artifacts:

# Post-processing is enabled by default; only disable for debugging
kimodo_gen "a person walks" # post-processing ON (default)
kimodo_gen "a person walks" --no-postprocess  # post-processing OFF

Interactive demo not loading:

# Ensure port 7860 is available
lsof -i :7860

# Launch on a different port
kimodo_demo --server-port 7861

# For remote server access
kimodo_demo --server-name 0.0.0.0 --server-port 7860
# Then use SSH port forwarding: ssh -L 7860:localhost:7860 user@server

Weekly Installs

219

Repository

aradotso/trending-skills

GitHub Stars

First Seen

5 days ago

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

gemini-cli218

github-copilot218

codex218

amp218

cline218

warp218

Kimodo Motion Diffusion：基于文本和约束生成3D人体与机器人运动 | AI运动生成模型

🇨🇳中文介绍

Kimodo Motion Diffusion

安装

可用模型

相关 Skills

CLI：kimodo_gen

基础文本到运动生成

输出格式

多提示序列

基于约束的生成

交互式演示

底层 Python API

基础模型推理

带有引导和约束的高级 API

以编程方式处理约束

加载和使用保存的约束

保存和加载生成的运动

机器人集成

MuJoCo 可视化（G1 机器人）

ProtoMotions 集成

GMR 重定向（SMPL-X 到其他机器人）

NPZ 输出格式参考

脚本参考

常见模式

批量生成流水线

比较模型变体

故障排除

🇺🇸English

Kimodo Motion Diffusion

Installation

Available Models

CLI: kimodo_gen

Basic Text-to-Motion

Output Formats

Multi-Prompt Sequences

Constraint-Based Generation

Interactive Demo

Low-Level Python API

Basic Model Inference

Advanced API with Guidance and Constraints

Working with Constraints Programmatically

Loading and Using Saved Constraints

Saving and Loading Generated Motions

Robotics Integration

MuJoCo Visualization (G1 Robot)

ProtoMotions Integration

GMR Retargeting (SMPL-X to Other Robots)

NPZ Output Format Reference

Scripts Reference

Common Patterns

Batch Generation Pipeline

Comparing Model Variants

Troubleshooting

最新 Skills

CLI：`kimodo_gen`

CLI: `kimodo_gen`