TienKung-Lab 仓库详细介绍

https://github.com/Open-X-Humanoid/TienKung-Lab

TienKung-Lab 是一套面向全尺寸人形机器人（TienKung 天工机器人）的基于强化学习（RL）的运动控制框架，核心围绕机器人行走、奔跑等 locomotion（移动）行为的研发，具备仿真、跨仿真器迁移、真实机器人落地等能力，整体基于 NVIDIA IsaacLab 构建，模块化设计且可扩展。

一、核心背景与定位

1. 目标：为 TienKung 人形机器人实现自然、稳定、高效的行走 / 奔跑行为，支持感知控制、仿真到真实机器人的迁移（Sim2Real）。

2. 技术底座：

   1. 核心依赖：IsaacSim 4.5.0（NVIDIA 机器人仿真引擎）、IsaacLab 2.1.0（基于 IsaacSim 的机器人学习框架）、RSL-RL 2.3.1（leggedrobotics 开源的强化学习库）。

   2. 适配环境：Python 3.10、Linux（Ubuntu 22.04）。

3. 核心特性：

   1. 融合 AMP（Adaptive Motion Policies）风格奖励 + 周期性步态奖励，优化运动的自然性与稳定性；

   2. 支持 Sim2Sim（IsaacSim → MuJoCo）迁移，验证算法泛化性；

   3. 集成基于射线投射（ray-casting）的传感器，增强环境感知与避障能力；

   4. 模块化架构，易定制 / 扩展；

   5. 已在真实 TienKung 机器人上完成验证。

二、仓库结构解析

仓库采用分层、模块化的目录设计，核心目录 / 文件功能如下：

|-------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 目录 / 文件 | 核心作用 |
| .flake8/.pre-commit-config.yaml | 代码规范配置（flake8 代码检查、pre-commit 钩子，保证代码风格统一） |
| Exported_policy/ | 存放导出的训练好的策略模型（如 walk.pt 是行走策略权重） |
| rsl_rl/ | 集成 RSL-RL 强化学习库（单独安装，提供 RL 训练核心逻辑） |
| legged_lab/ | 仓库核心业务代码，包含机器人环境、传感器、地形、脚本等： - assets/：机器人 / 环境资产（模型、配置等）； - envs/：TienKung 机器人仿真环境定义（含数据集）； - mdp/：马尔可夫决策过程相关（任务、奖励函数定义）； - scripts/：核心运行脚本（训练、数据转换、动画播放等）； - sensors/：传感器相关代码（射线投射等感知模块）； - terrains/：仿真地形定义（测试机器人在不同地形的运动）； - utils/：工具函数（数据处理、配置解析等）； - __init__.py：包入口，标记 Python 模块 |
| docs/ | 文档资源（图片、GIF、说明文档），包含运动效果演示、架构说明等 |
| setup.py | Python 包安装配置，支持 pip install -e . 以可编辑模式安装 |
| README.md | 仓库核心说明（安装、使用、TODO、功能概览） |

三、核心功能模块 & 完整程序链路逐层拆解

TienKung-Lab 所有功能遵循「数据预处理→仿真训练→策略导出→跨仿真验证→实机部署」的完整程序闭环，以下结合对应源码文件、执行脚本、底层逻辑，对四大核心模块进行精细化拆解，清晰梳理每一步程序运行机制与代码分工。

1. 运动重定向模块（程序前置预处理链路）

该模块是 RL 训练的前置核心程序，解决通用人形运动数据无法适配天工机器人硬件结构的问题，通过专属脚本完成数据格式转换、适配、导出，为后续训练提供合法专家运动数据，无此步骤则无法开展AMP强化学习训练。

1.1 核心程序文件与分工

• scripts/smplx_to_robot.py：一级转换脚本，核心功能为解析通用SMPLX格式运动数据（AMASS/OMOMO数据集），通过GMR高斯混合回归算法，将标准人形运动姿态换算为天工机器人专属的关节角度、机身位姿数据，输出.pkl格式中间数据文件。

• legged_lab/scripts/gmr_data_conversion.py：二级转换脚本，读取.pkl中间文件，批量解析数据格式，输出仿真环境可识别的.txt标准化运动文件，用于可视化预览。

• legged_lab/scripts/play_amp_animation.py：数据校验&导出脚本，加载标准化运动数据，完成仿真可视化校验，同时导出AMP训练专用的专家数据集，存入motion_amp_expert目录，供训练脚本调用。

1.2 完整程序执行流程

原始SMPLX运动数据 → 执行smplx_to_robot.py生成机器人适配.pkl数据 → 执行gmr_data_conversion.py生成可视化txt数据 → 执行play_amp_animation.py校验运动效果 → 导出AMP专家训练数据集 → 完成前置预处理。

1.3 程序核心逻辑

通过算法修正通用人形与天工机器人的关节自由度、机身尺寸差异，过滤无效运动帧、修正姿态偏差，输出时序稳定、适配硬件的运动序列，保证后续RL训练的参考数据精准有效。

将通用人形运动数据（如 AMASS、OMOMO 等 SMPLX 格式）适配到 TienKung 机器人，是 RL 训练前的 "运动数据预处理" 核心步骤，流程如下：

• 依赖：GMR（Gaussian Mixture Regression，高斯混合回归）工具库，仅支持 SMPLX 类型运动数据；

• 核心目的：将通用人形运动转换为 TienKung 机器人可执行的关节 / 根节点数据，用于 RL 训练的 "专家参考数据" 或运动可视化。

2. AMP强化学习训练模块（核心仿真训练链路）

该模块是仓库核心程序主体，基于IsaacLab仿真引擎+RSL-RL算法库，加载预处理后的专家运动数据，通过双奖励机制迭代训练机器人行走、奔跑策略，是实现机器人自主运动的核心环节。

2.1 核心程序文件与分工

• legged_lab/scripts/train.py：训练主入口程序，支持配置并行环境数、日志类型、训练任务（walk/run），调用底层环境与奖励函数，启动仿真训练流程。

• legged_lab/envs/：仿真环境定义程序，定义天工机器人仿真模型、地形环境、观测空间、动作空间，模拟真实运动物理约束。

• legged_lab/mdp/：决策核心程序，自定义AMP匹配奖励、周期性步态奖励、姿态稳定奖励，是训练收敛、运动自然的核心逻辑载体。

• rsl_rl/：底层算法依赖程序，提供PPO强化学习核心算法、迭代更新机制、策略梯度计算，支撑整体训练框架运行。

2.2 完整程序执行流程

加载AMP专家运动数据集 → 初始化IsaacSim仿真环境与机器人模型 → 批量并行仿真迭代（支持最高4096并行环境） → 实时计算双奖励值（AMP姿态匹配+步态周期奖励） → 反向传播更新策略网络 → 迭代优化行走/奔跑策略 → 保存最优训练模型。

2.3 程序核心特性

• 双奖励耦合：AMP奖励保证运动贴合人类自然步态，周期性步态奖励杜绝行走卡顿、奔跑失衡，兼顾自然性与稳定性；

• 超高并行训练：支持多环境并行迭代，大幅缩短模型收敛周期；

• 日志可视化：适配Tensorboard，可实时查看奖励变化、训练损失、运动参数。

核心是基于 RSL-RL + IsaacLab 实现机器人运动的 RL 训练，关键特性：

• 奖励函数：AMP 风格（对齐预定义运动）+ 周期性步态奖励（保证行走 / 奔跑的节奏稳定性）；

• 训练入口：legged_lab/scripts/train.py，支持指定任务（walk/run）、日志器（tensorboard）、环境数等参数；

• 验证方式：训练后可通过仿真直接验证运动效果，或导出策略到 MuJoCo 做 Sim2Sim 验证。

3. 传感器感知控制模块（环境交互程序链路）

该模块为机器人运动提供环境感知辅助程序，依托射线投射传感器算法，实现仿真环境障碍物检测、地形感知，让运动策略具备环境适配能力，目前已完成基础程序开发，感知闭环功能持续迭代完善。

3.1 核心程序文件与分工

• legged_lab/sensors/：传感器核心程序目录，封装射线投射感知算法，实现仿真环境距离检测、障碍物定位、地形起伏识别。

• play_amp_animation.py（带传感器参数）：感知可视化程序，支持walk_with_sensor、run_with_sensor任务，可直观查看传感器感知数据与机器人运动联动效果。

• legged_lab/utils/：感知数据处理工具程序，过滤感知噪声、规整传感器数据，为运动策略调整提供有效输入。

3.2 完整程序执行流程

传感器初始化启动 → 仿真环境实时采集障碍物、地形数据 → 工具程序降噪处理 → 数据输入运动控制策略 → 机器人动态调整步态、规避障碍 → 完成环境交互闭环。

3.3 程序迭代规划

当前已实现基础环境感知与运动联动，后续将通过新增传感器驱动程序、优化感知决策算法，完善全场景感知控制能力，实现复杂环境自适应运动。

当前已集成射线投射传感器，用于环境感知（如障碍物检测），未来计划扩展更多传感器、完善 "感知控制" 模块（让机器人基于感知结果调整运动策略）。

4. Sim2Sim / Sim2Real 迁移部署模块（模型落地程序链路）

该模块是仿真到落地的核心转接程序，实现训练策略的跨仿真器验证与真实机器人部署，打通仿真训练与实机应用的壁垒，分为Sim2Sim跨仿真验证、Sim2Real实机部署两条程序链路。

4.1 核心程序文件与分工

• legged_lab/scripts/play.py：仿真策略回放程序，加载训练完成的模型权重，复现机器人行走、奔跑运动效果，用于训练后初步校验。

• legged_lab/scripts/sim2sim.py：跨仿真迁移核心程序，将IsaacSim训练的策略模型迁移至MuJoCo仿真器，完成跨平台泛化性验证。

• Exported_policy/：模型存储目录，存放程序自动导出的最优策略文件（.pt格式），支持直接加载复用。

• 关联部署仓库Deploy_Tienkung：实机部署核心程序，包含ROS2控制库、机器人SDK、模型格式转换工具，是真实机器人运行RL策略的底层支撑。

4.2 Sim2Sim 程序执行流程

训练完成自动导出policy.pt模型 → 调用sim2sim.py脚本 → 加载MuJoCo仿真环境配置 → 导入策略模型执行运动任务 → 验证跨仿真器稳定性与泛化性。

4.3 Sim2Real 实机部署程序链路（完整闭环）

IsaacLab训练导出.pt策略模型 → 调用python_scripts/torch2ov.py转换模型为机器人硬件适配格式 → 通过rl_control_new（ROS2控制库）加载策略 →x_humanoid_rl_sdk完成机器人状态调度、指令解析 → 真实天工机器人执行行走/奔跑运动，完成实机落地。

4.4 部署环境硬性要求

实机部署需适配 Ubuntu22.04、ROS2 Humble、C++17 编译环境，依托专属SDK实现仿真策略到硬件指令的精准转换。

• Sim2Sim：支持将 IsaacSim 中训练的策略迁移到 MuJoCo 仿真环境，验证算法在不同仿真器的泛化性；

• Sim2Real：已完成真实 TienKung 机器人的 demo 验证，部署相关代码可参考关联仓库：https://github.com/Open-X-Humanoid/Deploy_Tienkung.git。

四、安装与快速使用

1. 安装流程（核心步骤）

# 1. 先安装 IsaacLab（建议 conda 方式，参考官方文档） # 2. 克隆仓库（需在 IsaacLab 目录外） git clone <TienKung-Lab 仓库地址> cd TienKung-Lab # 3. 安装 TienKung-Lab 核心库（可编辑模式） pip install -e . # 4. 安装 RSL-RL 依赖 cd rsl_rl pip install -e . # 5. 验证安装（运行行走任务训练，无头模式，64 个并行环境） python legged_lab/scripts/train.py --task=walk --logger=tensorboard --headless --num_envs=64

2. 核心使用场景示例

（1）运动重定向（从 SMPLX 到 TienKung）

# 步骤1：用 GMR 转换 SMPLX 数据为机器人格式 python scripts/smplx_to_robot.py --smplx_file <SMPLX数据路径> --robot tienkung --save_path <保存的pkl文件路径> # 步骤2：转换为可视化用数据（供 play_amp_animation.py 验证） python legged_lab/scripts/gmr_data_conversion.py --input_pkl <上述pkl路径> --output_txt legged_lab/envs/tienkung/datasets/motion_visualization/motion.txt # 步骤3：可视化并导出 AMP 训练用的专家数据 python legged_lab/scripts/play_amp_animation.py --task=walk --num_envs=1 --save_path legged_lab/envs/tienkung/datasets/motion_amp_expert/motion.txt --fps 30.0

（2）RL 训练与验证

• 训练：指定任务（walk/run）、日志、环境数等参数运行 train.py；

• 仿真验证：训练后可通过脚本播放机器人运动，验证策略效果；

• Sim2Sim 迁移：将训练好的策略导出，在 MuJoCo 中加载验证。

五、TODO 与未来规划

仓库仍在迭代中，核心待完成项：

• 新增更多传感器（丰富感知能力）；

• 完善感知控制模块（让机器人基于传感器输入动态调整运动策略）。

已完成的关键里程碑：

• ✅ 2025-09-27：支持运动重定向；

• ✅ 2025-11-07：新增 Sim2Real 演示；

• ✅ 2025-11-19：添加部署仓库的超链接（真实机器人落地代码）。

六、核心优势与适用场景

1. 优势：

   1. 基于成熟的 IsaacLab/RSL-RL 生态，降低 RL 开发门槛；

   2. 兼顾 "仿真验证" 与 "真实落地"，且支持跨仿真器迁移；

   3. 模块化设计，可快速扩展新传感器、新运动任务；

   4. 已在真实人形机器人验证，具备实际应用价值。

2. 适用场景：

   1. 人形机器人 locomotion 算法研发（行走、奔跑、避障）；

   2. RL + 仿真的机器人控制算法验证；

   3. Sim2Real 算法落地研究；

   4. 运动重定向技术在人形机器人的应用。

综上，TienKung-Lab 是一套从 "运动数据预处理→RL 训练→仿真验证→真实机器人落地" 全链路的人形机器人运动控制框架，核心聚焦 TienKung 机器人，但模块化设计也为其他人形机器人的运动控制研发提供了参考。