hand-gesture-engine 0.1.1
A lightweight hand gesture recognition engine
Requires Python: >=3.9

# Hand Gesture Engine

A modular, extensible hand gesture recognition engine built in Python using MediaPipe landmarks.
Designed for real-time applications, clean architecture, and easy integration into games, apps, and AI projects.
Perfect for:

- Computer Vision projects
- Gesture-controlled apps
- Games & UI interaction
- esearch & prototyping

## Features

- Modular gesture detection system
- Real-time hand landmark processing
- Centralized gesture recognizer (brain logic)
- Configurable thresholds (pinch, thumb, etc.)
- Built-in logging (debug & production ready)
- CPU / GPU backend auto-selection
- Clean project structure
- YAML configuration support
- Confidence scoring
- Stable public API
- Ready for extension with custom gestures

## Supported Gestrues

| Gesture           | Name Returned |
| ----------------- | ------------- |
| ✊ Fist            | `FIST`        |
| ✋ Open Hand       | `OPEN HAND`   |
| 👍 Thumbs Up      | `THUMBS UP`   |
| 👎 Thumbs Down    | `THUMBS DOWN` |
| ✌ Peace           | `PEACE`       |
| ☝ Pointing        | `POINTING`    |
| 👌 OK             | `OK`          |
| 🤏 Pinch          | `PINCH`       |
| 🖖 Three Fingers | `THREE`       |

## Installation

```bash
pip install mediapipe opencv-python
```

Then:

```bash
pip install hand-gesture-engine==0.1.1
```

## Quick Start

### Sample Code:

```
import cv2
from hand_gesture import GestureEngine, GestureConfig

config = GestureConfig.from_yaml("gesture_config.yaml")
engine = GestureEngine(config=config)

cap = cv2.VideoCapture(0)

while cap.isOpened():
    ret, frame = cap.read()
    if not ret:
        break

    frame, gesture = engine.process(frame)

    if gesture:
        print("Detected:", gesture)

    cv2.imshow("Gesture Engine", frame)
    if cv2.waitKey(1) == 27:
        break
```

### Configuration

<u>**IMPORTANT**</u>:

Add/Create ```gesture_config.yaml``` in the same working directory:
```
backend: AUTO

stability:
  hold_time: 0.35
  min_confidence: 0.6

thresholds:
  pinch: 0.04
  thumb_extended: 0.25
  finger_tolerance: 0.05
```

### GerstureEngine

```
engine = GestureEngine(
    backend="AUTO",  # AUTO | CPU | GPU
    config=config
)
```

<b>
Backends</br>
AUTO - selects best available backend</br>
CPU - forced CPU execution</br>
GPU - uses GPU if supported</br>
</b>

### Logging

Enable logging via config:

```bash
GestureConfig(enable_logging=True)
```

Logs include:

- Backend selection
- Detection failures
- Gesture recognition results

## Future Ideas

Roadmap

- Gesture smoothing
- Multi-hand support
- Custom gesture training
- Mobile optimization
- ONNX / TensorRT backend

## Credit

https://choosealicense.com/</br>
This site helps you choose an open source license for your repository/project.</br>
You can get to know about the licenses and which license to choose.</br>
Very useful! 

## Author

Karan Vishwakarma</br>
Built with Python and Mediapipe(Google)

## License

MIT License</br>
Free to use, modify, and distribute.

## Final Note

If this project helps you:

- Star it on GitHub
- Share it on PyPI
- Build cool gesture-powered apps