Xmimic 动作跟踪代码

安装

• 根据 Isaac Lab 安装指南安装 Isaac Lab，并将环境版本对齐到以下当前验证版本。推荐使用 conda 方式安装，便于后续在终端中直接调用 Python 脚本。

当前验证环境:

• Python 3.11
• Isaac Sim 5.1
• Isaac Lab 2.3.2

动作转换、训练和评估应使用一致的 Isaac Lab / Isaac Sim 版本及对应自由度的机器人模型配置。更换环境版本或模型配置后，应重新生成动作 NPZ，避免 body 数量或顺序不一致。

• 将本仓库单独克隆到 Isaac Lab 目录外，例如不要放在 IsaacLab 文件夹内部:

# 方式一: SSH
git clone git@github.com:Open-X-Humanoid/xMimic.git

# 方式二: HTTPS
git clone https://github.com/Open-X-Humanoid/xMimic.git

• 安装项目依赖:

python -m pip install -e source/whole_body_tracking

动作跟踪

动作预处理

将处理后的动作数据保存在本地，例如 motion_data/ 目录下，并在训练脚本中指定对应的动作文件。参考动作需要完成重映射，并且仅使用广义坐标。

• 通过正向运动学将重映射后的动作转换为包含最大坐标信息的数据，包括 body pose、body velocity 和 body acceleration。脚本会在本地保存 {motion_name}.npz 文件:

python scripts/csv_to_npz.py --input_file {motion_name}.csv --input_fps 30 \
--output_name {motion_name} --output_dir motion_data --headless

• 在 Isaac Sim 中回放转换后的动作，用于检查动作是否正常:

python scripts/replay_npz.py --motion_file motion_data/{motion_name}.npz

训练仿真全流程

动作重映射

下载 xGMR，使用 xGMR 将 BVH 格式数据转化为 PKL 格式数据。

git clone https://github.com/Open-X-Humanoid/xGMR.git

动作重映射

python scripts/bvh_to_robot.py --bvh_file data/lafan/dance1_subject3.bvh --robot tiangong3 --save_path output/YYW.pkl --motion_fps {fps} --add_collision_avoidance True --format "lafan"

将生成的 .pkl 文件复制到 motion_data/ 文件夹下。

动作格式转换

• 将 xGMR 输出的 .pkl 文件转化成训练所需的 .npz 文件:

python scripts/gmr_to_npz_inter.py \
--input_file " " \
--input_fps {fps} --frame_range 10 -1 --output_name {motion_name} --output_fps 100 \
--robot tiangong3_23dof \
--start_frames 100 --end_frames 50 --hold_pos 300

转换得到的 NPZ 同时保存 body_names 和 joint_names 字符串数组，其顺序分别对应 body 数据和关节数据的第二维。训练会按这些名称匹配并重排数据，不再要求 NPZ 与训练模型的内部索引顺序相同。旧 NPZ 缺少名称字段时，对应数据会回退到原来的索引加载方式，并在终端打印警告；此时必须保证 NPZ 的 body/关节顺序与训练模型一致。已有名称重复、缺少所需 link/关节或数据维度不匹配时仍会报错。名称匹配不替代模型兼容性检查，转换与训练仍应使用相同的机器人模型配置。

23 自由度使用 --robot tiangong3_23dof；29 自由度使用 --robot tiangong3_29dof。 29 自由度版本额外启用双侧 elbow_yaw、wrist_pitch、wrist_roll，输入动作需包含这六个关节（支持 29 关节或含头部的 31 关节输入）。

策略训练

• 指定运动文件训练 policy:

python scripts/rsl_rl/train.py --task=Tracking-Tiangong3-23DoF-v0 \
--num_envs 4096 \
--max_iterations 100000 \
--device cuda:0 \
--motion_file motion_data/{motion_name}.npz \
--headless --logger tensorboard 

23 自由度训练日志保存到 tiangong3_23dof_flat 实验目录。

29 自由度任务使用 --task=Tracking-Tiangong3-29DoF-v0，并指定通过 --robot tiangong3_29dof 转换得到的 .npz 文件。训练日志保存到 tiangong3_29dof_flat 实验目录。

策略评估

• 使用以下命令运行训练好的 policy:

python scripts/rsl_rl/play.py \
--task=Tracking-Tiangong3-23DoF-v0 --num_envs=2 \
--load_run={run_folder_regex} --checkpoint={checkpoint_regex} \
--motion_file motion_data/{motion_name}.npz

评估 29 自由度策略时，同样使用 --task=Tracking-Tiangong3-29DoF-v0 和对应的 29 自由度动作文件。

启动 MuJoCo 仿真

下载 xSIM_MUJOCO:

git clone https://github.com/Open-X-Humanoid/xSIM_MUJOCO.git

启动 MuJoCo 仿真:

source /opt/ros/humble/setup.bash
export ROS_DOMAIN_ID=your_domain_id
python scripts/simulator_view_asyn.py -m evt2(机器人名称)

策略部署

部署代码 xMIGCS 地址:

git clone https://github.com/Open-X-Humanoid/Deploy_Tienkung.git

切换到3.0分支

将导出的 .onnx 文件放在 policy/beyond_mimic/model 中，同时在 policy/beyond_mimic/config/BeyondMimic_down.yaml 中配置对应的 onnx_path、kp 和 kd。

在 xMIGCS 目录下执行:

export ROS_DOMAIN_ID=your_domain_id
python3 rl_control_node.py

若使用键盘控制，按 1；若使用 Xbox 手柄控制，按 LT+HOME 进入 Xmimic 对应策略。

代码结构

下面是本仓库的代码结构概览:

• source/whole_body_tracking/whole_body_tracking/tasks/tracking/mdp 该目录包含定义 BeyondMimic MDP 的基础函数，主要模块如下:

  • commands.py 命令库，用于根据参考动作、当前机器人状态和误差计算相关变量，包括位姿误差、速度误差、初始状态随机化和自适应采样。

  • rewards.py 实现 DeepMimic 奖励函数和相关平滑项。

  • events.py 实现域随机化相关项。

  • observations.py 实现动作跟踪和数据采集所需的观测项。

  • terminations.py 实现提前终止和超时条件。

• source/whole_body_tracking/whole_body_tracking/tasks/tracking/tracking_env_cfg.py 包含动作跟踪任务的环境 MDP 超参数配置。

• source/whole_body_tracking/whole_body_tracking/tasks/tracking/config/g1/agents/rsl_rl_ppo_cfg.py 包含动作跟踪任务的 PPO 超参数配置。

• source/whole_body_tracking/whole_body_tracking/robots 包含机器人相关配置，包括 armature 参数、关节刚度和阻尼计算，以及动作缩放计算。

• scripts 包含动作数据预处理、策略训练和策略评估相关的工具脚本。

该结构便于保持模块化，也方便后续开发者扩展和定位代码。