gesture-hand-tracker 0.1.0

Real-time hand gesture recognition using MediaPipe and machine learning

Hand Tracking

Real-time hand gesture recognition using MediaPipe and machine learning. Detect and classify hand gestures from video input.

Features

• Real-time Hand Detection: Detect hands in video streams using Google's MediaPipe framework
• Gesture Recognition: Classify hand gestures using a pre-trained machine learning model
• Multiple Interfaces: Choose between:
  • Standalone hand tracking with OpenCV
  • Interactive hand-controlled game with Pygame
• Easy to Use: Simple API for integrating hand tracking into your applications
• Flexible: Support for webcams and video files as input

Installation

Basic Installation

Install the hand tracking package:

pip install hand-tracking

With Game Support

To use the hand-controlled game features:

pip install hand-tracking[game]

Development Installation

For development and testing:

git clone <repository-url>
cd hand-tracking
pip install -e ".[dev,game]"

Quick Start

Hand Gesture Recognition

from hand_tracking import HandTracker

# Initialize the tracker
tracker = HandTracker()

# In your video processing loop:
import cv2

cap = cv2.VideoCapture(0)
while True:
    ret, frame = cap.read()
    if not ret:
        break
    
    # Get prediction
    result = tracker.predict_gesture(frame)
    
    # Draw on frame
    frame = tracker.draw_predictions(frame, result)
    
    # Display
    cv2.imshow('Hand Tracking', frame)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

Command Line Usage

Run the hand tracking application:

hand-tracker

Or use the interactive game:

hand-tracking-game

Hand Tracking Game

from hand_tracking import HandTrackingGame

# Create and run the game
game = HandTrackingGame(screen_width=1280, screen_height=720)
game.run()

Gesture Labels

The hand tracker recognizes the following gestures:

• Greeting: Hi
• Letters: A through Y (missing C and Z in current model)

For the game, special direction gestures are used:

• up: Move up
• down: Move down
• left: Move left
• right: Move right

Model

The package includes a pre-trained model (model.p) that was trained on hand landmark data. To use your own model:

tracker = HandTracker(model_path='/path/to/your/model.p')

Requirements

• Python >= 3.8
• OpenCV (opencv-python)
• MediaPipe
• NumPy
• Pygame >= 2.1.0 (for game features)

Project Structure

hand-tracking/
├── src/
│   └── hand_tracking/
│       ├── __init__.py
│       ├── tracker.py       # Main hand tracking module
│       └── game.py          # Hand tracking game
├── tests/
│   ├── __init__.py
│   ├── test_tracker.py
│   └── test_game.py
├── pyproject.toml
├── README.md
├── LICENSE
├── model.p                  # Pre-trained ML model
└── .gitignore

API Reference

HandTracker

Main class for hand gesture recognition.

Methods:

• __init__(model_path=None): Initialize the tracker
• predict_gesture(frame): Predict gesture from a video frame
  • Returns: {character, landmarks, bbox}
• draw_predictions(frame, prediction_result): Draw predictions on frame

Class Attributes:

• LABELS_DICT: Mapping of gesture indices to labels

HandTrackingGame

Interactive game using hand gestures.

Methods:

• __init__(screen_width=1280, screen_height=720, model_path=None): Initialize game
• run(): Run the game loop
• handle_gesture(predicted_character): Process gesture input

Functions:

• run_hand_tracking(video_source=0, model_path=None): Run standalone hand tracking
• main(): Run the game (entry point)

Troubleshooting

Camera Not Opening

• Ensure your webcam is connected
• Check camera permissions (especially on macOS/Linux)
• Try specifying a different camera index: HandTracker(...)

Poor Gesture Recognition

• Ensure adequate lighting
• Keep your hand clearly visible
• Make sure the hand is not too close or too far from the camera
• The model was trained on specific hand positions

Import Errors

• Ensure all dependencies are installed: pip install -e .[dev,game]
• Check Python version >= 3.8

Performance

• Typical latency: 30-50ms per frame on modern hardware
• Tested on: Intel i5+ / AMD Ryzen 5+, with integrated graphics
• FPS: 20-30 FPS typical

License

This project is licensed under the MIT License. See LICENSE for details.

Contributing

Contributions are welcome! Please feel free to fork the repository and submit pull requests.

Citation

If you use this project in your research, please cite:

@software{hand_tracking_2024,
  title={Hand Tracking: Real-time Hand Gesture Recognition},
  author={Hand Tracking Contributors},
  url={https://github.com/TODO/hand-tracking},
  year={2024}
}

Acknowledgments

• MediaPipe by Google for hand detection
• OpenCV for computer vision functionality
• Pygame for game development

Changelog

Version 0.1.0 (2024)

• Initial release
• Hand gesture recognition with MediaPipe
• Multi-hand detection support
• Hand tracking game with Pygame
• Command-line interface