Metadata-Version: 2.1
Name: hand-gesture-engine
Version: 0.1.0
Summary: A lightweight hand gesture recognition engine
Home-page: https://github.com/KaranVishwakarma-1807/hand-gesture-engine
Author: Karan Vishwakarma
Author-email: vishwakarmakaran625@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: opencv-python
Requires-Dist: mediapipe
Requires-Dist: numpy

# 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.

## 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

## Project Structure

.</br>
├── examples/</br>
│   ├── demo.py</br>
│   ├── gesture_game.py</br>
│   └── test.py</br>
├── hand_gesture/</br>
│   ├── assests/</br>
│   │   └── hand_landmarker.task</br>
│   ├── __init__.py</br>
│   ├── config.py</br>
│   ├── engine.py</br>
│   ├── gesture.py</br>
│   ├── logging_config.py</br>
│   ├── recognizer.py</br>
│   ├── stabilizer.py</br>
│   ├── tracker.py</br>
│   └── utils.py</br>
├── .gitignore</br>
├── pyproject.toml</br>
└── README.md</br>

## 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
```

to clone the repository:

```bash
git clone https://github.com/KaranVishwakarma-1807/hand-gesture-engine.git
cd gesture-engine
```

## Basic Usage

```
from gesture_engine.engine import GestureEngine
from gesture_engine.config import GestureConfig

engine = GestureEngine(
    backend="AUTO",
    config=GestureConfig()
)

gesture, confidence = engine.process(hand_landmarks)

print(gesture, confidence)
```

## Extending Gestures

To add a new gesture:

- Implement gesture logic in ```gestures.py```
- Register it in ```recognizer.py```
- (Optional) Add config parameters

## Future Ideas

Roadmap

- Gesture smoothing
- Multi-hand support
- Custom gesture training
- Mobile optimization
- ONNX / TensorRT backend

## License

MIT License</br>
Free to use, modify, and distribute.

## Author

Karan Vishwakarma</br>
Built with Python and Mediapipe(Google)

## Credit

https://tree.nathanfriend.com/</br>
Here, you can make you custom project directory trees for the markdown file.</br>
Definietly, check it out, if you want the same.</br>
Very useful!

## Quick Start

```
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

```
backend: AUTO

stability:
  hold_time: 0.35
  min_confidence: 0.6

thresholds:
  pinch: 0.04
  thumb_extended: 0.25
  finger_tolerance: 0.05
```

## Contributing

Pull requests are welcome.</br>
Open an issue for major changes.
