Metadata-Version: 2.4
Name: gazecontrol
Version: 0.8.0
Summary: Hand gesture + eye tracking desktop control — point, pinch, drag, resize, gaze
Author: Ciro
License: MIT License
        
        Copyright (c) 2026 Ciro
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: hand-gesture,gesture,accessibility,desktop,pinch
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Adaptive Technologies
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: opencv-python>=4.8.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: PyQt6>=6.4.0
Requires-Dist: pywin32>=306; sys_platform == "win32"
Requires-Dist: mediapipe>=0.10.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: onnxruntime>=1.17.0
Provides-Extra: logging
Requires-Dist: python-json-logger>=2.0; extra == "logging"
Provides-Extra: gpu
Requires-Dist: onnxruntime-gpu>=1.17.0; extra == "gpu"
Provides-Extra: eye
Requires-Dist: eyetrax>=0.4.0; extra == "eye"
Requires-Dist: scikit-learn>=1.3.0; extra == "eye"
Provides-Extra: dev
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: pytest-qt>=4.4.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.4.0; extra == "dev"
Requires-Dist: hypothesis>=6.100.0; extra == "dev"
Requires-Dist: pre-commit>=3.7.0; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Requires-Dist: pip-audit>=2.7.0; extra == "dev"
Requires-Dist: bandit>=1.7.0; extra == "dev"
Requires-Dist: cyclonedx-bom>=4.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Dynamic: license-file

# GazeControl

Desktop control via **hand gestures**. Pinch to click, hold to drag,
two fingers to scroll — all from a webcam.

> Eye tracking (gaze-assisted pointer) is on the roadmap. The code
> path exists behind an optional extra and a startup mode selector,
> but it requires per-user calibration and is not production-ready.

---

## Quick start

```bash
pip install gazecontrol
gazecontrol
```

That's it — webcam in, cursor out. Default mode is **hand-only**;
no calibration required.

---

## Hardware requirements

| Item     | Minimum             |
|----------|---------------------|
| Webcam   | 720p @ 30 fps       |
| OS       | Windows 10 / 11     |
| GPU      | None required       |

Win32-only for now (window manager uses native Windows APIs).

---

## Installation

```bash
# Production
pip install gazecontrol

# Development
git clone https://github.com/<you>/gazecontrol
cd gazecontrol
pip install -e ".[dev]"
pre-commit install
```

Run `gazecontrol --doctor` to verify the camera and dependencies.

---

## Gestures

| Gesture                   | Action                          |
|---------------------------|---------------------------------|
| Index pinch (tap)         | Left click                      |
| Index pinch (held)        | Drag the hovered window         |
| Index pinch in corner     | Resize the hovered window       |
| Two fingers up / down     | Scroll                          |
| Double pinch              | Toggle the app launcher         |

---

## Configuration

Settings load from environment variables (prefix `GAZECONTROL_`,
double underscore for nested groups) and an optional `settings.toml`
in the working directory. See `settings.toml.example` for the full
surface.

```bash
# Example: bump pinch threshold
export GAZECONTROL_INTERACTION__PINCH_DOWN_THRESHOLD=0.04
```

---

## CLI

```text
gazecontrol                       # run hand-only pipeline
gazecontrol --no-overlay          # headless run (no Qt HUD)
gazecontrol --doctor              # probe camera + deps
gazecontrol --dump-config         # dump effective settings as JSON
gazecontrol --benchmark 30        # run 30 s, print per-stage latency
```

---

## Roadmap — eye tracking (experimental)

An `eye-hand` input mode exists behind the `[eye]` extra. It pairs
the hand pipeline with an L2CS-Net + eyetrax gaze ensemble and a
PointerFusionStage that lets gaze drive target selection while hand
keeps click/drag precision.

Status: works on the maintainer's machine but needs per-user
calibration, an unbundled L2CS ONNX model, and tighter drift
correction. Not recommended for end users yet. Track progress in
[docs/architecture.md](docs/architecture.md).

---

## Project layout

```
src/gazecontrol/
├── cli.py                # entry point + doctor + benchmark
├── runtime/              # input mode + pipeline factory
├── pipeline/             # CaptureStage → GestureStage → ...
├── gesture/              # MediaPipe + rule/MLP classifiers
├── interaction/          # InteractionFSM + WindowHitTester
├── filters/              # 1€, Kalman, dead-zone, accel curve
├── overlay/              # PyQt6 HUD
├── window_manager/       # Win32 wrappers
├── gaze/                 # roadmap: eye-tracking backends
└── settings.py           # pydantic-settings
```

See [docs/architecture.md](docs/architecture.md) for the full
diagram and ADRs.

---

## License

GazeControl is released under the **MIT License** — see
[`LICENSE`](LICENSE).

Bundled or downloaded components from third-party projects (L2CS-Net,
MediaPipe Tasks) retain their upstream licenses — see
[`NOTICE.md`](NOTICE.md) for attributions and full text.
