| --- |
| 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 |
|
|
