文档阅读指引

版本发布记录

Wuji Retargeting 各版本更新内容与变更说明

安装与配置

系统要求、依赖安装和 Apple Vision Pro 配置

• 系统要求
  系统采用统一的 MediaPipe 关键点格式作为输入。当前公开示例已支持 Vision Pro、预录制数据、MP4 视频和 Intel RealSense。此外，也可接入 Pico、Meta Quest 或其他基于图像识别的手部追踪方案进行二次开发。
• 安装指南
  使用 --recurse-submodules 参数拉取 Wuji Hand URDF 模型子模块。

快速开始

仿真演示和真机遥操作的运行方法和命令参考

• 真机控制
  真机控制流程与 Linux USB 串口权限配置
• 命令参考
  teleop_sim.py（仿真）、teleop_real.py（真机）

调参指南

tuning_tool 使用、segment_scaling 缩放、参数速查表、调参顺序

• tuning_tool 启动和使用方法
  tuning_tool.py 是调参时的主要观察工具，同步显示数采手套收集的手部运动和 Wuji Hand 的运动以及其中的映射关系，查看目标骨架是否合理、Wuji Hand 动作是否符合期望，检查调参效果。
• 最常用：segment_scaling
  几何缩放：按手指、按目标向量（wrist→PIP / wrist→DIP / wrist→TIP）微调长度，修正某根手指长度与 Wuji Hand 骨架不一致的问题。所有几何修正都通过 segment_scaling 完成。
• 参数分类
  retarget 块下的参数按用途可以分五类：
• 参数速查表
• 实际调参顺序

API 介绍

Retargeter 用法、输入输出格式和配置参数说明

• 基础用法
• 输入格式
  输入数据为 MediaPipe 格式的手部关键点，形状为 (21, 3)，包含 21 个关键点的 3D 坐标（单位：米）。无论输入源来自 Vision Pro、预录制回放、MP4 视频还是 Intel RealSense，相机或脚本最终都会统一输出为这一格式。
• 输出格式
  输出为长度为 20 的关节角度数组（弧度），对应 Wuji Hand 的 20 个关节：
• 配置文件
  上面的示例适用于默认的 Vision Pro 配置思路。对于视频与 RealSense 这类基于 MediaPipe 视觉输入的场景，建议使用单独的 adaptive_analytical_video.yaml。
• 不同输入模式的配置
• 驱动自定义灵巧手
  optimizer 块下三个键用于把同一套重定向算法指向不同手型，无需改代码：
• video_input 参数
  adaptive_analytical_video.yaml 还包含 video_input 配置段，用于视频和 RealSense 输入预处理：
• 参数说明
  默认配置针对 Apple Vision Pro 调优。对于 MP4 视频和 Intel RealSense，建议优先使用 adaptive_analytical_video.yaml，并根据手型与画面条件进一步调整 scaling、segment_scaling 和 video_input 相关参数。
• 手型适配
  如果重定向效果不佳，可以调整以下参数：

附录

自适应优化算法原理、故障排除和相关资源

• 算法原理
  优化公式
• 故障排除
  Q: pinocchio 安装报错？
• 相关资源