data/README.md

# data/

Raw collected session data used for model training and evaluation.

## 1. Contents

Each `collected_<name>/` folder contains `.npz` files for one participant:

| Folder | Participant | Samples |
|--------|-------------|---------|
| `collected_Abdelrahman/` | Abdelrahman | 15,870 |
| `collected_Jarek/` | Jarek | 14,829 |
| `collected_Junhao/` | Junhao | 8,901 |
| `collected_Kexin/` | Kexin | 32,312 (2 sessions) |
| `collected_Langyuan/` | Langyuan | 15,749 |
| `collected_Mohamed/` | Mohamed | 13,218 |
| `collected_Yingtao/` | Yingtao | 17,591 |
| `collected_ayten/` | Ayten | 17,621 |
| `collected_saba/` | Saba | 8,702 |
| **Total** | **9 participants** | **144,793** |

## 2. File Format

Each `.npz` file contains:

| Key | Shape | Description |
|-----|-------|-------------|
| `features` | (N, 17) | 17-dimensional feature vectors (float32) |
| `labels` | (N,) | Binary labels: 0 = unfocused, 1 = focused |
| `feature_names` | (17,) | Column names for the 17 features |

## 3. Feature List

`ear_left`, `ear_right`, `ear_avg`, `h_gaze`, `v_gaze`, `mar`, `yaw`, `pitch`, `roll`, `s_face`, `s_eye`, `gaze_offset`, `head_deviation`, `perclos`, `blink_rate`, `closure_duration`, `yawn_duration`

10 of these are selected for training (see `data_preparation/prepare_dataset.py`).

## 4. Collection

```bash
python -m models.collect_features --name yourname
```

1. Webcam opens with live overlay
2. Press **1** = focused, **0** = unfocused (switch every 10–30 sec)
3. Press **p** to pause/resume
4. Press **q** to stop and save