调参指南

Retargeting 参数配置文件位于本仓库 example/config/ 路径下，按手型选择对应文件：

所有可调参数都在 YAML 的 retarget 块下。所有参数调整都建议先启动 tuning_tool.py，再修改 YAML，保存后通过可视化结果确认效果。优先调整几何修正 segment_scaling。

tuning_tool 启动和使用方法

tuning_tool.py 是调参时的主要观察工具，同步显示数采手套收集的手部运动和 Wuji Hand 的运动以及其中的映射关系，查看目标骨架是否合理、Wuji Hand 动作是否符合期望，检查调参效果。

启动方式：

cd example

# 下面所有命令中的 <YOUR_SN> 替换为实际手套序列号后再执行

# === Wuji Hand（默认手型）===
# 不带 --config 时，--wuji-glove 默认加载 config/adaptive_analytical_wuji_glove_<hand>.yaml
python tuning_tool.py --wuji-glove --hand right --glove-sn <YOUR_SN>
python tuning_tool.py --wuji-glove --hand left  --glove-sn <YOUR_SN>

# === Wuji Hand 2 ===
# 必须用 --config 显式指定 wh120 文件，否则会回落到默认 Wuji Hand 配置
python tuning_tool.py --wuji-glove --hand right --glove-sn <YOUR_SN> \
  --config config/adaptive_analytical_wuji_glove_wh120_right.yaml
python tuning_tool.py --wuji-glove --hand left  --glove-sn <YOUR_SN> \
  --config config/adaptive_analytical_wuji_glove_wh120_left.yaml

使用方法：

1. 启动 tuning_tool.py。
2. 打开与启动命令一致的那个 YAML：默认 Wuji Hand 用 adaptive_analytical_wuji_glove_<hand>.yaml，Wuji Hand 2 用 adaptive_analytical_wuji_glove_wh120_<hand>.yaml。
3. 修改 retarget 下的参数并保存。
4. 工具会热加载配置，观察三层 skeleton 的变化。
5. 如果结果变好，再继续小步调整。如果变差，回退上一次修改。

颜色含义：

最常用：segment_scaling

几何缩放：按手指、按目标向量（wrist→PIP / wrist→DIP / wrist→TIP）微调长度，修正某根手指长度与 Wuji Hand 骨架不一致的问题。所有几何修正都通过 segment_scaling 完成。

参数位置：

retarget:
  segment_scaling:
    thumb:  [1.0, 1.0, 1.0]
    index:  [1.0, 1.0, 1.0]
    middle: [1.0, 1.0, 1.0]
    ring:   [1.0, 1.0, 1.0]
    pinky:  [1.05, 1.05, 1.1]

使用建议：

• 某根手指整体偏短、够不到（即青色线段短于白色骨架），调大该手指 3 个值。某根手指过长或过度伸展（即青色线段长于白色骨架），调小该手指 3 个值。
• 保存修改后看青色 target 是否变得跟白色骨架贴合再继续。
• YAML 里另有一个 scaling 字段不是几何缩放，归在「捏合调节」，详见下文，常规保持 1.0。

参数分类

retarget 块下的参数按用途可以分五类：

• 关节权重：w_pos / w_dir / w_full_hand，分别决定算法对"指尖位置 / 指尖朝向 / 整指姿态"的偏好优先级。其中 w_pos / w_dir 主要影响捏合状态下的指尖精度，w_full_hand 主要影响张开手时的整指形状。
• Huber 阈值：huber_delta / huber_delta_dir，控制位置误差和朝向误差从二次惩罚进入线性惩罚的阈值，影响算法对大偏差的敏感程度。
• 软限位 / 姿态约束：thumb_skip_pip / w_hyper / soft_min / w_couple / couple_ratio。其中 thumb_skip_pip 会牺牲大拇指关节贴合度换取整体映射自然度，w_hyper / soft_min 用于减少反向弯曲，w_couple / couple_ratio 把 DIP 弯曲与 PIP 软联动到更像人手的比例。
• 平滑：lp_alpha / norm_delta，抑制输出抖动，前者作用在输出层，后者作用在优化项里。
• 模式 / 捏合调节：pinch_thresholds / scaling / mediapipe_rotation，分别为捏合 / 张开模式切换阈值、捏合状态下指尖目标的整体缩放、输入坐标系微调。

参数速查表

实际调参顺序

1. 先启动 tuning_tool.py，重点观察青色 target 和白色的 Wuji Hand 骨架的变化。
2. 先调 segment_scaling：只修某一根手指偏长 / 偏短的问题，每次只改一根手指。
3. 有抖动再调 lp_alpha / norm_delta：lp_alpha 低一点更稳，norm_delta 高一点更保守。
4. 捏合误触发或不触发，再调 pinch_thresholds.d1/d2：调大 d1/d2 会更早进入捏合模式，提高对指尖捏合的偏好。调小 d1/d2 会更晚进入捏合模式，更偏向保持全手姿态。
5. w_pos / w_dir / w_full_hand / w_hyper / w_couple / couple_ratio 属于算法偏好权重，不建议优先改，除非已经确认几何尺度和平滑参数都没问题。注意 w_pos / w_dir 主要影响捏合状态下的指尖精度，w_full_hand 主要影响张开手时的整指形状。