---
tags:
- ml-intern
---
# EyeGuard 20-20-20 👁️

A robust computer-vision application that enforces the **20-20-20 rule** for eye health — with **anti-spoofing** protection against one-eye-closed tricks.

## The 20-20-20 Rule
- Every **20 minutes** of screen time
- Look at something **20 feet away**
- For at least **20 seconds**

## Features

### Core Functionality
- **Real-time webcam eye tracking** using MediaPipe Face Mesh (468 landmarks)
- **Per-eye EAR (Eye Aspect Ratio) calculation** — each eye tracked independently
- **20-minute timer** with visual countdown
- **20-second rest enforcement** — both eyes must stay closed
- **Blink filtering** — brief blinks (< 0.5s) don't count as rest

### Anti-Spoofing / Anti-Cheating
- **One-eye-closed trick = DETECTED** — requires BOTH eyes closed simultaneously for the full 20 seconds
- **Face disappearance detection** — if the face leaves the camera during rest, the rest attempt fails
- **Hysteresis thresholds** — prevents flickering between open/closed states
- **Temporal smoothing** — median filter over 5 frames for stable EAR readings
- **Geometric verification** — uses facial landmark geometry, not just single-frame classification

### State Machine
1. **SCREENING** — Normal work, counting down 20 minutes
2. **ALERT** — Time for a break! Flashing red banner asks user to close both eyes
3. **RESTING** — Both eyes confirmed closed, counting 20 seconds
4. **REST_COMPLETE** — Break finished successfully, timer resets
5. **SPOOFING** — One-eye trick detected! 3-second penalty before retry
6. **NO_FACE** — Face not visible, waiting for user

## Requirements

```bash
pip install opencv-python-headless mediapipe==0.10.13 numpy
```

## Usage

### Basic Usage (default webcam)
```bash
python eye_guard_2020.py
```

### Different Camera
```bash
python eye_guard_2020.py --camera 1
```

### Adjust Sensitivity
```bash
python eye_guard_2020.py --ear-open 0.18 --ear-closed 0.12
```

### Key Controls (during runtime)
- `q` — Quit
- `r` — Reset the 20-minute timer
- `t` — Test mode (force alert immediately)

## How It Works

### Eye Aspect Ratio (EAR)
```
EAR = (||P2-P6|| + ||P3-P5||) / (2 * ||P1-P4||)
```

**Open eye**: EAR ≈ 0.25–0.35  
**Closed eye**: EAR ≈ 0.05–0.15

### Hysteresis
- Eye is **closed** only when EAR drops below `ear_closed` (default 0.18)
- Eye is **open** only when EAR rises above `ear_open` (default 0.22)
- This 0.04 gap provides stable state transitions

### Blink Rejection
A closure must last at least **15 consecutive frames** (~0.5s at 30fps) to count as "resting". Normal blinks (100–300ms) are filtered out.

### One-Eye Trick Detection
During RESTING, if either eye re-opens while the other stays closed:
1. Status immediately switches to **SPOOFING**
2. The rest attempt is marked as **failed**
3. A 3-second penalty is enforced
4. The user must start the 20-second rest over

## Testing

```bash
python test_eyeguard_synthetic.py
```

Tests cover:
1. ✅ Normal rest cycle (both eyes closed)
2. ✅ Spoofing detection (one eye closed)
3. ✅ Blink filtering (brief closures ignored)
4. ✅ Rest interruption (early opening)
5. ✅ No-face detection during rest
6. ✅ One-eye trick during alert phase

## Why This Approach?

Our geometric approach **cannot be fooled by closing one eye** because it computes EAR for each eye independently and enforces an **AND gate** — both must be closed. This is fundamentally more robust than deep-learning classifiers that operate on whole-face images and can be confused by partial closures.

## Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `ear_open` | 0.22 | EAR threshold to mark eye as open |
| `ear_closed` | 0.18 | EAR threshold to mark eye as closed |
| `SCREEN_TIME_ALERT_SECONDS` | 1200 | 20 minutes in seconds |
| `REST_DURATION_SECONDS` | 20 | Rest duration in seconds |
| `MIN_CONSECUTIVE_CLOSED_FRAMES` | 15 | Minimum frames (~0.5s) to count as rest start |

## License

MIT — free for personal and commercial use. Protect your eyes! 👀

<!-- ml-intern-provenance -->
## Generated by ML Intern

This model repository was generated by [ML Intern](https://github.com/huggingface/ml-intern), an agent for machine learning research and development on the Hugging Face Hub.

- Try ML Intern: https://smolagents-ml-intern.hf.space
- Source code: https://github.com/huggingface/ml-intern