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 @@ -102,7 +102,7 @@ To quit, press **⌘Q** while the desk is open, or right-click the menu bar icon
Each camera frame is classified as one of four states:

- **focused**
- **looking away**: head turned or gaze off center. Each study phase starts with a 10-second calibration, and these are measured against it.
- **looking away**: head turned or gaze off center. Each study phase starts with a 10-second calibration, and these are measured against it. Places you keep looking at, like a second monitor or a laptop beside it, become work zones after about a minute and then count as focused.
- **eyes closed**: closed for longer than 0.5 s, so blinks don't count.
- **absent**: no face in the frame.

Expand Down
66 changes: 58 additions & 8 deletions Sources/FocusCore/FocusScorer.swift
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,51 @@ public enum Knobs {
public static let displaySmoothing = 0.05
/// Baseline needs this many good frames (~3 s at 10 fps) after the calibration time.
public static let calibrationSamples = 30
/// A head pose you held for this long in total over the last `zoneMemory` seconds becomes a work zone (a second screen).
public static let zoneLearnAfter = 60.0
public static let zoneMemory = 600.0
/// Poses further than this above or below the calibrated one are never learned: that is a phone in your lap, not a screen.
public static let zoneMaxPitch = 30.0
}

/// Head poses you keep coming back to: a second monitor, a laptop beside it. Lives across study phases, so a screen
/// learned in round one is still a screen in round two. Poses go into 10° bins; a pose is in a zone when its bin and
/// the bins around it (about ±15°) add up to `zoneLearnAfter` seconds within the last `zoneMemory` seconds.
/// ponytail: frames are counted as 0.1 s each, true at the camera's fixed ~10 fps.
public final class PoseZones {
private struct Bin: Hashable { let yaw: Int, pitch: Int }
private var samples: [(t: Double, bin: Bin)] = []
private var counts: [Bin: Int] = [:]

public init() {}

private static func bin(_ yaw: Double, _ pitch: Double) -> Bin {
Bin(yaw: Int((yaw / 10).rounded()), pitch: Int((pitch / 10).rounded()))
}

private func forget(before t: Double) {
var drop = 0
while drop < samples.count, samples[drop].t < t - Knobs.zoneMemory {
counts[samples[drop].bin]! -= 1
drop += 1
}
if drop > 0 { samples.removeFirst(drop) }
}

public func record(yaw: Double, pitch: Double, at t: Double) {
forget(before: t)
let b = Self.bin(yaw, pitch)
samples.append((t, b))
counts[b, default: 0] += 1
}

public func contains(yaw: Double, pitch: Double, at t: Double) -> Bool {
forget(before: t)
let b = Self.bin(yaw, pitch)
var frames = 0
for dy in -1...1 { for dp in -1...1 { frames += counts[Bin(yaw: b.yaw + dy, pitch: b.pitch + dp)] ?? 0 } }
return Double(frames) * 0.1 >= Knobs.zoneLearnAfter
}
}

/// Turns per-frame face signals into a windowed focus score and rare, non-spammy alerts.
Expand All @@ -88,7 +133,7 @@ public final class FocusScorer {
private let start: Double
private var samples: [(t: Double, focused: Bool)] = []
private var calibration: [FaceSignals] = []
private var baseline: (yaw: Double, pitch: Double, ear: Double)?
private var baseline: (yaw: Double, pitch: Double, ear: Double, gaze: Double)?
private var closedSince: Double?
private var absentSince: Double?
/// Nobody counts as absent before the first face of this stretch: coming back late from a break is not a lapse.
Expand All @@ -99,9 +144,12 @@ public final class FocusScorer {
/// Time of the last frame that counted (not skipped); the app hides the focus figure once this goes stale.
public private(set) var lastFrame: Double?

public init(params: ScorerParams, start: Double) {
private let zones: PoseZones

public init(params: ScorerParams, start: Double, zones: PoseZones = PoseZones()) {
self.params = params
self.start = start
self.zones = zones
}

@discardableResult
Expand Down Expand Up @@ -148,7 +196,8 @@ public final class FocusScorer {
if t - start >= Knobs.calibrationSeconds, calibration.count >= Knobs.calibrationSamples {
// Median, so a glance away during calibration doesn't skew the baseline.
func median(_ values: [Double]) -> Double { values.sorted()[values.count / 2] }
baseline = (median(calibration.map(\.yaw)), median(calibration.map(\.pitch)), median(calibration.map(\.ear)))
baseline = (median(calibration.map(\.yaw)), median(calibration.map(\.pitch)), median(calibration.map(\.ear)),
median(calibration.map(\.gazeOffset)))
calibration = []
}
return .focused
Expand All @@ -162,12 +211,13 @@ public final class FocusScorer {
closedSince = nil
}

if abs(s.yaw - base.yaw) > Knobs.maxYaw
|| abs(s.pitch - base.pitch) > Knobs.maxPitch
|| s.gazeOffset > Knobs.maxGazeOffset {
return .lookingAway
// Every pose that could be a screen is remembered, so a second monitor becomes a zone after a minute or so.
if abs(s.pitch - base.pitch) <= Knobs.zoneMaxPitch { zones.record(yaw: s.yaw, pitch: s.pitch, at: t) }
if abs(s.yaw - base.yaw) > Knobs.maxYaw || abs(s.pitch - base.pitch) > Knobs.maxPitch {
return zones.contains(yaw: s.yaw, pitch: s.pitch, at: t) ? .focused : .lookingAway
}
return .focused
// Relative to calibration: a camera off to the side sees the eye at an angle, so the pupil never sits centred.
return s.gazeOffset - base.gaze > Knobs.maxGazeOffset ? .lookingAway : .focused
}

private func evaluate(at t: Double) -> FocusEvent? {
Expand Down
5 changes: 4 additions & 1 deletion Sources/FocusGuard/AppModel.swift
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,8 @@ final class AppModel: ObservableObject {

let cameraService = CameraService()
let spotify = Spotify()
/// Screens learned from where you look; kept for the whole app run, across study phases.
private let zones = PoseZones()
private var bag = Set<AnyCancellable>()
/// Set by the panel controller: closes the panel (Esc).
var closePanel: () -> Void = {}
Expand Down Expand Up @@ -340,7 +342,8 @@ final class AppModel: ObservableObject {
alerting = false
focusStale = false
if clock.phase.isStudy && !clock.isPaused && !timerOnly {
scorer = FocusScorer(params: .forSensitivity(sensitivity), start: Mono.seconds()) // camera frames carry Mono time too
scorer = FocusScorer(params: .forSensitivity(sensitivity), start: Mono.seconds(), // camera frames carry Mono time too
zones: zones)
focus = 100
calibrating = true
startCamera()
Expand Down
45 changes: 44 additions & 1 deletion Sources/focus-check/main.swift
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ private func check(_ ok: Bool, line: Int = #line) {

private let fps = 10.0
private let look = FaceSignals(faceFound: true, ear: 0.3, gazeOffset: 0.1, yaw: 0, pitch: 0, confidence: 0.9)
private var away: FaceSignals { var s = look; s.yaw = 45; return s }
/// Head well down, like reading a phone in your lap: never learned as a screen, so it always counts as away.
private var away: FaceSignals { var s = look; s.pitch = 45; return s }
private var closed: FaceSignals { var s = look; s.ear = 0.1; return s }

/// Feeds `signal(t)` at 10 fps from 0 to `until` seconds and collects events.
Expand All @@ -28,6 +29,45 @@ private func distraction(from: Double, length: Double) -> (Double) -> FaceSignal
{ t in (from..<(from + length)).contains(t) ? away : look }
}

/// Looking at a laptop 40° to the side: away at first, then a learned work zone.
private var laptop: FaceSignals { var s = look; s.yaw = 40; s.pitch = 12; return s }

/// Feeds `signal` from `from` to `to` seconds at 10 fps.
private func feed(_ scorer: FocusScorer, from: Double, to: Double, _ signal: FaceSignals) {
for i in 0..<Int((to - from) * fps) { scorer.process(signal, at: from + Double(i) / fps) }
}

func secondScreenBecomesAZone() {
let scorer = FocusScorer(params: .standard, start: 0)
feed(scorer, from: 0, to: 100, look)
check(scorer.classify(laptop, at: 100) == .lookingAway) // not learned yet
feed(scorer, from: 100, to: 300, laptop)
check(scorer.classify(laptop, at: 300) == .focused)
check(scorer.score == 100)
check(scorer.classify(away, at: 300) == .lookingAway) // the phone still counts as away
}

func zonesCarryOverToTheNextPhase() {
let zones = PoseZones()
let first = FocusScorer(params: .standard, start: 0, zones: zones)
feed(first, from: 0, to: 20, look)
feed(first, from: 20, to: 120, laptop)
let next = FocusScorer(params: .standard, start: 200, zones: zones)
feed(next, from: 200, to: 215, look) // calibration of the new phase
check(next.classify(laptop, at: 215) == .focused)
}

func gazeIsRelativeToCalibration() {
// A camera beside the screen sees the eye at an angle: the pupil sits off-centre even when you look straight ahead.
var side = look; side.gazeOffset = 0.4
let scorer = FocusScorer(params: .standard, start: 0)
feed(scorer, from: 0, to: 15, side)
var straight = side; straight.gazeOffset = 0.45
var sideways = side; sideways.gazeOffset = 0.9
check(scorer.classify(straight, at: 15) == .focused)
check(scorer.classify(sideways, at: 15) == .lookingAway)
}

func oneSecondDipNeverAlerts() {
check(run(until: 200, distraction(from: 100, length: 1)).isEmpty)
}
Expand Down Expand Up @@ -280,6 +320,9 @@ let checks: [(String, () -> Void)] = [
("singleRoundGoesStraightToDone", singleRoundGoesStraightToDone),
("pauseAfterMissedPhaseCatchesUp", pauseAfterMissedPhaseCatchesUp),
("zeroConfigIsClamped", zeroConfigIsClamped),
("secondScreenBecomesAZone", secondScreenBecomesAZone),
("zonesCarryOverToTheNextPhase", zonesCarryOverToTheNextPhase),
("gazeIsRelativeToCalibration", gazeIsRelativeToCalibration),
("oneSecondDipNeverAlerts", oneSecondDipNeverAlerts),
("twentySecondDistractionDoesNotAlert", twentySecondDistractionDoesNotAlert),
("thirtySecondDistractionAlertsOnce", thirtySecondDistractionAlertsOnce),
Expand Down
6 changes: 5 additions & 1 deletion docs/focus-scoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,14 @@ 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.
- `lookingAway`: |Δyaw| > 25° or |Δpitch| > 20°, unless that head pose is a learned work zone (below); or, with the head in the calibrated pose, the pupil offset is more than 0.35 above its calibrated value. The offset is relative because a camera beside the screen sees the eye at an angle.
- `focused`: otherwise.
- Frames with low Vision confidence are skipped (neither focused nor distracted).

## Work zones (several screens)

The calibration only knows the screen you looked at during its first 10 s. Every head pose afterwards is recorded in 10° bins. A pose whose bin and neighbouring bins (about ±15°) add up to 60 s within the last 10 minutes becomes a work zone and counts as focused: a second monitor or a laptop beside it is learned after about a minute. Poses more than 30° above or below the calibrated one are never learned, so a phone in your lap always counts as looking away. Zones are kept for the whole app run, across study phases.

## Score
- `focusScore` = percentage of `focused` frames within the sliding window W.
- `smoothedScore` = EMA of `focusScore` for display.
Expand Down
Loading