Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ The score is the share of focused frames in a sliding window. A nudge fires only

The sensitivity slider moves the threshold. If you study from paper on your desk, looking down may count as looking away. In that case, lower the sensitivity.

The approach follows [Driver-State-Detection](https://github.com/e-candeloro/Driver-State-Detection) by Ettore Candeloro (MIT). [The design spec](docs/superpowers/specs/2026-10-13-focusguard-design.md) has the exact numbers.
The approach follows [Driver-State-Detection](https://github.com/e-candeloro/Driver-State-Detection) by Ettore Candeloro (MIT). [How FocusGuard scores focus](docs/focus-scoring.md) has the exact numbers.

## For developers

Expand Down
53 changes: 53 additions & 0 deletions docs/focus-scoring.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# How FocusGuard scores focus

The camera and Vision code only produce numbers about your face. Everything below runs in `Sources/FocusCore/FocusScorer.swift`, has no camera or UI code, and is covered by `swift run focus-check`. The thresholds live in one place in that file (`ScorerParams` and `Knobs`) and are meant as calibration knobs.

## Signals

Each camera frame (about 10 per second) goes through Apple's Vision framework: `VNDetectFaceLandmarksRequest` for the eye contours and pupils, plus the face's yaw, pitch and roll. That gives the eye aspect ratio (EAR), the pupil offset inside the eye, and the head pose.

## Why not an end-to-end "focus %" model

End-to-end engagement models trained on DAiSEE reach about 60–73 % accuracy even in papers and generalize poorly. The established approach is pretrained face and landmark models plus transparent scoring, which is what [Driver-State-Detection](https://github.com/e-candeloro/Driver-State-Detection) (MIT) does and what FocusGuard follows.

## Calibration
The first 10 s of each study phase record the user's baseline: neutral `yaw`/`pitch` (camera may sit low or to the side) and baseline EAR. All later checks use deltas from the baseline.

## Per-frame state

Each frame gets exactly one of these states:

- `absent`: no face found.
- `eyesClosed`: EAR < 0.7 × baseline EAR, sustained for > 0.5 s. Ordinary blinks never count.
- `lookingAway`: |Δyaw| > 25°, or |Δpitch| > 20°, or pupil offset within the eye > 0.35.
- `focused`: otherwise.
- Frames with low Vision confidence are skipped (neither focused nor distracted).

## Score
- `focusScore` = percentage of `focused` frames within the sliding window W.
- `smoothedScore` = EMA of `focusScore` for display.
- A 1 s distraction inside a 30 s window lowers the score to ~97%, not 5%.

## Alert rule

A nudge fires only when all four conditions hold:

1. `focusScore` < threshold T continuously for H seconds.
2. The user is still distracted right now: under 50% focused frames in the last 2 s. A windowed score lags, so without this a distraction that already ended could still trigger a bubble.
3. At least C has passed since the last bubble. A continuous distraction therefore gets a reminder every C, never more often.
4. At least 60 s have passed since the study phase started (grace period).

Absence: no face for > 20 s shows one "Where did you go?" bubble; the next one only after the user returns and leaves again. Absent frames count as unfocused in the score.

## Sensitivity slider
One slider (0…1) linearly interpolating between presets; default = Standard (0.5).

| Preset | W | T | H | C |
|---|---|---|---|---|
| Gentle (0.0) | 60 s | 40% | 20 s | 5 min |
| Standard (0.5) | 30 s | 50% | 10 s | 3 min |
| Sensitive (1.0) | 15 s | 60% | 5 s | 90 s |

## Privacy

Camera frames are processed in memory and dropped. Nothing from the camera is written to disk or sent over the network.
157 changes: 0 additions & 157 deletions docs/superpowers/specs/2026-10-13-focusguard-design.md

This file was deleted.

Loading