ik_pointing

ik_pointing 是一个面向 Unitree G1 的固定站姿右臂指认项目。系统使用头部 Intel RealSense D435i 深度相机感知桌面目标位置，将目标统一表示为 target_pos_b@pelvis，再通过固定站姿右臂 IK 求解 7 个关节，并用 rt/lowcmd 在真机执行 pointing 动作。

当前项目聚焦 Part1 单目标场景：桌面上只有一个凸起目标，机器人下身与腰部保持固定，只允许右臂运动。主链路为：

depth -> target_pos_camera -> pelvis_from_camera -> target_pos_b
-> IK -> latest_arm_joint_targets.json -> rt/lowcmd -> G1 pointing

概述

• 当前主线是“深度感知 -> 目标点桥接 -> IK -> 低层控制”。
• 统一中间接口是 target_pos_b@pelvis，坐标约定为 x 前、y 左、z 上。
• 真机执行主线采用 mode_machine + rt/lowcmd。
• 已验证结果：默认深度 sim2sim 误差约 0.00295 m，一组可用的 RealSense 外参标定平均残差约 0.0148 m。

硬件条件

• sim2sim：Linux 主机、Python 3.10+、可运行 MuJoCo Python 渲染。
• sim2real：Unitree G1 29DoF、Intel RealSense D435i、USB 3.0、机器人 DDS 网口连接、固定站姿、固定腰部、固定相机安装、吊装或等价安全保护。

运行环境

• 推荐：Ubuntu 22.04 / 24.04，Python 3.10 / 3.11，MuJoCo 3.3+。
• 基础依赖安装：

cd ik_pointing
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

• 真机额外依赖：

pip install -r requirements-sim2real.txt

• 仓库已内置 third_party/unitree_sdk2_python 的最小运行子集，供 lowcmd 脚本导入。

sim2sim 方法本机运行

1. 运行深度 sim2sim：

python3 scripts/run_part1_depth_sim2sim.py

2. 将输出送入 IK：

python3 scripts/ik_target_to_joint_targets.py \
  --target-json logs/pointing/sim2sim_depth/latest_target_pos_b.json \
  --output logs/pointing/sim2sim_depth/latest_arm_joint_targets.json

3. 关键输出文件：logs/pointing/sim2sim_depth/latest_target_pos_b.json、logs/pointing/sim2sim_depth/latest_arm_joint_targets.json、logs/pointing/sim2sim_depth/synthetic_truth.json。

sim2real 方法将项目上传至机器人真机运行

1. 标定 RealSense 外参：

python3 scripts/calibrate_pelvis_from_realsense_points.py \
  --points-json config/pelvis_calibration_points_example.json \
  --output logs/pointing/realsense_pelvis_calibration.json

2. 持续输出 target_pos_b：

python3 scripts/realsense_to_target_pos_b.py \
  --calibration logs/pointing/realsense_pelvis_calibration.json \
  --output logs/pointing/latest_target_pos_b.json \
  --save-debug-depth logs/pointing/latest_depth_debug.png

3. 持续输出右臂关节目标：

python3 scripts/ik_target_to_joint_targets.py \
  --target-json logs/pointing/latest_target_pos_b.json \
  --output logs/pointing/latest_arm_joint_targets.json \
  --watch --reset-on-change

4. 真机执行：

python3 sim2real.py \
  --target-json logs/pointing/latest_arm_joint_targets.json \
  --network-interface enp2s0 \
  --auto-release-motion-mode

其中 enp2s0 替换为实际网卡名。

安全说明

• 首次上真机必须吊装。
• 先确认机器人已经稳定站立，再启动 sim2real.py。
• 当前项目假设只动右臂，不要与其他全身控制程序同时接管。
• 没有完成外参标定前，不要直接根据真机动作判断 IK 是否有误。