File size: 4,439 Bytes
9496b2e 7f92554 51216f3 7f92554 51216f3 7f92554 51216f3 7f92554 51216f3 7f92554 51216f3 7f92554 51216f3 7f92554 51216f3 7f92554 9496b2e | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | ---
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
|