OpenHandTrack — Python

Real-time 3D hand tracking for Python, wrapping MediaPipe's Hand Landmarker task behind a small, clean API — no fighting mediapipe.tasks internals.

• 21 landmarks per hand (x, y, z), up to 2 hands
• Handedness with confidence, mirrored-camera quirk handled for you
• Gesture helpers (is_fist, is_open_palm, is_pinch, …)
• One-Euro smoothing so the tracking feels solid instead of twitchy
• Auto-downloads the model on first use (cached locally, not in git)
• Works on macOS, Windows, Linux — pure stdlib for model download

Install

python3.12 -m venv .venv
.venv/bin/pip install -e "python/[examples]"   # library + example deps

Requires Python 3.11 or 3.12 — MediaPipe does not ship wheels for newer Pythons yet, so on 3.13+ pip install fails with No matching distribution found for mediapipe. Use a 3.11/3.12 interpreter to create the venv.

Hello world

import cv2
from openhandtrack import HandTracker

cap = cv2.VideoCapture(0)
with HandTracker() as tracker:            # model auto-downloads on first run
    while True:
        ok, frame = cap.read()
        if not ok:
            break
        result = tracker.process(frame)   # BGR frame in, clean result out
        print(f"{len(result)} hand(s)", *(h.handedness for h in result))
        cv2.imshow("tracking", frame)
        if cv2.waitKey(1) == ord("q"):
            break
cap.release()

result.hands is empty (never an error) when no hand is in frame.

API at a glance

Full docstrings live in the source (openhandtrack/tracker.py, smoothing.py, gestures.py) — that's the reference.

The mirrored-camera quirk

MediaPipe labels handedness assuming the input image is mirrored (a selfie-style webcam feed). HandTracker defaults to mirrored=True to match the common "mirror your webcam view" setup. If you process unmirrored frames (rear camera, video files), pass mirrored=False and the labels are swapped for you. Hold up your right hand: if it reports Left, flip the flag.

Examples

Short, readable projects that reuse this library — see examples/:

• air_draw/ — pinch to draw in the air, palm to lift, fist to clear; hover the on-screen palette for colours + eraser.
• finger_count/ — counts extended fingers, dots each fingertip.
• peace_selfie/ — hold ✌ for a countdown, saves selfie_N.png.
• virtual_mouse/ — cursor control with the index finger, pinch to click (pynput).
• air_scroll/ — point up/down to scroll pages, fist locks (pynput).
• pinch_ruler/ — live normalized pinch-distance meter; shows why we divide by hand size.
• two_hand_zoom/ — spread/squeeze two hands to zoom; demonstrates max_hands=2.
• volume_control/ — thumb/index spread controls system volume (with a platform-agnostic mock fallback).
• presentation_remote/ — swipe gestures send arrow keys to your slides.

Tests

.venv/bin/python -m pytest python/

License

Apache-2.0 — same as MediaPipe, so you can build on it freely.