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 • Runtime Modes • Configuration

---

Highlights

• 20+ hand models — LinkerHand, Inspire, OmniHand, RoHand, Dex5, and more, all driven by YAML configs
• Multiple input sources — webcam (MediaPipe), video file, PICO VR (XRoboToolkit), hc_mocap UDP, saved recordings
• Flexible backends — MuJoCo viewer, MuJoCo sim, or real-hand hardware control
• Bi-hand visualization — side-by-side dual-hand replay and rendering
• Asset-light — large runtime assets hosted externally (ModelScope / HuggingFace), not in Git

---

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

---

Quick Start

1. Install

git submodule update --init --recursive
pip install -e .

2. Download assets

python scripts/setup/download_assets.py

3. Run

somehand replay --recording recordings/pico_right.pkl

You should see a MuJoCo viewer replaying the sample recording.

---

More Examples

Live webcam retargeting

somehand webcam

Replay in MuJoCo sim

somehand replay \
    --backend sim \
    --hand right \
    --config configs/retargeting/right/linkerhand_o6_right.yaml \
    --recording recordings/pico_right.pkl

Render a recording to MP4

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

Offline acceptance check

python scripts/acceptance_check.py \
    --config configs/retargeting/right/linkerhand_l20_right.yaml \
    --video recordings/acceptance.mp4 \
    --hand right

---

Documentation

Full docs covering installation, runtime modes, configuration, assets, and troubleshooting:

Topic	English	中文
Getting Started	getting-started.md	快速开始
Runtime Modes	runtime-modes.md	运行模式
Configuration	configuration.md	配置说明
Assets & Models	assets-and-models.md	资产与模型
Troubleshooting	troubleshooting.md	常见问题
Maintainer Guide	maintainer-guide.md	维护指南

License

Apache 2.0