diff --git a/README.md b/README.md index 49654ae..3a670c5 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/Sources/FocusCore/FocusScorer.swift b/Sources/FocusCore/FocusScorer.swift index aeb95a5..a17265d 100644 --- a/Sources/FocusCore/FocusScorer.swift +++ b/Sources/FocusCore/FocusScorer.swift @@ -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. @@ -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. @@ -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 @@ -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 @@ -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? { diff --git a/Sources/FocusGuard/AppModel.swift b/Sources/FocusGuard/AppModel.swift index 316f954..9975dc4 100644 --- a/Sources/FocusGuard/AppModel.swift +++ b/Sources/FocusGuard/AppModel.swift @@ -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() /// Set by the panel controller: closes the panel (Esc). var closePanel: () -> Void = {} @@ -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() diff --git a/Sources/focus-check/main.swift b/Sources/focus-check/main.swift index cd351f2..cd288f2 100644 --- a/Sources/focus-check/main.swift +++ b/Sources/focus-check/main.swift @@ -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. @@ -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.. Void)] = [ ("singleRoundGoesStraightToDone", singleRoundGoesStraightToDone), ("pauseAfterMissedPhaseCatchesUp", pauseAfterMissedPhaseCatchesUp), ("zeroConfigIsClamped", zeroConfigIsClamped), + ("secondScreenBecomesAZone", secondScreenBecomesAZone), + ("zonesCarryOverToTheNextPhase", zonesCarryOverToTheNextPhase), + ("gazeIsRelativeToCalibration", gazeIsRelativeToCalibration), ("oneSecondDipNeverAlerts", oneSecondDipNeverAlerts), ("twentySecondDistractionDoesNotAlert", twentySecondDistractionDoesNotAlert), ("thirtySecondDistractionAlertsOnce", thirtySecondDistractionAlertsOnce), diff --git a/docs/focus-scoring.md b/docs/focus-scoring.md index 7ef5a30..f2a1429 100644 --- a/docs/focus-scoring.md +++ b/docs/focus-scoring.md @@ -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.