Real-time hand gesture recognition using MediaPipe and OpenCV. Detects hand landmarks from a webcam feed and classifies gestures with a wireframe skeleton overlay.
The app renders a live wireframe of 21 hand landmarks and displays the recognized gesture in the top-left corner.
Supported gestures: Open Palm · Fist · Peace · Point · Thumbs Up · OK · Rock
- Python 3.11+
- A webcam
- uv (recommended) or pip
git clone git@github.com:sbnet/gesture.git
cd gesture
uv sync # or: pip install -e .On first run the app downloads the MediaPipe hand landmark model (~1 MB) to ~/.cache/hand-wire-demo/.
uv run hand-wire-demo| Flag | Default | Description |
|---|---|---|
--camera, -c |
0 |
Webcam device index |
--width |
1280 |
Frame width |
--height |
720 |
Frame height |
--max-hands |
1 |
Maximum hands to detect simultaneously |
--model-complexity |
1 |
0 = fast, 1 = full accuracy |
--min-detection-confidence |
0.6 |
Detection confidence threshold |
--min-tracking-confidence |
0.5 |
Tracking confidence threshold |
--mirror / --no-mirror |
mirror on | Flip image horizontally |
--debug |
off | Show landmark indices and raw feature values |
# Examples
uv run hand-wire-demo --camera 1 --debug
uv run hand-wire-demo --no-mirror --max-hands 2Press Q or Esc to quit.
uv sync --dev
# Lint & format
uv run ruff check src tests
uv run ruff format src tests
# Type check
uv run mypy src
# Tests
uv run pytest
uv run pytest --cov=hand_wire_demo --cov-report=term-missingCI runs on Python 3.11 and 3.12 via GitHub Actions (lint → format → type check → tests).
MIT — see LICENSE.