ScreenGuardian: Public Development History

Historical public code. This is not the current product.

This repository preserves the public development history of ScreenGuardian, a local computer-vision desktop app that gives posture and screen-distance feedback from a webcam: the original 2023 competition application, an optimized 2024 variant, and the CustomTkinter and MediaPipe rewrite that sits on the default branch.

Kept as an engineering record. Not maintained. Issues and pull requests are not monitored. No license is provided for this repository; all rights are reserved. It does not contain the current product's source code.

These implementations represent earlier stages of ScreenGuardian's development and are preserved to document the project's engineering evolution. ScreenGuardian has since been substantially rebuilt as a separate private PySide6/Qt application for macOS and Windows. The archived architecture and limitations described here should not be treated as a description of the current product.

Stage	Primary engineering contribution	Relationship to current product
Original ScreenGuardian / V1	Established the core concept and broad competition-era feature set	Historical foundation
ScreenGuardian Lite	Reduced repeated analysis work by separating expensive inference cadence from rendering	Historical optimization stage
ScreenGuardian TK Rewrite	Rebuilt computer vision, storage, calibration, portability, and interface foundations	Last public implementation
Current ScreenGuardian	Separate private PySide6/Qt rebuild for macOS and Windows	Active product; source not included

Browse source snapshots

Version	Source snapshot	Primary file
Original ScreenGuardian / V1	Browse the 2023 source	ScreenGuardian.py
ScreenGuardian Lite	Browse the 2024 Lite source	sgLite.py
ScreenGuardian TK Rewrite	Browse the January 2026 source	screenguardian_dev.py

---

Public development history

Original ScreenGuardian / V1

October 2023 · Python, PyQt5, Dlib, OpenCV · abf08de264225c9161036142aaae186c40b94a7e

The competition-era application, and the version that won the Congressional App Challenge. It runs a live webcam loop, detects the face with Dlib's frontal-face detector, and reads 68 facial landmarks to estimate viewing distance and head posture, drawing the tracked points over the video feed.

Its feature surface was wide for a first project:

• Posture and screen-distance alerts, with configurable minimum distance, distance threshold, break interval, and alert delay
• Focus Monitoring, using eye aspect ratio as an attention signal, with on-task and off-task time accounting
• Manual Start Break and End Break sessions
• A Quick Vision Test
• Calibration capturing a neutral head position and a personal eye-aspect-ratio baseline
• Time with no face detected excluded from screen-time totals
• Light and dark modes, an alert log, and a weekly statistics window with six charts

Statistics and settings were stored as plain text files, and asset paths were hardcoded for Windows. The application was distributed as a packaged executable.

ScreenGuardian Lite

Developed in 2024, committed August 2025 · Python, PyQt5, Dlib, OpenCV · e5007286aab97da8d4bae79d215703ef9e5890b2

ScreenGuardian Lite is a focused optimization of V1. It retains the same toolkit, architecture, and product model while reducing repeated per-frame analysis work.

Lite separates how often the expensive analysis runs from how often the interface redraws: the 68-point landmark prediction, the eye-aspect-ratio computation, the distance estimate, the break timer, and the focus logic all move behind a single quarter-second gate, so inference runs at roughly 4 Hz while the render loop continues at full rate. Landmarks are cached between inference ticks so drawing can reuse them, and capture is paced to about 25 FPS.

ScreenGuardian Lite continued the project's development after the competition. The existing v1.0 tag points at this commit.

ScreenGuardian TK Rewrite

Developed during 2025, committed January 2026 · Python, CustomTkinter, OpenCV, MediaPipe, SQLite, JSON · d7e955f53f415e8a8c591c73eeb0eade1fa2e393

The TK rewrite is the most recent public implementation preserved in this repository. It replaced the computer-vision, storage, calibration, portability, and interface foundations of V1 and Lite.

What changed from V1 and Lite:

• Detection. Dlib gives way to MediaPipe, and the input expands from facial landmarks alone to face, pose, and hand landmarks together.
• Posture. A single eye-line angle is replaced by several geometric signals covering vertical position, depth, neck compression, head twist, eye-line tilt, and torso orientation.
• Distance. Calibration moves from a slider-scaled estimate to a physical reference object of known size combined with inter-pupillary pixel distance, reported in centimeters or inches.
• Storage. Text files give way to SQLite for alerts and daily and hourly aggregates, and JSON for settings and calibration, with schema checks and a duplicate-row merge at startup.
• Portability. Hardcoded Windows paths give way to the operating system's application-data directory. Camera opening becomes a per-platform ordered backend search with environment overrides. Notifications drop their third-party dependency in favor of native paths on macOS, Windows, and Linux.
• New capabilities. Optional face-touch and nail-biting feedback, hourly statistics, a dedicated 20-20-20 reminder, a resource-saving mode, and a local data-erase control.

The rewrite also changed the feature scope. It added new MediaPipe-based capabilities while leaving several V1 experiments behind, including Focus Monitoring, on-task and off-task accounting, the Quick Vision Test, and manual break sessions. The retrospective covers the full comparison.

The rewrite was developed during 2025 and committed publicly in January 2026.

Comparison

	V1 (2023)	Lite (2024)	TK Rewrite (2026 commit)
Interface	PyQt5	PyQt5	CustomTkinter
Detection	Dlib, 68 facial landmarks	Dlib, 68 facial landmarks	MediaPipe FaceMesh, Pose, Hands
Distance estimate	scaled face-box heuristic	scaled face-box heuristic	physical reference plus inter-pupillary distance
Storage	plain text files	plain text files	SQLite and JSON
File locations	hardcoded Windows paths	hardcoded Windows paths	OS application-data directory
Camera	fixed device index	fixed device index	per-platform backend search
Analysis cadence	every frame	gated, decoupled from rendering	worker threads with a single-slot frame queue
Notifications	third-party library	third-party library	native per-platform

Checking out each version locally

git clone https://github.com/EricW9888/ScreenGuardian-legacy.git
cd ScreenGuardian-legacy

# Original ScreenGuardian / V1  (ScreenGuardian.py, plus UI assets)
git checkout abf08de264225c9161036142aaae186c40b94a7e

# ScreenGuardian Lite  (sgLite.py, alongside the original)
git checkout e5007286aab97da8d4bae79d215703ef9e5890b2

# ScreenGuardian TK Rewrite  (screenguardian_dev.py)
git checkout d7e955f53f415e8a8c591c73eeb0eade1fa2e393

# Back to the default branch
git checkout main

Checking out a commit directly puts you in detached HEAD state. That is expected and harmless for reading. The original application and its interface assets remain available in the pre-rewrite history: the V1 snapshot contains the competition-era implementation, and the Lite snapshot retains it alongside sgLite.py. Those files are absent from the TK rewrite and the current default branch.

Demo

The video below shows the TK Rewrite, the version on this default branch. No recording of V1 or Lite is published here; their interface assets are preserved in the pre-rewrite history.

ScreenGuardian.README.Video.mov

Recognition

The original ScreenGuardian project won the 2023 Congressional App Challenge for Nevada's Second Congressional District. The broader product and business concept later received the top award at the 2024 Copernicus Entrepreneurship Olympiad.

Running the TK Rewrite

This is archived code. Read the limitations below before installing anything.

Create the environment:

python -m venv .venv

Activate it. On macOS and Linux:

source .venv/bin/activate

On Windows, in PowerShell:

.venv\Scripts\Activate.ps1

Then, on any platform:

pip install -r requirements.txt
python screenguardian_dev.py

Python 3.11 is recommended for this archived dependency set. The pinned mediapipe==0.10.9 provides wheels for Python 3.8 through 3.11, but not Python 3.12 or later. The app also needs a Python built with Tk support.

If the camera is not found, close other applications using the webcam and set SG_CAMERA_BACKEND (CAP_AVFOUNDATION on macOS, CAP_MSMF or CAP_DSHOW on Windows, CAP_V4L2 on Linux, or CAP_ANY) and SG_CAMERA_INDEX.

Packaging

The historical packaging instruction is a plain PyInstaller build. It is documented rather than verified; no CI job builds a packaged application.

pyinstaller --noconfirm --name "ScreenGuardianDev" screenguardian_dev.py

Privacy and local storage

• Camera frames are processed in memory. They are not written to disk and not uploaded by this application; there is no image or video write path in the source.
• Landmark coordinates are transient and are not persisted.
• Stored locally: derived aggregates (screen time, posture time, distance averages and counts, by day and by hour), alert timestamps and messages, settings, and calibration.
• A log file is written alongside them and receives diagnostic output.

Path	Contents
macOS ~/Library/Application Support/ScreenGuardian/	config.json, calibration.json, data.db, screenguardian.log
Windows %LOCALAPPDATA%\ScreenGuardian\ScreenGuardian\	the same four files

The repeated segment in the Windows path is what appdirs produces here, not a typo.

The data-erase control clears the database tables holding aggregates and alerts. It does not delete the calibration file or the log file; this application contains no file-deletion path.

Historical limitations

These apply to the archived public implementations.

• The detection heuristics were not evaluated against a labeled dataset, and no measured accuracy is claimed for any version here.
• Automated behavioral testing was limited or absent; continuous integration compiles the sources.
• Both desktop applications used concentrated architectures, with most logic in a single large module.
• Dependencies and packaging instructions are historical.

Engineering retrospective

docs/ENGINEERING_EVOLUTION.md covers the technical evolution in more depth: the full feature-delta matrix, the architecture comparison, what was added and redesigned, what was not carried forward, and the engineering lessons from each stage.

Current product

ScreenGuardian is currently under active development as a private PySide6/Qt desktop application for macOS and Windows. It has been substantially rebuilt since the public implementations preserved here, and its source code is not contained in this repository.

This repository documents the path from the original competition application through ScreenGuardian Lite and the TK rewrite; it does not represent the current product's active codebase.

screenguardianapp.com