Python wrapper around Google Mediapipe's Hand Landmark Detection that organizes raw landmark data into usable hand objects with per-finger access, angle calculation, raised finger detection, and more.
Install from PyPI:
pip install handy-hand-trackingIf you want to work from a local checkout instead, you can install it in editable mode:
git clone https://github.com/DwnNyxDev/hand_tracking.git
cd hand_tracking
python -m pip install -e .The bundled hand_landmarker.task model file is included with the package, so no separate download is needed.
A simple example entry point is available after installation that reads in video from your device:
hand-tracking-exampleYou can also run the module directly:
python -m hand_tracking.exampleExample import usage:
from hand_tracking.landmark_detector import LiveLandmarkDetectorRepresents a single detected hand with landmark positions and gesture utilities.
from hand_tracking.hands import HandAttributes:
side(str):"Left"or"Right".wrist(tuple):(x, y, z)normalized coordinates of the wrist landmark.fingers(dict): Maps finger names to arrays of 4 landmark points each. Keys:"thumb","index","middle","ring","pinky".
Methods:
get_raised_fingers() → list[str] — Returns the names of fingers that are currently extended (not bent).
raised = hand.get_raised_fingers()
# e.g. ["index", "middle"]calculate_finger_angle(finger_name) → float — Returns the angle (in radians) of the given finger relative to the image axes.
angle = hand.calculate_finger_angle("index")Add to your Dockerfile:
RUN pip install handy-hand-trackingThen in your ROS2 node:
from hand_tracking.landmark_detector import LiveLandmarkDetector
from hand_tracking.hands import HandIf docker compose up fails with:
Error response from daemon: error gathering device information while adding custom device "/dev/video0": no such file or directory
You're likely on Windows with WSL2. USB devices aren't available to WSL by default — you need to attach your webcam manually using usbipd.
Open PowerShell as Administrator and run:
usbipd listFind your webcam in the list and note its bus ID (e.g. 2-3).
First time only — bind the device:
usbipd bind --busid 2-3Every restart — attach it to WSL:
usbipd attach --wsl --busid 2-3Binding is a one-time step that persists. Attaching is lost on every Windows restart and must be re-run each session before starting Docker. Then try docker compose up again. If usbipd is not installed, get it from usbipd-win.
mediapipenumpyopencv-python
- hand_controller — ROS 2 package that wraps this library into a node for robot control pipelines
MIT