Hand Tracking Module

A powerful and easy-to-use Python package for real-time hand detection and tracking using MediaPipe and OpenCV. This module provides a simple interface to detect hands, track hand landmarks, and perform gesture recognition through your webcam.

Features

• Real-time Hand Detection: Detect up to 2 hands simultaneously
• Hand Landmark Tracking: Get precise coordinates of 21 hand landmarks
• Finger Counting: Detect which fingers are up/down
• Distance Measurement: Calculate distances between landmarks
• Bounding Box Detection: Get hand bounding boxes
• Customizable Parameters: Adjust detection confidence and tracking sensitivity
• Easy Integration: Simple API for quick integration into your projects

Installation

Install the package using pip:

pip install tanay

Requirements

• Python 3.8+
• OpenCV
• MediaPipe
• NumPy

These dependencies will be automatically installed when you install the package.

Quick Start

Here's a simple example to get you started:

import cv2
from tanay.HandTrackingModule import handDetector

# Initialize the hand detector
detector = handDetector()

# Start video capture
cap = cv2.VideoCapture(0)

while True:
    success, img = cap.read()
    
    # Find hands in the image
    img = detector.findHands(img)
    
    # Get hand landmarks
    lmList, bbox = detector.findPosition(img)
    
    # Check if hands are detected
    if len(lmList) != 0:
        # Get finger status (which fingers are up)
        fingers = detector.fingersUp()
        print(f"Fingers up: {fingers}")
        
        # Count total fingers up
        totalFingers = fingers.count(1)
        print(f"Total fingers: {totalFingers}")
    
    cv2.imshow("Hand Tracking", img)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

API Reference

Class: handDetector

Constructor

handDetector(mode=False, maxHands=2, detectionCon=0.5, trackCon=0.5)

Parameters:

• mode (bool): Static image mode. If False, treats input as video stream
• maxHands (int): Maximum number of hands to detect (1-2)
• detectionCon (float): Minimum detection confidence (0.0-1.0)
• trackCon (float): Minimum tracking confidence (0.0-1.0)

Methods

findHands(img, draw=True)

Detects hands in the image and optionally draws landmarks.

Parameters:

• img: Input image (BGR format)
• draw (bool): Whether to draw hand landmarks

Returns:

• Modified image with hand landmarks drawn (if draw=True)

findPosition(img, handNo=0, draw=True)

Gets the positions of hand landmarks.

Parameters:

• img: Input image
• handNo (int): Hand index (0 for first hand, 1 for second)
• draw (bool): Whether to draw landmark points

Returns:

• lmList: List of landmark positions [[id, x, y], ...]
• bbox: Bounding box coordinates [xmin, ymin, xmax, ymax]

fingersUp()

Determines which fingers are extended upward.

Returns:

• List of 5 integers (0 or 1) representing finger status [thumb, index, middle, ring, pinky]

findDistance(p1, p2, img, draw=True, r=15, t=3)

Calculates distance between two landmarks.

Parameters:

• p1, p2 (int): Landmark IDs
• img: Input image
• draw (bool): Whether to draw the distance line
• r (int): Circle radius for endpoints
• t (int): Line thickness

Returns:

• length: Distance between points
• img: Image with distance visualization
• [x1, y1, x2, y2, cx, cy]: Coordinates of points and center

Hand Landmark IDs

The hand landmarks follow MediaPipe's convention:

Wrist: 0
Thumb: 1, 2, 3, 4
Index: 5, 6, 7, 8
Middle: 9, 10, 11, 12
Ring: 13, 14, 15, 16
Pinky: 17, 18, 19, 20

Examples

Example 1: Finger Counting

import cv2
from tanay.HandTrackingModule import handDetector

detector = handDetector()
cap = cv2.VideoCapture(0)

while True:
    success, img = cap.read()
    img = detector.findHands(img)
    lmList, bbox = detector.findPosition(img, draw=False)
    
    if len(lmList) != 0:
        fingers = detector.fingersUp()
        totalFingers = fingers.count(1)
        
        # Display finger count
        cv2.putText(img, f'Fingers: {totalFingers}', (10, 70), 
                   cv2.FONT_HERSHEY_PLAIN, 3, (255, 0, 0), 3)
    
    cv2.imshow("Finger Counter", img)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

Example 2: Distance Measurement

import cv2
from tanay.HandTrackingModule import handDetector

detector = handDetector()
cap = cv2.VideoCapture(0)

while True:
    success, img = cap.read()
    img = detector.findHands(img)
    lmList, bbox = detector.findPosition(img, draw=False)
    
    if len(lmList) != 0:
        # Distance between thumb tip and index tip
        length, img, lineInfo = detector.findDistance(4, 8, img)
        print(f"Distance: {length}")
    
    cv2.imshow("Distance Measurement", img)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

Applications

This hand tracking module can be used for:

• Gesture Recognition: Build gesture-controlled applications
• Virtual Mouse: Control mouse cursor with hand movements
• Sign Language Recognition: Detect and interpret sign language
• Augmented Reality: Add virtual objects that interact with hands
• Accessibility Tools: Create hands-free interfaces
• Games: Hand-controlled gaming experiences
• Art and Creative Tools: Digital painting with hand gestures

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Tanay Baviskar

• Email: tanaybaviskar@gmail.com

Acknowledgments

• MediaPipe for the hand tracking solution
• OpenCV for computer vision functionality

Changelog

Version 0.1.1

• Initial release
• Basic hand detection and tracking functionality
• Finger counting capability
• Distance measurement between landmarks
• Bounding box detection

⭐ If you found this package helpful, please give it a star on PyPI!