models/cnn/CNN_MODEL/README.md

# Eye Open / Closed Classifier (YOLOv11-CLS)


Binary classifier: **open** vs **closed** eyes.  
Used as a baseline for eye-tracking, drowsiness, or focus detection.

---

## Model team task

- **Train** the YOLOv11s-cls eye classifier in a **separate notebook** (data split, epochs, GPU, export `best.pt`).
- Provide **trained weights** (`best.pt`) for this repo’s evaluation and inference scripts.



---

## Repo contents

- **notebooks/eye_classifier_colab.ipynb** — Data download (Kaggle), clean, split, undersample, **evaluate** (needs `best.pt` from model team), export.
- **scripts/predict_image.py** — Run classifier on single images (needs `best.pt`).
- **scripts/webcam_live.py** — Live webcam open/closed (needs `best.pt` + optional `weights/face_landmarker.task`).
- **scripts/video_infer.py** — Run on video files.
- **scripts/focus_infer.py** — Focus/attention inference.
- **weights/** — Put `best.pt` here; `face_landmarker.task` is downloaded on first webcam run if missing.
- **docs/** — Extra docs (e.g. UNNECESSARY_FILES.md if present).

---

## Dataset

- **Source:** [Kaggle — open/closed eyes](https://www.kaggle.com/datasets/sehriyarmemmedli/open-closed-eyes-dataset)
- The Colab notebook downloads it via `kagglehub`; no local copy in repo.

---

## Weights

- Put **best.pt** from the model team in **weights/best.pt** (or `runs/classify/runs_cls/eye_open_closed_cpu/weights/best.pt`).
- For webcam: **face_landmarker.task** is downloaded into **weights/** on first run if missing.

---

## Local setup

```bash
pip install ultralytics opencv-python mediapipe "numpy<2"
```

Optional: use a venv. From repo root:
- `python scripts/predict_image.py <image.png>`
- `python scripts/webcam_live.py`
- `python scripts/video_infer.py` (expects 1.mp4 / 2.mp4 in repo root or set `VIDEOS` env)
- `python scripts/focus_infer.py`

---

## Project structure

```
├── notebooks/
│   └── eye_classifier_colab.ipynb   # Data + eval (no training)
├── scripts/
│   ├── predict_image.py
│   ├── webcam_live.py
│   ├── video_infer.py
│   └── focus_infer.py
├── weights/                     # best.pt, face_landmarker.task
├── docs/                        # extra docs
├── README.md
└── venv/                        # optional
```

Training and weight generation: **model team, separate notebook.**