Upload README with documentation

README.md

@@ -1,26 +1,117 @@
----
-tags:
-- ml-intern
----
+# EyeGuard 20-20-20 👁️
 
-# HarshCode/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.
 
-<!-- ml-intern-provenance -->
-## Generated by ML Intern
+## The 20-20-20 Rule
+- Every **20 minutes** of screen time
+- Look at something **20 feet away**
+- For at least **20 seconds**
 
-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.
+## Features
 
-- Try ML Intern: https://smolagents-ml-intern.hf.space
-- Source code: https://github.com/huggingface/ml-intern
+### 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
 
-```python
-from transformers import AutoModelForCausalLM, AutoTokenizer
+### 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
 
-model_id = "HarshCode/eyeguard-20-20-20"
-tokenizer = AutoTokenizer.from_pretrained(model_id)
-model = AutoModelForCausalLM.from_pretrained(model_id)
+```bash
+python test_eyeguard_synthetic.py
 ```
 
-For non-causal architectures, replace `AutoModelForCausalLM` with the appropriate `AutoModel` class.
+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! 👀