> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速开始

<Warning>
  运行示例前，请确保：

  * 已完成[安装与配置](/docs/wuji-retargeting/installation)。如果遇到模型文件找不到的错误，请检查 submodule 是否已初始化：`git submodule update --init --recursive`
  * 使用 Vision Pro 时，需在 Apple Vision Pro 上安装 **Tracking Streamer**（通过 [App Store](https://apps.apple.com/us/app/tracking-streamer/id6478969032) 或 [GitHub](https://github.com/Improbable-AI/VisionProTeleop) 获取）
</Warning>

<h2 id="simulation">仿真演示</h2>

```bash theme={null}
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 实时遥操作，仿真界面将显示仿真手跟随用户手部动作。
使用回放预录制数据将类似如下演示：

<video controls width="100%">
  <source src="https://mintcdn.com/wuji-0bbde051/isWZkBBshh11pitl/assets/source/images/zh/wuji-retargeting/avp1.pk1.mp4?fit=max&auto=format&n=isWZkBBshh11pitl&q=85&s=83ee32ce98660d82412ef73c99052190" type="video/mp4" data-path="assets/source/images/zh/wuji-retargeting/avp1.pk1.mp4" />
</video>

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

## 真机控制

### 运行示例

```bash theme={null}
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
```

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

预期效果：

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

### 录制输入数据

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

```bash theme={null}
cd example
python teleop_real.py --input visionpro --record
```

<Info>
  当使用 `--video` 或 `--realsense` 时，示例脚本会默认切换到 `config/adaptive_analytical_video.yaml`。使用 `--input wuji_glove` 时，会自动切换到对应的 `adaptive_analytical_wuji_glove_*.yaml`。如需自定义调参，仍可通过 `--config` 覆盖。
</Info>

### 选择灵巧手型号：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 模型，代码侧无需改动：

```bash theme={null}
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` 匹配握手反馈的手别。

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

## Wuji Glove 输入

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

### 在 Wuji Studio 中准备手套

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

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

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

### 使用手套运行

```bash theme={null}
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` 记录中性位的手腕和拇指偏移，使重定向手部与放松姿态对齐：

```bash theme={null}
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 每关节系统电流上限，单位安培 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.