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

# Installation

## System Requirements

### Operating System

This project requires Linux (x86\_64 or arm64). Ubuntu 22.04 or later is recommended.

### Software Versions

<table>
  <thead>
    <tr>
      <th>Software</th>
      <th>Version</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Python</td>
      <td>3.10 or later</td>
    </tr>

    <tr>
      <td>Wuji Hand SDK</td>
      <td rowspan="2">See <a href="https://docs.wuji.tech/en/docs/wuji-hand/v1/release-notes/">Release Notes</a> for latest updates</td>
    </tr>

    <tr>
      <td>Firmware</td>
    </tr>
  </tbody>
</table>

### Input Devices

| Device | Description |
| :- | :- |
| Apple Vision Pro | Real-time hand tracking |
| Wuji Glove | Real-time hand skeleton data via the Wuji SDK (recommended) |
| Pre-recorded Data | Playback MediaPipe format data for validation and debugging |
| MP4 Video | Extract keypoints from offline hand videos for demos, debugging, and validation |
| Intel RealSense | Extract keypoints from a live RGB camera stream |

<Info>
  The system uses a unified MediaPipe keypoint format as input. Current public examples support Vision Pro, Wuji Glove, replay data, MP4 video, and Intel RealSense. Beyond that, you can integrate Pico, Meta Quest, or other image-based hand-tracking solutions for custom development.
</Info>

## Installation Guide

### Clone Repository

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

<Warning>
  Use the `--recurse-submodules` flag to pull the Wuji Hand URDF model submodule.
</Warning>

### Install Dependencies

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

<Warning>
  **Ubuntu 22.04 note**: The distro's stock `pip 22.0.2` has a build-isolation bug that can install this package as `UNKNOWN 0.0.0` with none of its dependencies. Upgrade pip first: `python3 -m pip install -U pip`.
</Warning>

<Info>
  If you encounter any issues during installation, please refer to [Troubleshooting](/en/docs/wuji-retargeting/appendix#troubleshooting).
</Info>

### Optional Input Mode Dependencies

* **Vision Pro / Pre-recorded data**: The base installation above is sufficient.
* **Wuji Glove**: Install the Wuji SDK:

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

* **MP4 video**: Install the video extra dependencies:

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

* **Intel RealSense**: In addition to the base installation, install the RealSense extra dependencies:

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

<Info>
  MP4 video mode requires you to install the video extras and provide your own input video file. The RealSense extras already include all video dependencies, so there's no need to install both. RealSense mode requires a connected Intel RealSense device that is accessible from your environment.
</Info>

### Run in Docker

This repository ships **no official Dockerfile**. To run it in a container, build your own image — the installation steps above work unchanged inside the container.

Live and real-hardware paths need an extra mount. The Wuji Hand URDF model ships with the submodule and is already inside the image, but the Wuji SDK (`wuji_sdk` for Wuji Glove, `wujihandpy` for the real hand) reads per-device assets from the host's `$HOME/.wuji` — for example the device URDF `~/.wuji/sdk/models/<serial>_hand.urdf` and parameters `~/.wuji/sdk/params/<serial>.toml`, provisioned by Wuji Studio. These files do not exist in a fresh container, so mount them in:

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

Mount the host's `~/.wuji` to the container user's home (`/root/.wuji` when running as root, adjust for other users). Real-hardware and Wuji Glove paths additionally need device connectivity (USB passthrough or host networking). Simulation and replay paths (e.g. `teleop_sim.py --play data/avp1.pkl`) do not require `~/.wuji`.

### Configure Apple Vision Pro

To use Vision Pro for real-time hand tracking, complete the following configuration. If you don't have a Vision Pro, use pre-recorded data to verify system functionality.

#### Install VisionOS App

Install **Tracking Streamer** from the [App Store](https://apps.apple.com/us/app/tracking-streamer/id6478969032) on your Apple Vision Pro.

#### Install Python Library

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

<Info>
  Keep the `avp_stream` library up to date. The latest App Store version requires `avp_stream >= 2.50.0`. The VisionOS app will display a warning if the Python library version is outdated.
</Info>

#### Optional: iOS Companion App

Install **Tracking Manager** from the App Store on your iPhone/iPad for managing recordings, settings, and camera calibration.

No additional network configuration is required. It works directly after installation.


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