# AeroPuzzle

A real-time, gesture-controlled sliding puzzle game powered by computer vision and hand tracking. Create puzzles from your webcam feed and solve them using air gestures — no mouse or touch input required.

---

## Features

- **Gesture-Controlled Gameplay** — Use hand gestures to grab, drag, and swap puzzle tiles in real time.
- **Live Webcam Integration** — Capture a snapshot from your webcam to create the puzzle.
- **Adaptive Hand Tracking** — Powered by MediaPipe Hand Landmarker with dual-threshold hysteresis filtering.
- **Velocity-Adaptive Smoothing** — 1€ filter eliminates jitter while keeping the cursor responsive.
- **Premium HUD Overlay** — Sleek header, status indicators, timer, and victory card rendered directly on the video feed.
- **Auto-Termination** — Automatically closes 5 seconds after puzzle completion.

---

## Screenshots

<!-- Add screenshots here -->

---

## Installation

### From PyPI

```bash
pip install aeropuzzle
```

### From Source

```bash
git clone https://github.com/Aarthirt14/AeroPuzzle.git
cd AeroPuzzle
pip install .
```

---

## Usage

### Launch the game

```bash
aeropuzzle
```

Or using the Python module syntax:

```bash
python -m aeropuzzle
```

### Command-line options

```bash
aeropuzzle --help       # Show usage information
aeropuzzle --version    # Show version number
```

---

## How to Play

1. **Webcam Active** — Ensure your webcam is connected and allowed.
2. **Frame Your Photo** — Position both hands in front of the camera and spread your index fingers to define the crop area.
3. **Capture Snapshot** — Pinch your index finger and thumb together to capture the snapshot and start the puzzle.
4. **Solve the Puzzle**:
   - Move your hand to control the pointer cursor.
   - Pinch to grab a tile.
   - Drag the tile to its correct position.
   - Release the pinch to swap it with another tile.
5. **Win** — Solve the puzzle to see your completion time. The application automatically closes 5 seconds after solving.

---

## Requirements

- Python 3.10+
- A working webcam
- Dependencies (installed automatically via pip):
  - `opencv-python`
  - `mediapipe`
  - `numpy`
  - `pillow`

---

## Tech Stack

| Component | Technology |
|---|---|
| Language | Python 3.10+ |
| Computer Vision | OpenCV |
| Hand Tracking | MediaPipe (Tasks-Vision API) |
| Typography | Pillow (PIL) |
| Numerical Computing | NumPy |

---

## Development

```bash
git clone https://github.com/Aarthirt14/AeroPuzzle.git
cd AeroPuzzle
pip install -e .
```

### Build the package

```bash
pip install build
python -m build
```

### Publish to PyPI

```bash
pip install twine
twine upload dist/*
```

---

## License

This project is licensed under the [MIT License](LICENSE).