> ## 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.

# 安装与配置

## 系统要求

### 操作系统

运行本项目需要 Linux（x86\_64 或 arm64），推荐 Ubuntu 22.04 及以上。

### 软件版本

<table>
  <thead>
    <tr>
      <th>软件</th>
      <th>版本</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Python</td>
      <td>3.10 及以上</td>
    </tr>

    <tr>
      <td>Wuji Hand SDK</td>
      <td rowspan="2">参考<a href="https://docs.wuji.tech/docs/wuji-hand/v1/release-notes/">版本发布记录</a>获取最近更新</td>
    </tr>

    <tr>
      <td>固件</td>
    </tr>
  </tbody>
</table>

### 输入设备

| 设备 | 说明 |
| :- | :- |
| Apple Vision Pro | 实时手部追踪 |
| Wuji Glove | 经 Wuji SDK 实时获取手部骨骼数据（推荐） |
| 预录制数据 | 回放 MediaPipe 格式数据，用于验证和调试 |
| MP4 视频 | 从离线手部视频提取关键点，用于演示、调试和验证 |
| Intel RealSense | 从 RGB 相机流实时提取关键点 |

<Info>
  系统采用统一的 MediaPipe 关键点格式作为输入。当前公开示例已支持 Vision Pro、Wuji Glove、预录制数据、MP4 视频和 Intel RealSense。还可接入 Pico、Meta Quest 或其他基于图像识别的手部追踪方案进行二次开发。
</Info>

## 安装指南

### 克隆仓库

```bash theme={null}
git clone --recurse-submodules https://github.com/wuji-technology/wuji-retargeting.git
cd wuji-retargeting
git lfs pull
```

<Warning>
  使用 `--recurse-submodules` 参数拉取 Wuji Hand URDF 模型子模块。
</Warning>

### 安装依赖

```bash theme={null}
pip install -r requirements.txt
pip install -e .
```

<Warning>
  **Ubuntu 22.04 注意**：系统自带的 `pip 22.0.2` 存在构建隔离 bug，可能把本包安装成 `UNKNOWN 0.0.0` 且丢失所有依赖。先升级 pip 再安装：`python3 -m pip install -U pip`。
</Warning>

<Info>
  如果安装过程中遇到问题，请参考[故障排除](/docs/wuji-retargeting/appendix#故障排除)。
</Info>

### 可选输入模式依赖

* **Vision Pro / 预录制数据**：完成上述基础安装即可使用。
* **Wuji Glove**：需要安装 Wuji SDK：

```bash theme={null}
pip install wuji-sdk
```

* **MP4 视频**：需要安装视频模式额外依赖：

```bash theme={null}
pip install -e ".[video]"
```

* **Intel RealSense**：除基础安装外，还需要安装 RealSense 额外依赖：

```bash theme={null}
pip install -e ".[realsense]"
```

<Info>
  MP4 视频模式需要先安装 video 额外依赖，并由用户自行提供输入视频文件。RealSense 额外依赖已包含 video 的全部依赖，无需重复安装。RealSense 模式需要已连接并可正常访问的 Intel RealSense 设备。
</Info>

### 在 Docker 中运行

本仓库不提供官方 Dockerfile。如需在容器中运行，自行构建镜像即可，上述安装步骤在容器内同样适用。

实机和 Wuji Glove 路径需要额外挂载主机 `~/.wuji` 目录。Wuji Hand URDF 模型随子模块已经在镜像中，但 Wuji SDK（`wuji_sdk` 用于 Wuji Glove，`wujihandpy` 用于实机）读取的每设备资产位于宿主机 `$HOME/.wuji`，包括设备 URDF（`~/.wuji/sdk/models/<serial>_hand.urdf`）和参数文件（`~/.wuji/sdk/params/<serial>.toml`），由 Wuji Studio 标定生成。容器内默认无这些文件，必须挂载：

```bash theme={null}
docker run --rm -it \
    -v ~/.wuji:/root/.wuji \
    your-retargeting-image
```

把宿主机 `~/.wuji` 挂载到容器用户的 home 目录（root 用户挂到 `/root/.wuji`，非 root 用户按实际用户名调整）。实机与 Wuji Glove 路径还需要 USB 透传或 host 网络。仿真和回放路径（如 `teleop_sim.py --play data/avp1.pkl`）不需要 `~/.wuji`。

### 配置 Apple Vision Pro

使用 Vision Pro 进行实时手部追踪，需要完成以下配置。如暂无 Vision Pro，可使用预录制数据验证系统功能。

#### 安装 VisionOS 应用

在 Apple Vision Pro 上从 [App Store](https://apps.apple.com/us/app/tracking-streamer/id6478969032) 安装 **Tracking Streamer**。

#### 安装 Python 库

```bash theme={null}
pip install --upgrade avp_stream
```

<Info>
  请保持 `avp_stream` 库为最新版本。最新的 App Store 版本要求 `avp_stream >= 2.50.0`。如果 Python 库版本过旧，VisionOS 应用会显示警告。
</Info>

#### 可选：iOS 伴侣应用

在 iPhone/iPad 上从 App Store 安装 **Tracking Manager**，用于管理录制、设置和摄像头标定。

无需额外的网络配置，安装后可直接使用。


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