快速开始

运行示例前，请确保：

已完成安装与配置。如果遇到模型文件找不到的错误，请检查 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。使用 --input wuji_glove 时，会自动切换到对应的 adaptive_analytical_wuji_glove_*.yaml。如需自定义调参，仍可通过 --config 覆盖。

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

上述命令默认驱动 Wuji Hand（USB 串口），无需额外参数。要驱动 Wuji Hand 2（以太网），用 --hand-model wuji_hand_2 并指定 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_wuji_hand_2_right.yaml

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

不带 --hand-model 时自动推断：optimizer.urdf_path / optimizer.mjcf_path 或配置文件路径包含 hand2 字样即识别为 Wuji Hand 2，否则按 Wuji Hand 处理。示例配置文件名中的 hand_2 不参与匹配，识别凭配置内模型路径。 --wuji-hand-2-ip 留空时自动扫描网络上的 Wuji Hand 2，单只直接连接，多只时按 --hand left/right 匹配握手反馈的手别。

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

Wuji Glove 输入

Wuji Glove 是推荐的实时输入设备。它通过 wuji_sdk 发布 21 个 MediaPipe 格式手部关键点，驱动 Wuji Glove 示例配置。

在 Wuji Studio 中准备手套

遥操作前，先在 Wuji Studio 中连接并标定手套：

从 Wuji Studio 发布页下载 Wuji Studio。
在 Ubuntu 上安装桌面应用：sudo apt install ./wuji-studio_<version>_amd64.deb
连接 Wuji Glove，启动 Wuji Studio。
在 Connect 视图中搜索并连接手套。
打开 Visualization 确认手套实时运动与接触状态。
点击 Activity bar 底部的用户头像，通过 Create profile 新建用户档案，创建后自动切换为当前档案。预置的 Default 档案不保存标定结果，在该档案下执行标定不生效。
打开 Calibration 按屏幕提示完成标定。流程结束后 Wuji Studio 自动保存标定文件。

Wuji Studio 界面中的 profile 即 SDK 用户，标定生成的手部模型按用户档案隔离保存。遥操作运行时沿用当前选中的用户档案，因此标定完成后保持该档案不变，标定结果才会生效。档案管理详见 Wuji Studio 基础设置。

使用手套运行

cd example

# 仿真
python teleop_sim.py --input wuji_glove --hand right --glove-sn <YOUR_SN>

# 真机
python teleop_real.py --input wuji_glove --hand right --glove-sn <YOUR_SN>

Wuji Glove 路径额外提供左右手配置（adaptive_analytical_wuji_glove_left.yaml / adaptive_analytical_wuji_glove_right.yaml）。用手套驱动 Wuji Hand 2 时，传入对应的 Wuji Hand 2 配置，见上文「选择灵巧手型号」。

标定中性位偏移

calibrate_offset.py 记录中性位的手腕和拇指偏移，使重定向手部与放松姿态对齐：

cd example
python calibrate_offset.py --hand right \
    --config config/adaptive_analytical_wuji_glove_right.yaml

命令参考

teleop_sim.py（仿真）

选项	默认值	说明
`--config`	`config/adaptive_analytical_avp.yaml`	YAML 配置文件
`--hand`	`left`	手的方向（`left`/`right`）
`--input`	-	输入类型（`visionpro`/`mediapipe_replay`/`video`/`realsense`/`wuji_glove`）
`--play FILE`	-	播放录制数据（`--input mediapipe_replay` 的快捷方式）
`--video FILE`	-	使用 MP4 视频作为输入（`--input video` 的快捷方式）
`--realsense`	-	使用 Intel RealSense 作为输入（`--input realsense` 的快捷方式）
`--show-video`	-	显示视频与 MediaPipe 关键点叠加，仅用于 `video`/`realsense` 模式
`--device-name`	`glove`	Wuji Glove 的 wuji_sdk 设备名
`--glove-sn`	-	Wuji Glove 序列号（多台 Wuji 设备在线时必填）
`--ip`	`192.168.50.127`	Vision Pro IP 地址
`--speed`	`1.0`	播放速度
`--no-loop`	-	禁用循环播放
`--record`	-	录制输入数据
`--output FILE`	-	录制输出路径

teleop_real.py（真机）

选项	默认值	说明
`--config`	`config/adaptive_analytical_avp.yaml`	YAML 配置文件
`--hand`	`right`	手的方向（`left`/`right`）
`--input`	-	输入类型（`visionpro`/`mediapipe_replay`/`video`/`realsense`/`wuji_glove`）
`--play FILE`	-	播放录制数据（`--input mediapipe_replay` 的快捷方式）
`--video FILE`	-	使用 MP4 视频作为输入（`--input video` 的快捷方式）
`--realsense`	-	使用 Intel RealSense 作为输入（`--input realsense` 的快捷方式）
`--show-video`	-	显示视频与 MediaPipe 关键点叠加，仅用于 `video`/`realsense` 模式
`--device-name`	`glove`	Wuji Glove 的 wuji_sdk 设备名
`--glove-sn`	-	Wuji Glove 序列号（多台 Wuji 设备在线时必填）
`--ip`	`192.168.50.127`	Vision Pro IP 地址
`--speed`	`1.0`	播放速度
`--no-loop`	-	禁用循环播放
`--record`	-	录制输入数据
`--output FILE`	-	录制输出路径
`--hand-model`	从配置推断	灵巧手型号：`wuji_hand`（Wuji Hand，USB）或 `wuji_hand_2`（Wuji Hand 2，网络）
`--hand-serial`	-	Wuji Hand 序列号
`--wuji-hand-2-ip`	自动扫描	Wuji Hand 2 网络地址，如 `192.168.1.111:50001`
`--kp`	`3.0`	Wuji Hand 2 MIT 控制器 kp
`--kd`	`0.1`	Wuji Hand 2 MIT 控制器 kd
`--current-limit`	`1.5`	Wuji Hand 2 每关节系统电流上限，单位安培

概览

硬件

软件

更多

仿真演示

真机控制

运行示例

录制输入数据

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

Wuji Glove 输入

在 Wuji Studio 中准备手套

使用手套运行

标定中性位偏移

命令参考

teleop_sim.py（仿真）

teleop_real.py（真机）

​仿真演示

​真机控制

​运行示例

​录制输入数据

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

​Wuji Glove 输入

​在 Wuji Studio 中准备手套

​使用手套运行

​标定中性位偏移

​命令参考

​teleop_sim.py（仿真）

​teleop_real.py（真机）

仿真演示

真机控制

运行示例

录制输入数据

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

Wuji Glove 输入

在 Wuji Studio 中准备手套

使用手套运行

标定中性位偏移

命令参考

teleop_sim.py（仿真）

teleop_real.py（真机）