快速开始
仿真演示
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-videoLinux 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 每关节系统电流上限，单位安培 |