Metadata-Version: 2.4
Name: eyetrax
Version: 0.2.2
Summary: Webcam-based eye-tracking
Project-URL: homepage, https://github.com/ck-zhang/eyetrax
Author: Chenkai Zhang (ck-zhang)
License: MIT License
        
        Copyright (c) 2024 ck-zhang
        
        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.
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.9
Requires-Dist: mediapipe>=0.10
Requires-Dist: numpy>=1.22
Requires-Dist: opencv-python>=4.5
Requires-Dist: pyvirtualcam>=0.10
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.10
Requires-Dist: screeninfo>=0.8
Description-Content-Type: text/markdown

# EyePy

![made-with-python](https://img.shields.io/badge/Made%20with-Python-1f425f.svg)
![Open Source Love](https://badges.frapsoft.com/os/v1/open-source.svg?v=103)
![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
![GitHub stars](https://img.shields.io/github/stars/ck-zhang/EyePy.svg?style=social)

![Demo](https://github.com/user-attachments/assets/70819837-c689-4516-8b95-0952500014ff)

EyePy is a Python library that provides **webcam-based eye tracking**.
Extract facial features, train eye tracking model and predict gaze with super easy to use interface.

The repo also includes a virtual camera script allowing integration with streaming software like OBS.

## Installation

Clone this project:
```shell
git clone https://github.com/ck-zhang/EyePy
```

### Using Pip
```shell
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate
pip install -r requirements.txt
```

### Using uv
```shell
# Install uv https://github.com/astral-sh/uv/?tab=readme-ov-file#installation
pip install uv
uv sync
source venv/bin/activate  # On Windows use: venv\Scripts\activate
```

## Demo

To run the gaze estimation demo:

```bash
python demo.py [OPTIONS]
```

### Options

| Option            | Description                                      | Default             |
|-------------------|--------------------------------------------------|---------------------|
| `--filter`        | Filter method (`kalman`, `kde`, `none`)          | `none`              |
| `--camera`        | Index of the camera to use                       | `0`                 |
| `--calibration`   | Calibration method (`9p`, `5p`, `lissajous`)     | `9p`                |
| `--background`    | Path to background image                         | None                |
| `--confidence`    | Confidence interval for KDE contours (0 to 1)    | `0.5`               |

## Virtual Camera Script (only tested on linux)

```bash
python virtual_cam.py [OPTIONS]
```

### Virtual Camera Options

| Option            | Description                                      | Default             |
|-------------------|--------------------------------------------------|---------------------|
| `--filter`        | Filter method (`kalman`, `kde`, `none`)          | `none`              |
| `--camera`        | Index of the camera to use                       | `0`                 |
| `--calibration`   | Calibration method (`9p`, `5p`, `lissajous`)     | `9p`                |
| `--confidence`    | Confidence interval for KDE contours (0 to 1)    | `0.5`               |

### Virtual camera demo

https://github.com/user-attachments/assets/7337f28c-6ce6-4252-981a-db77db5509f6

## Usage as library

### Initialization
```python
from EyePy import GazeEstimator
gaze_estimator = GazeEstimator()
```

### Feature Extraction
```python
import cv2
image = cv2.imread('image.jpg')
features, blink_detected = gaze_estimator.extract_features(image)

if features is None:
    print("No face detected.")
elif blink_detected:
    print("Blink detected!")
else:
    print("Extracted features:", features)
```

### Training the Model
```python
X = [[...], [...], ...]  # Each element is a feature vector
y = [[x1, y1], [x2, y2], ...]  # Corresponding gaze coordinates
gaze_estimator.train(X, y)
```

### Predicting Gaze Location
```python
predicted_gaze = gaze_estimator.predict([features])
print("Predicted gaze coordinates:", predicted_gaze[0])
```

## Future Work

### TODO

- [x] Virtual camera script ~~Integrate with OBS~~
- [ ] Integrate with opentrack

Any suggestions for features and improvements are welcome.

If you enjoyed using EyePy, consider giving it a star.
