手部重定向（Retargeting） - 文档中心

手部重定向把人手关键点（21 个 MediaPipe 格式 landmark）映射为 Wuji Hand 2 与 Wuji Hand 的 20 维关节角度命令，可直接送入设备。算法原生内置于 SDK，安装 pip install wuji-sdk numpy 即可使用——numpy 用于关键点/qpos 数组，此外无其他依赖。C SDK 提供对等接口，见 C SDK 参考——重定向。

快速开始

RetargetSession.for_hand(model, side) 按设备型号绑定内置 IK 配置。session.step(keypoints) 接受 (21, 3) float32 数组，返回 (20,) float32 关节角度，可直接发送到设备：

import numpy as np
from wuji_sdk import Handedness, HandModel, RetargetSession

session = RetargetSession.for_hand(HandModel.WujiHand2, side=Handedness.Right)

# keypoints：21 个 MediaPipe landmark，单位米
keypoints = np.zeros((21, 3), dtype=np.float32)
# ... 用相机 / MediaPipe / VR 采集填入 keypoints

joint_angles = session.step(keypoints)   # numpy.ndarray (20,)

切换数据源（重新对齐时序、丢弃旧帧）调 session.reset() 清空 warm-start 与低通滤波内部状态。

API 参考

创建 session

类方法 RetargetSession.for_hand(hand_model, side)，按设备型号绑定内置配置。

参数	类型	说明
`hand_model`	`HandModel`	目标手型：`HandModel.WujiHand` 或 `HandModel.WujiHand2`
`side`	`Handedness`	手性：`Handedness.Left` 或 `Handedness.Right`

单帧重定向

session.step(keypoints) 对单帧关键点跑一次重定向。

参数	类型	说明
`keypoints`	`np.ndarray`	形状 `(21, 3)` 的 float32 数组（或 63 元素行主序展平），按 MediaPipe landmark 顺序，单位米

返回 np.ndarray 形状 (20,) float32，可直接发设备。

重置状态

session.reset() 清空 warm-start 与低通滤波器状态。切换数据源或长时间停顿后再开始时调用。

输入格式

step 入参遵循 MediaPipe Hands landmark 约定，21 个点按固定顺序（wrist / 五指 × 4 关节），坐标系单位为米。任何能产出该格式的来源都可接入：摄像头 + MediaPipe、Wuji Glove 的 hand_skeleton 订阅、VR 手部追踪等。

实时遥操作示例

RetargetSession 是纯重定向接口，遥操作（从实时关键点流驱动手部）是基于该接口的应用层模式。完整示例见 wuji-sdk 仓 examples/python/ 下的 retargeting/ 子目录（Wuji Glove 输入 → 重定向 → 驱动 Wuji Hand 2 / Wuji Hand）。

订阅实时关键点流时建议每帧 drain 到最新一帧再喂给 step，避免取到老帧导致延迟累积。

Teleop 推荐用默认 SDK 用户

Teleop 推荐用默认 SDK 用户运行：默认用户的 glove 跑在 SDK 内置默认 hand URDF 上，目前比 per-user IK 标定更稳定。示例 1.teleop_real.py 在连接 glove 前主动 manager.switch_to_default_user()，退出时再还原切换前的用户。

若内置 URDF 在你的手上跟踪效果不佳，先创建一个具名 SDK 用户，切到该用户后做 glove 标定（默认用户下标定无效，详见 SDK 用户管理与标定）。

平台与限制

仅支持 Linux x86_64 与 Linux aarch64。macOS / Windows / 其它架构暂不分发预编译 wheel。
算法原生内置于 SDK，无需额外下载。运行时依赖仅 numpy（用于关键点/qpos 数组）。