Wuji HandWuji GloveWuji StudioWuji SDK
Retargeting 使用说明

快速开始

运行示例前，请确保：

  • 已完成安装与配置。如果遇到模型文件找不到的错误，请检查 submodule 是否已初始化：git submodule update --init --recursive
  • 使用 Vision Pro 时，需在 Apple Vision Pro 上安装 Tracking Streamer（通过 App Store 或 GitHub 获取）

仿真演示

cd example

# Vision Pro 实时遥操作（推荐），将 <vision-pro-ip> 替换为实际 IP 地址，IP 地址可在 Tracking Streamer 中查看
python teleop_sim.py --input visionpro --ip <vision-pro-ip> --hand left

# 回放预录制数据（无 Vision Pro 时使用）
python teleop_sim.py --play data/avp1.pkl --hand left

# 使用 MP4 视频作为输入
python teleop_sim.py --video <your-video.mp4> --hand right
python teleop_sim.py --video <your-video.mp4> --hand right --show-video

# 使用 Intel RealSense 作为实时输入
python teleop_sim.py --realsense --hand right
python teleop_sim.py --realsense --hand right --show-video

预期效果：

使用 Vision Pro 实时遥操作，仿真界面将显示仿真手跟随用户手部动作。 使用回放预录制数据将类似如下演示：

使用 MP4 或 RealSense 输入时，可通过 --show-video 查看原始图像与 MediaPipe 关键点叠加结果，便于检查输入质量与调试效果。

真机控制

运行示例

cd example

# Vision Pro 实时输入（推荐，需配置 Apple Vision Pro），将 <vision-pro-ip> 替换为实际 IP 地址，IP 地址可在 Tracking Streamer 中查看
python teleop_real.py --input visionpro --ip <vision-pro-ip> --hand right

# 回放预录制数据（无 Vision Pro 时使用）
python teleop_real.py --play data/avp1.pkl --hand right

# 使用 MP4 视频作为输入
python teleop_real.py --video <your-video.mp4> --hand right
python teleop_real.py --video <your-video.mp4> --hand right --show-video

# 使用 Intel RealSense 作为实时输入
python teleop_real.py --realsense --hand right
python teleop_real.py --realsense --hand right --show-video

Linux USB 权限：Wuji Hand 通过 USB 串口通信，Linux 默认限制普通用户访问串口设备。建议将用户加入串口设备组：sudo usermod -aG dialout $USER（需重新登录生效）。sudo chmod a+rw /dev/ttyUSB0 仅用于临时排障且重启后失效。

预期效果：

使用 Vision Pro 实时遥操作，Wuji Hand 将跟随用户手部动作。 使用回放预录制数据，Wuji Hand 运动轨迹与仿真演示中的预期效果视频相似。 使用 MP4 视频输入更适合离线验证和演示，使用 RealSense 则适合在没有 Vision Pro 时进行实时输入验证。

录制输入数据

使用 Vision Pro 时可以同时录制输入数据，录制的数据可用于后续回放和调试：

cd example
python teleop_real.py --input visionpro --record

当使用 --video 或 --realsense 时，示例脚本会默认切换到 config/adaptive_analytical_video.yaml。如需自定义调参，仍可通过 --config 覆盖。

选择灵巧手型号：Wuji Hand（默认）和 Wuji Hand 2

上述命令默认驱动 Wuji Hand（USB 串口），无需额外参数。要驱动 Wuji Hand 2（以太网），用 --hand-model wh120 并指定 Wuji Hand 2 配置文件。Wuji Hand 2 配置通过 optimizer.urdf_path / mjcf_path / link_naming 把重定向器指向 Wuji Hand 2 模型，代码侧无需改动：

cd example

# 使用 Wuji Glove 输入 + 驱动 Wuji Hand 2（右手）
python teleop_real.py --input wuji_glove --hand right --glove-sn <YOUR_SN> \
    --config config/adaptive_analytical_wuji_glove_wh120_right.yaml

# 网络上有多只 Wuji Hand 2 在线，按地址显式指定：
python teleop_real.py --input wuji_glove --hand right --glove-sn <YOUR_SN> \
    --wh120-ip <hand-ip>:50001 \
    --config config/adaptive_analytical_wuji_glove_wh120_right.yaml

不带 --hand-model 时，从配置文件自动推断：文件名含 wh120 或 optimizer.urdf_path 指向 Wuji Hand 2 模型即识别为 Wuji Hand 2，否则按 Wuji Hand 走。

--wh120-ip 留空时自动扫描网络上的 Wuji Hand 2，单只直接连，多只时按 --hand left/right 匹配握手反馈的手别。

Wuji Hand 2 与 Wuji Hand 固件版本必须与本地 wuji_sdk 匹配，连接阶段不匹配会快速报错。

命令参考

teleop_sim.py（仿真）

选项默认值说明
--configconfig/adaptive_analytical_avp.yamlYAML 配置文件
--handleft手的方向（left/right）
--input-输入类型（visionpro/mediapipe_replay/video/realsense）
--play FILE-播放录制数据（--input mediapipe_replay 的快捷方式）
--video FILE-使用 MP4 视频作为输入（--input video 的快捷方式）
--realsense-使用 Intel RealSense 作为输入（--input realsense 的快捷方式）
--show-video-显示视频与 MediaPipe 关键点叠加，仅用于 video/realsense 模式
--ip192.168.50.127Vision Pro IP 地址
--speed1.0播放速度
--no-loop-禁用循环播放
--record-录制输入数据
--output FILE-录制输出路径

teleop_real.py（真机）

选项默认值说明
--configconfig/adaptive_analytical_avp.yamlYAML 配置文件
--handright手的方向（left/right）
--input-输入类型（visionpro/mediapipe_replay/video/realsense）
--play FILE-播放录制数据（--input mediapipe_replay 的快捷方式）
--video FILE-使用 MP4 视频作为输入（--input video 的快捷方式）
--realsense-使用 Intel RealSense 作为输入（--input realsense 的快捷方式）
--show-video-显示视频与 MediaPipe 关键点叠加，仅用于 video/realsense 模式
--ip192.168.50.127Vision Pro IP 地址
--speed1.0播放速度
--no-loop-禁用循环播放
--record-录制输入数据
--output FILE-录制输出路径
--hand-model从配置推断灵巧手型号：wh110（Wuji Hand，USB）或 wh120（Wuji Hand 2，网络）
--hand-serial-Wuji Hand 序列号
--wh120-ip自动扫描Wuji Hand 2 网络地址，如 192.168.1.111:50001
--kp3.0Wuji Hand 2 MIT 控制器 kp
--kd0.1Wuji Hand 2 MIT 控制器 kd
--current-limit1.5Wuji Hand 2 每关节系统电流上限，单位安培

安装与配置

上一页

调参指南

下一页

目录

真机控制
运行示例
录制输入数据
选择灵巧手型号：Wuji Hand（默认）和 Wuji Hand 2
命令参考
teleop_sim.py（仿真）
teleop_real.py（真机）