系统要求
操作系统
运行本项目需要 Linux（x86_64 或 arm64），推荐 Ubuntu 22.04 及以上。软件版本
| 软件 | 版本 |
|---|---|
| Python | 3.10 及以上 |
| Wuji Hand SDK | 参考版本发布记录获取最近更新 |
| 固件 |
输入设备
系统采用统一的 MediaPipe 关键点格式作为输入。当前公开示例已支持 Vision Pro、Wuji Glove、预录制数据、MP4 视频和 Intel RealSense。还可接入 Pico、Meta Quest 或其他基于图像识别的手部追踪方案进行二次开发。
安装指南
克隆仓库
安装依赖
如果安装过程中遇到问题，请参考故障排除。
可选输入模式依赖
- Vision Pro / 预录制数据：完成上述基础安装即可使用。
- Wuji Glove：需要安装 Wuji SDK：
- MP4 视频：需要安装视频模式额外依赖：
- Intel RealSense：除基础安装外，还需要安装 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 标定生成。容器内默认无这些文件，必须挂载：
~/.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 安装 Tracking Streamer。安装 Python 库
请保持
avp_stream 库为最新版本。最新的 App Store 版本要求 avp_stream >= 2.50.0。如果 Python 库版本过旧，VisionOS 应用会显示警告。