somehand

Universal dexterous-hand retargeting with MediaPipe, MuJoCo, and configurable YAML hand models.
Turn human hand motion into robot-hand targets — visualize in MuJoCo, replay offline, or drive real hardware.

English Docs • 中文文档 • Getting Started • CLI • API

---

What It Does

• Retarget hand motion from webcam, video, PICO Bridge, hc_mocap UDP, or saved recordings.
• View results in MuJoCo, run MuJoCo sim, or drive supported real hardware.
• Switch hand models through YAML configs; large runtime assets are downloaded separately.

---

Supported Hand Models

Company	Model	DoF	Joints
LinkerHand	L6	6	11
LinkerHand	L10	10	20
LinkerHand	L20	16	21
LinkerHand	L20 Pro	17	21
LinkerHand	L21	17	17
LinkerHand	L25	21	21
LinkerHand	L30	20	20
LinkerHand	LHG20	16	21
LinkerHand	O6	6	11
LinkerHand	O7	7	17
LinkerHand	T12	14	19
DexRobot	DexHand021	20	20
Unitree	Dex5	20	20
Inspire	DFQ	6	12
Inspire	FTP	6	12
AGIBOT	OmniHand	10	16
BrainCo	Revo2	6	11
OYMotion	RoHand	6	25
Sharpa	Wave 01	22	22
Wuji	Wuji Hand	20	20

Use configs/retargeting/{left,right,bihand} as the source of truth for current side and bi-hand availability.

---

CLI Quick Start

git submodule update --init --recursive
pip install -e .
python scripts/setup/download_assets.py --only mjcf mediapipe examples
somehand replay --recording recordings/pico_right.pkl

API Quick Start

See API Usage for stable imports, one-step retargeting, and session orchestration.

For a live camera check:

somehand webcam

Render a recording to MP4:

somehand dump-video \
    --recording recordings/webcam_hand.pkl \
    --output recordings/webcam_hand_replay.mp4

---

Documentation

Start with the task you need:

Task	English	中文
Set up and run once	Getting Started	快速开始
Run from the terminal	CLI Usage	CLI 用法
Embed retargeting in Python	API Usage	API 用法
Choose or edit a hand model config	Configuration	配置说明
Download assets or check supported models	Assets & Models	资产与模型

Full indexes: English / 中文.

License

Apache 2.0