Metadata-Version: 2.4
Name: aeropuzzle
Version: 0.1.0
Summary: A gesture-controlled sliding puzzle game using real-time hand tracking.
Author: Aarthirt14
License-Expression: MIT
Project-URL: Homepage, https://github.com/Aarthirt14/AeroPuzzle
Project-URL: Repository, https://github.com/Aarthirt14/AeroPuzzle
Project-URL: Issues, https://github.com/Aarthirt14/AeroPuzzle/issues
Keywords: puzzle,gesture,hand-tracking,mediapipe,opencv,computer-vision
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment :: Puzzle Games
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-python>=4.8
Requires-Dist: mediapipe>=0.10
Requires-Dist: numpy>=1.24
Requires-Dist: pillow>=10.0
Dynamic: license-file

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