Hand Tracking

A real-time hand tracking module built with OpenCV and MediaPipe, plus a gesture-based volume controller demo.

Overview

This project provides a reusable handDetector class that wraps MediaPipe's hand landmark detection. It exposes simple methods for detecting hands, reading landmark positions, checking which fingers are raised, and measuring distances between landmarks.

The included demo uses thumb-to-index-finger distance to control system volume in real time.

Files

File	Description
HandTrackingModule.py	Full-featured reusable module
HandTrackingMin.py	Minimal version of the module
testing.py	Gesture-based volume controller (Windows only)
test.py	Early prototype / scratchpad

Requirements

• Python 3.x
• OpenCV
• MediaPipe

pip install opencv-python mediapipe

For the volume controller demo (Windows only):

pip install pycaw comtypes

Usage

As a module

import cv2
import HandTrackingModule as htm

cap = cv2.VideoCapture(0)
detector = htm.handDetector(detectionCon=0.7)

while True:
    success, img = cap.read()
    img = detector.findHands(img)
    lmList, bbox = detector.findPosition(img)

    if lmList:
        fingers = detector.fingersUp()
        print(fingers)  # e.g. [1, 0, 0, 0, 0] = only thumb up

    cv2.imshow("Image", img)
    cv2.waitKey(1)

handDetector API

detector = handDetector(
    mode=False,        # Static image mode (False = video stream)
    maxHands=2,        # Maximum number of hands to detect
    detectionCon=0.5,  # Minimum detection confidence
    trackCon=0.5       # Minimum tracking confidence
)

Method	Returns	Description
findHands(img, draw=True)	img	Detects hands and optionally draws landmarks
findPosition(img, handNo=0, draw=True)	(lmList, bbox)	Returns list of [id, x, y] for each of the 21 landmarks, plus bounding box
fingersUp()	list[int]	Returns [thumb, index, middle, ring, pinky] — 1 if up, 0 if down
findDistance(p1, p2, img, draw=True)	(length, img, coords)	Euclidean distance between two landmark IDs

Landmark IDs

MediaPipe detects 21 landmarks per hand. Key ones:

4  = Thumb tip
8  = Index finger tip
12 = Middle finger tip
16 = Ring finger tip
20 = Pinky tip

Full landmark map: MediaPipe Hands documentation

Volume Controller (Windows only)

Run testing.py to control system volume with your hand:

• Pinch thumb and index finger together → minimum volume
• Spread them apart → maximum volume
• A volume bar is drawn on screen showing the current level

python testing.py

Note: The volume controller uses the Windows Core Audio API via pycaw and will not run on macOS or Linux.

Camera Index

Scripts default to camera index 1. If your webcam is not detected, change cv2.VideoCapture(1) to cv2.VideoCapture(0).

License

MIT