Documentation Guide

GitHub Repositories and Documentation Entry

The table below summarizes Wuji Retargeting repositories and applicable scenarios.

Repository	Version	Use Case	Applies To
wuji-retargeting		Human hand motion retargeting for teleoperation	Wuji Hand 2 (Beta 1) Wuji Hand Wuji Glove

Wuji Retargeting version updates and changes

System requirements, dependency setup, and Apple Vision Pro configuration

System Requirements
The system uses a unified MediaPipe keypoint format as input. Current public examples support Vision Pro, replay data, MP4 video, and Intel RealSense. Beyond that, you can integrate Pico, Meta Quest, or other image-based hand-tracking solutions for custom development.
Installation Guide
Use the --recurse-submodules flag to pull the Wuji Hand URDF model submodule.

How to run simulation demos and real-hand teleoperation, with command reference

Real Hardware Control
Linux USB Permissions: Wuji Hand communicates via USB serial. Linux restricts serial device access for regular users by default. We recommend adding your user to the dialout group: sudo usermod -aG dialout $USER (requires logout/login). sudo chmod a+rw /dev/ttyUSB0 is only for temporary troubleshooting and resets after reboot.
Command Reference
teleop_sim.py (Simulation), teleop_real.py (Real Hardware)

tuning_tool usage, segment_scaling, parameter cheatsheet, and tuning order

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.
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 groups
Parameters under retarget fall into five groups:
Parameter quick reference
Recommended tuning order

Retargeter usage, I/O formats, and configuration parameter docs

Basic Usage
Input Format
Input data is MediaPipe format hand keypoints with shape (21, 3), containing 3D coordinates for 21 keypoints (unit: meters). Regardless of whether the source is Vision Pro, replay data, MP4 video, or Intel RealSense, the input pipeline ultimately normalizes the data into this format.
Output Format
Output is a length-20 joint angle array (radians), corresponding to Wuji Hand's 20 joints:
Configuration File
The example above reflects the default Vision Pro configuration style. For MediaPipe vision sources such as video and RealSense, use the dedicated adaptive_analytical_video.yaml configuration.
Configuration by Input Mode
Driving a Custom Dexterous Hand
Three keys under the optimizer block point the same retargeting algorithm at different hand models without code changes:
video_input Parameters
adaptive_analytical_video.yaml also includes a video_input section for preprocessing video and RealSense input:
Parameter Descriptions
Default configuration is tuned for Apple Vision Pro. For MP4 video and Intel RealSense, start with adaptive_analytical_video.yaml, then adjust scaling, segment_scaling, and video_input parameters based on hand size and image conditions.
Hand Size Adaptation
If retargeting results are poor, adjust the following parameters:

Adaptive optimization algorithm, troubleshooting, and related resources

For technical support or any questions, please contact us: support@wuji.tech