Tuning Guide

Retargeting parameter config files live under example/config/ — pick the file that matches your hand model:

All tunable parameters sit under the retarget block in the YAML. For any change, start tuning_tool.py first, then edit the YAML, save, and confirm the result visually. Tune the geometric correction segment_scaling first.

Start and use tuning_tool

tuning_tool.py is the main observation tool during tuning. It shows hand motion captured by the data glove alongside Wuji Hand motion and the mapping between them, so you can see whether the target skeleton is reasonable and whether Wuji Hand follows the expected pose.

Launch:

cd example

# Replace <YOUR_SN> in all commands below with your glove serial number before running

# === Wuji Hand (default) ===
# Without --config, --wuji-glove loads 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 ===
# Pass --config explicitly to the wh120 file, otherwise it falls back to the default Wuji Hand config
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

Workflow:

1. Start tuning_tool.py.
2. Open the YAML that matches the launch command: the default Wuji Hand uses adaptive_analytical_wuji_glove_<hand>.yaml, Wuji Hand 2 uses adaptive_analytical_wuji_glove_wh120_<hand>.yaml.
3. Edit parameters under retarget and save.
4. The tool hot-reloads the config. Watch the three-layer skeleton change.
5. If the result improves, keep adjusting in small steps. If it gets worse, revert the last change.

Color legend:

Most common: segment_scaling

Geometric scaling. Adjusts target vector length per finger (wrist→PIP, wrist→DIP, wrist→TIP) to fix mismatches between a finger and the Wuji Hand skeleton. All geometric correction goes through segment_scaling.

Parameter location:

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]

Tips:

• If a finger looks too short and can't reach (cyan shorter than the white skeleton), raise its three values. If a finger overshoots or hyperextends (cyan longer than white), lower the three values.
• Save, watch whether cyan target snaps onto the white skeleton, then continue.
• The YAML also has a scaling field that is not geometric. It belongs to pinch tuning (see below) and normally stays at 1.0.

Parameter groups

Parameters under retarget fall into five groups:

• Joint weights: w_pos / w_dir / w_full_hand control the algorithm's preference for fingertip position, fingertip direction, and full-finger pose respectively. w_pos / w_dir mainly affect fingertip accuracy during pinch, while w_full_hand mainly affects open-hand pose.
• Huber thresholds: huber_delta / huber_delta_dir control where position error and direction error transition from quadratic to linear penalty, governing the algorithm's sensitivity to large deviations.
• Soft limits / pose constraints: thumb_skip_pip / w_hyper / soft_min / w_couple / couple_ratio. thumb_skip_pip trades some thumb-joint fidelity for more natural overall mapping. w_hyper / soft_min reduce hyperextension. w_couple / couple_ratio softly couple DIP flexion to PIP at a human-like ratio.
• Smoothing: lp_alpha / norm_delta suppress output jitter. The former acts on the output layer, while the latter acts inside the optimization objective.
• Mode / pinch tuning: pinch_thresholds / scaling / mediapipe_rotation cover the pinch / open-hand mode switch threshold, the global scale of the fingertip target during pinch, and a fine rotation on the input coordinate system.

Parameter quick reference

Recommended tuning order

1. Start tuning_tool.py and focus on how the cyan target lines up against the white Wuji Hand skeleton.
2. Tune segment_scaling first: fix one finger at a time when it looks too long or too short.
3. If output jitters, tune lp_alpha / norm_delta. Lower lp_alpha is steadier, higher norm_delta is more conservative.
4. If pinch triggers too easily or not at all, tune pinch_thresholds.d1/d2. Larger d1/d2 enters pinch sooner and prefers fingertip pinch. Smaller values enter pinch later and prefer the full-hand pose.
5. w_pos / w_dir / w_full_hand / w_hyper / w_couple / couple_ratio are algorithm-preference weights. Avoid changing them first unless geometric scale and smoothing are already correct. Remember that w_pos / w_dir mainly affect fingertip accuracy in pinch and w_full_hand mainly affects open-hand pose.