安装与配置

系统要求

软件版本

软件	版本
Python	3.10
Wuji Hand SDK	参考版本发布记录获取最近更新
固件	参考版本发布记录获取最近更新

输入设备

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

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

安装指南

克隆仓库

git clone --recurse-submodules https://github.com/wuji-technology/wuji-retargeting.git
cd wuji-retargeting
git lfs pull

使用 --recurse-submodules 参数拉取 Wuji Hand URDF 模型子模块。

安装依赖

pip install -r requirements.txt
pip install -e .

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

如果安装过程中遇到问题，请参考故障排除。

可选输入模式依赖

Vision Pro / 预录制数据：完成上述基础安装即可使用。
MP4 视频：需要安装视频模式额外依赖：

pip install -e ".[video]"

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

pip install -e ".[realsense]"

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

在 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 标定生成。容器内默认无这些文件，必须挂载：

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。

pip install --upgrade avp_stream

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

可选：iOS 伴侣应用

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

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