ccrpRepo/robot_retargeter
ccrpRepo/robot_retargeter has 388 GitHub stars and 36 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-21 10:27 UTC. Last push 2026-06-29.
实测星标增长
- 24小时
- 0
- 7天
- 正在收集历史
- 15天
- 正在收集历史
- 1个月
- 正在收集历史
各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。
关于
Motion retargeting pipeline from SMPL-X / source robots to target humanoid robots.
开发工具README_zh.md
原文robot_retargeter
中文 | English
将人体动作(SMPL-X)或源机器人动作重定向到目标人形机器人,并支持多机器人并排可视化的工具集。
简介
本项目提供一条完整的动作重定向流水线,主要包含三步:
- 回放 / 提取关键点:从 SMPL-X 动作(
.npz)或源机器人动作(.csv)中提取骨骼关键点。 - 重定向(Retarget):基于逆运动学(mink + MuJoCo)把关键点映射到目标机器人模型上,生成机器人动作。
- 可视化:将一个或多个目标机器人的重定向结果并排播放查看。
目录结构概览:
| 目录 | 内容 |
|---|---|
asset/ |
机器人模型(URDF/MJCF/mesh)、SMPL-X 模型、骨架 |
config/ |
机器人与骨架的重定向配置(YAML) |
dataset/ |
输入动作数据(SMPL-X .npz / LAFAN1 .csv 等) |
output_data/ |
输出的关键点与机器人动作 |
scripts/ |
Python 流水线脚本 |
bash/ |
一键运行的流水线脚本 |
安装
克隆仓库
# 使用普通 Git 克隆
git clone https://github.com/ccrpRepo/robot_retargeter.git
cd robot_retargeter
Python 环境
需要 Python ≥ 3.10(开发环境为 Python 3.11)。建议使用虚拟环境(conda / venv)。
# 1) 创建并激活环境(以 conda 为例)
conda create -n robot_retargeter python=3.11 -y
conda activate robot_retargeter
# 2) 安装依赖
pip install -e .
# 或
pip install -r requirements.txt
SMPL-X 模型(需单独下载)
SMPL-X 模型文件不包含在本仓库中(受其自身许可协议约束)。若要使用 SMPL-X 流水线(retarget_from_smplx.sh),请自行下载:
在官网注册并下载:smplx model download (下载 "SMPL-X" 模型,
.npz格式)。将文件放到
asset/smplx/目录下,结构如下:asset/smplx/ SMPLX_NEUTRAL.npz SMPLX_MALE.npz SMPLX_FEMALE.npz
动作数据集(AMASS)
dataset/ACCAD/ 中提供的是 AMASS 数据集里 ACCAD 子集的少量开源示例动作(SMPL-X .npz 格式),仅用于快速体验流水线。若需要更多动作数据,请自行从 AMASS 官网下载:
- AMASS 官网(注册后下载):https://amass.is.tue.mpg.de/
下载后解压,将 .npz 动作文件放到 dataset/ 下任意目录(例如 dataset/ACCAD/),再通过 SMPL_MOTION_FILE 指向对应文件即可。
运行
bash/ 目录提供了两个一键流水线脚本,会自动完成「关键映射点生成 → 重定向 → 可视化」三步。脚本默认使用当前激活环境中的 python,也可用 PYTHON_BIN 指定解释器。
1) 从 SMPL-X 动作重定向
./bash/retarget_from_smplx.sh
可通过环境变量自定义参数:
| 变量 | 默认值 | 说明 |
|---|---|---|
SMPL_MOTION_FILE |
dataset/ACCAD/Form_1_stageii.npz |
输入的 SMPL-X 动作文件 |
VIS_ROBOTS |
g1 h2 t800 r1 |
目标机器人列表(空格分隔,支持多个) |
KEYPOINTS_NAME |
由动作文件名自动推导 | 关键点 / 输出动作名称 |
SOURCE_FPS |
120 |
源动作帧率 |
RENDER_FPS |
30 |
可视化渲染帧率 |
PYTHON_BIN |
自动检测 | 指定 Python 解释器 |
示例(自定义机器人与动作文件):
VIS_ROBOTS="g1 jaka_pi h2 t800" \
SMPL_MOTION_FILE="dataset/ACCAD/Form_1_stageii.npz" \
./bash/retarget_from_smplx.sh
2) 从源机器人动作重定向

./bash/retarget_from_robot.sh
| 变量 | 默认值 | 说明 |
|---|---|---|
ROBOT_MOTION_FILE |
dataset/lafan1_g1/dance1_subject2.csv |
源机器人动作文件 |
ORIGIN_ROBOT |
g1 |
源机器人名称(提供骨架配置) |
VIS_ROBOTS |
h2 r1 |
目标机器人列表(空格分隔,支持多个) |
SOURCE_FPS |
30 |
源动作帧率 |
RENDER_FPS |
30 |
可视化渲染帧率 |
PYTHON_BIN |
自动检测 | 指定 Python 解释器 |
示例:
VIS_ROBOTS="jaka_pi h2 t800 pnd_adam" \
ROBOT_MOTION_FILE="dataset/bones_g1/grab_walk_ff_180_001__A550_M.csv" \
ORIGIN_ROBOT="g1" \
SOURCE_FPS=120 \
RENDER_FPS=30 \
./bash/retarget_from_robot.sh
运行结束后,重定向得到的机器人动作会保存在 output_data/robot_motion/ 下。
使用 Bones Seed G1 数据集
Bones Studio 发布了以 G1 机器人为载体的 Seed 动作数据集,其原始格式(根节点使用欧拉角/厘米单位,关节值为角度)与本项目所需的 LAFAN1 格式(根节点使用四元数/米单位,关节值为弧度)不同,需要先用 scripts/convert_bones_to_lafan1.py 进行转换。
数据下载
# 从 Hugging Face 下载 G1 Seed 数据集
wget https://huggingface.co/datasets/bones-studio/seed/blob/main/g1.tar.gz -O g1.tar.gz
tar -xzf g1.tar.gz -C dataset/bones_g1_origin/
格式转换
convert_bones_to_lafan1.py 将原始 G1 CSV 转换为 LAFAN1 兼容格式:
| 参数 | 默认值 | 说明 |
|---|---|---|
--input-root |
dataset/bones_g1_origin |
原始 CSV 所在目录(批量转换) |
--output-root |
dataset/bones_g1 |
转换后 CSV 输出目录 |
--input-csv |
无 | 仅转换单个 CSV 文件 |
--root-scale |
0.01 |
根节点位移缩放系数(cm→m) |
# 批量转换 dataset/bones_g1_origin/ 下所有 CSV 文件
python scripts/convert_bones_to_lafan1.py
# 仅转换单个文件
python scripts/convert_bones_to_lafan1.py \
--input-csv dataset/bones_g1_origin/grab_walk_ff_180_001__A550_M.csv
# 自定义输入 / 输出目录
python scripts/convert_bones_to_lafan1.py \
--input-root dataset/bones_g1_origin \
--output-root dataset/bones_g1
转换完成后,即可将生成的 CSV 作为源动作传入重定向流水线:
VIS_ROBOTS="jaka_pi h2 t800 pnd_adam" \
ROBOT_MOTION_FILE="dataset/bones_g1/grab_walk_ff_180_001__A550_M.csv" \
ORIGIN_ROBOT="g1" \
SOURCE_FPS=120 \
RENDER_FPS=30 \
./bash/retarget_from_robot.sh
核心机制
1)骨架匹配
source:smplx模型 ---> agibot_x2模型

由于源骨架(SMPL-X)与目标机器人的肢体长度不同,需要按「每段连杆(link)长度比」对源关键点逐段缩放,使其匹配目标机器人的尺寸,同时保留每段连杆原有的朝向。
骨架缩放伪代码(对应 scripts/smpl_replay.py 中的
compute_robot_link_lengths / compute_link_geometry_from_positions /
compute_link_scale_factors / apply_link_scales_to_positions):
# 输入:
# robot_mjcf 目标机器人的 MJCF 模型
# robot_links 连杆定义 {link_name: (parent_body, child_body)}
# skeleton_positions 源骨架关键点序列, 形状 [T, K, 3]
# skeleton_links 源骨架连杆定义 {link_name: (parent_body, child_body)}
# 步骤 1: 计算目标机器人每段连杆长度(零位姿、世界坐标下的两端距离)
mj_forward(robot_mjcf) # 前向运动学得到各 body 世界坐标
for link_name, (parent, child) in robot_links:
robot_len[link_name] = || xpos[child] - xpos[parent] ||
# 步骤 2: 计算源骨架每段连杆的方向向量与长度(逐帧)
for link_name, (parent, child) in skeleton_links:
link_vec[link_name] = skeleton_positions[:, child] - skeleton_positions[:, parent] # [T, 3]
skeleton_len[link_name] = norm(link_vec[link_name], axis=-1) # [T]
# 步骤 3: 计算每段连杆的缩放系数(逐帧,目标长度 / 源长度)
for link_name in skeleton_links:
scale[link_name] = robot_len[link_name] / skeleton_len[link_name] # [T]
# 步骤 4: 按连杆拓扑从父到子重建关键点位置
# 保持源方向向量不变,仅按 scale 拉伸长度
scaled_pos = copy(skeleton_positions)
for link_name, (parent, child) in skeleton_links: # 按 父 -> 子 顺序遍历
scaled_pos[:, child] = scaled_pos[:, parent] + scale[link_name][:, None] * link_vec[link_name]
# 输出:scaled_pos —— 已匹配目标机器人尺寸的关键点
用数学符号表达,对第 $i$ 段连杆(父关键点 $p$、子关键点 $c$)在第 $t$ 帧:
$$ s_i^{(t)} = \frac{L_i^{\text{robot}}}{\lVert \mathbf{x}_c^{(t)} - \mathbf{x}_p^{(t)} \rVert}, \qquad \hat{\mathbf{x}}_c^{(t)} = \hat{\mathbf{x}}_p^{(t)} + s_i^{(t)} \left( \mathbf{x}_c^{(t)} - \mathbf{x}_p^{(t)} \right) $$
其中 $L_i^{\text{robot}}$ 是机器人该连杆的固定长度,$\mathbf{x}$ 为原始关键点,$\hat{\mathbf{x}}$ 为缩放后的关键点。
说明:
- 缩放沿「父关键点 → 子关键点」逐段进行,子关键点位置由父关键点加上「原方向向量 × 缩放系数」得到,因此只改变长度、不改变朝向。
- 缩放系数是逐帧计算的(
link_scale_is_static = False),可适应源骨架长度随姿态的细微变化。- 此外,整体的根节点(root)平移还会按腿长比例缩放(
compute_leg_displacement_scale/scale_keypoint_frame_displacements),使步幅与机器人腿长匹配。
Root 缩放
为使不同体型(尤其腿长差异较大)的源/目标模型在运动幅度上保持一致, 会根据「目标腿长 / 源腿长」计算位移缩放系数,并对 root 在 $x,y,z$ 三个方向的帧间位移统一缩放。
- 腿长定义:大腿长度 + 小腿长度(左右腿取平均)。
- 缩放目标:主要调节整体步幅与位移尺度,使动作在目标机器人上更自然。
适配注意事项(斜胯构型)
在当前骨架定义中,left_shoulder - neck - right_shoulder 与
left_hip - hips_mean - right_hip 默认近似共线(水平)。
对于类似众擎 t800 的斜胯构型,建议在髋部左右两侧额外添加两个映射点,
并与对应 hip_roll_link 建立 fixed 连接,以更稳定地表达骨盆倾斜与左右髋差异。

2)膝关节弯曲
为提升下肢构型的可达性与力学表现,流程中会对膝部做两段骨(hip-knee-foot)几何重建。
该过程由 knee_angle_offset_degrees 控制弯曲强度:
- 文档示例图使用
60.0度仅用于展示效果。 - 实际配置常用值为
15.0度。 - 在
smpl_replay.py中该偏置默认参与计算。 - 在
robot_replay.py中需显式开启enable_knee_angle_offset_degrees: true才会生效。
核心是两段骨 IK 与空间余弦定理。设:
- $a$:大腿长度(hip->knee)
- $b$:小腿长度(knee->foot)
- $d$:目标髋踝距离(hip->target_foot)
则沿髋踝方向的投影长度与垂向抬起量分别为:
$$ x = \frac{a^2 - b^2 + d^2}{2d}, \qquad h = \sqrt{\max(a^2 - x^2,, 0)} $$
重建后的膝位置可写为:
$$ \mathbf{p}{knee} = \mathbf{p}{hip} + x,\mathbf{u} + h,\mathbf{v} $$
其中 $\mathbf{u}$ 为髋到目标踝的单位方向,$\mathbf{v}$ 为在弯曲平面内的弯曲方向。 这里特别说明:在膝关节弯曲步骤中,会保持「髋关节到踝关节」向量方向(即 $\mathbf{u}$ 方向)不变, 仅调整该向量的长度(对应目标髋踝距离 $d$),再据此重建膝位置。 代码实现中会保持弯曲方向与原始屈膝偏好一致,避免膝盖反转。

3)接触检测
接触判定通常覆盖双手与双脚;其中每只脚会设置前、后两个接触检测点,以更稳定地识别支撑与离地状态。

接触状态按「低速度 + 低高度」双条件判定(见 compute_contact_sequence /
compute_robot_contact_sequence):
$$ ext{contact}(t,c)=\big(v_{t,c}\le v_{th}\big);\land;\big(z_{t,c}\le h_{th}\big) $$
其中:
- $v_{t,c}$:接触点 $c$ 在第 $t$ 帧的窗口速度(由
contact_vel_calculate_window计算) - $z_{t,c}$:接触点高度
- $v_{th}$:
contact_vel_threshold - $h_{th}$:
contact_height_threshold
该设计可同时抑制“低空高速掠过”与“高空慢速摆动”导致的误判。
4)自适应高度
在检测到接触后,系统会估计每一帧的地面高度偏移,并整体下移关键点序列(仅 $z$ 方向), 使支撑脚更稳定地贴合地面。
- 在每帧选择当前激活接触点中的最小高度作为基准高度。
- 若该帧无激活接触,则沿用上一帧高度。
- 对高度序列做一阶低通滤波(
contact_height_lpf_alpha):
$$ y_t = \alpha x_t + (1-\alpha)y_{t-1}, \qquad 0<\alpha\le1 $$
- 对所有关键点执行 $z$ 向平移:
$$ z'{t,k} = z{t,k} - y_t $$
其中,较小的 $\alpha$ 会带来更平滑但更滞后的地面跟随效果。
5)足端接触滑动抑制
在 robot_retarget.py 中,针对处于接触状态的足端(或配置的接触体)引入“接触锁定目标”:
- 将连续接触区间内的源关键点位置取均值,得到该区间的固定目标点。
- 接触为真时,IK 目标使用该固定点;接触为假时,恢复跟随原始目标。
- 该约束以额外
FrameTask形式加入优化,权重由contact_pos_fixed_factor控制。
这样可以显著减小支撑相内的足端漂移(foot sliding),同时在摆动相保持动作自由度。