EduScale

EduScale is a research monorepo for improving the readability of low-resolution educational videos on budget Android devices. The study combines slide-aware super-resolution, OCR-aware evaluation, lightweight SPAN models, and a packaged Android app for offline enhancement.

The goal is practical: make lecture slides, classroom recordings, and screen-captured educational videos easier to read after upscaling from 240p or 360p to 720p.

Study Snapshot

Area	Current status
Retained model run folders	30
Runs with training metrics	30
Completed training epoch rows	1,359
Held-out x2 evaluation pairs	291
Held-out x3 evaluation pairs	291
Benchmark summary files	33
Per-sample evaluation CSVs	20
Android-packaged TFLite models	2

Primary evidence files:

• TRAINING_REPORT.md
• benchmarks/results
• datasets/manifests/heldout
• android/app/src/main/assets/README.md
• docs/RESEARCH_QUESTIONS.md

Monorepo Layout

Path	Role in the study
android	Kotlin Android app, app assets, workers, and offline model packaging
models	SPAN implementation, training code, checkpoints, conversion scripts, and optimized TFLite models
datasets	Dataset manifests, held-out splits, and data preparation utilities
benchmarks	Benchmark scripts plus saved PSNR, SSIM, runtime, OCR confidence, and CER outputs
scripts	End-to-end training, evaluation, statistics, and pipeline helpers
tools	Desktop analysis tools, video analyzer, quality comparator, reporting utilities, and document helpers
experiments	Research notebooks for ablations, optimization, frame selection, and OCR analysis
docs	User guide, development guide, Android notes, dataset docs, model docs, and benchmark docs
thesis	Thesis chapters, references, figures, proposal materials, and generated exports
config	App, model, device, and processing configuration

Current Android Models

Scale	Source checkpoint	Packaged model	Size
x2	models/span/education-finetuned/x2-v3-tpgsr-refine-20260411/last_model.pt	android/app/src/main/assets/span_education_x2.tflite	971 KB
x3	models/span/education-finetuned/x3-real-refine-20260412/best_model.pt	android/app/src/main/assets/span_education_x3.tflite	1.18 MB

Expected use:

Input	Model	Target
360p educational video	x2 SPAN	720p readable output
240p educational video	x3 SPAN	720p readable output

Benchmark Highlights

These numbers are from saved repository artifacts, not a fresh live rerun. OCR confidence is higher-is-better. Character error rate, or CER, is lower-is-better.

Updated Held-Out Evaluation

Model run	Scale	Samples	PSNR	SSIM	Runtime / image	OCR confidence	CER	Evidence
x2-all-20260410	x2	291	29.9002	0.9813	719.159 ms	90.9905	0.1016	x2-all-20260410-heldout-updated-ocr-summary.json
x2-all-20260410-ocr-refine	x2	291	29.3532	0.9758	762.6484 ms	90.9805	0.0814	x2-all-20260410-ocr-refine-heldout-updated-ocr-summary.json
x2-v3-tpgsr-refine-20260411	x2	291	29.4579	0.9786	572.7827 ms	91.2295	0.0765	x2-v3-tpgsr-refine-20260411-last-heldout-updated-summary.json
x3-real-refine-20260412	x3	291	26.6166	0.9642	292.9324 ms	88.8627	0.1918	x3-real-refine-20260412-heldout-updated-summary.json
x3-real-refine-20260412 last	x3	291	26.6002	0.9642	288.0681 ms	89.1655	0.2058	x3-real-refine-20260412-last-heldout-updated-summary.json

Improvement Over Time

Date	Change	Result
2026-03-08 to 2026-03-11	Baseline x2/x3 SPAN experiments, TPGSR variants, real-video runs, and synthetic-plus-PPT mixes	Established the first reproducible quality and OCR benchmark matrix
2026-04-09 to 2026-04-10	Expanded x2 training with larger all-source and raw PowerPoint manifests	x2-all-20260410 reached the strongest saved x2 PSNR/SSIM on the 291-sample updated held-out set: 29.9002 PSNR and 0.9813 SSIM
2026-04-10	Added OCR-focused x2 refinement	CER improved from 0.1016 on x2-all-20260410 to 0.0814 on x2-all-20260410-ocr-refine
2026-04-11 to 2026-04-12	Refined app-backed x2 TPGSR checkpoint	x2-v3-tpgsr-refine-20260411/last_model.pt reached 91.2295 OCR confidence and 0.0765 CER on the updated held-out set
2026-04-12	Refined x3 real-video checkpoint	Compared with x3-real, x3-real-refine-20260412 improved PSNR by 1.6661, SSIM by 0.0326, and CER by 0.0285 on the same updated held-out set
2026-04-13 to 2026-04-14	Continued x3 v4 refinement and OCR sweep experiments	Added longer-running ablation evidence for x3 model selection in TRAINING_REPORT.md

Study Design

EduScale evaluates super-resolution as a readability problem, not only as an image reconstruction problem.

Metric	Why it matters
PSNR	Measures pixel-level reconstruction quality against the high-resolution target
SSIM	Measures structural similarity, useful for slide edges, diagrams, and text blocks
Runtime	Tracks whether a model is practical for mobile or offline processing
OCR confidence	Estimates whether text becomes more readable to an OCR engine
CER	Measures text recognition errors; lower CER usually means more usable educational content

The active held-out manifests are:

• datasets/manifests/heldout/heldout_real_x2.csv
• datasets/manifests/heldout/heldout_real_x3.csv

Reproduce The Main Evaluation

Create or activate a virtual environment, then install the Python dependencies:

.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip install -r requirements-optional.txt

Run an x2 held-out evaluation:

.\.venv\Scripts\python.exe -m models.training.evaluation `
  --pairs_csv datasets/manifests/heldout/heldout_real_x2.csv `
  --checkpoint models/span/education-finetuned/x2-v3-tpgsr-refine-20260411/last_model.pt `
  --output_csv benchmarks/results/x2-v3-tpgsr-refine-20260411-last-heldout-updated-eval.csv `
  --output_summary_json benchmarks/results/x2-v3-tpgsr-refine-20260411-last-heldout-updated-summary.json `
  --include_ocr_metrics

Run an x3 held-out evaluation:

.\.venv\Scripts\python.exe -m models.training.evaluation `
  --pairs_csv datasets/manifests/heldout/heldout_real_x3.csv `
  --checkpoint models/span/education-finetuned/x3-real-refine-20260412/best_model.pt `
  --output_csv benchmarks/results/x3-real-refine-20260412-heldout-updated-eval.csv `
  --output_summary_json benchmarks/results/x3-real-refine-20260412-heldout-updated-summary.json `
  --include_ocr_metrics

Run the broader benchmark matrix:

.\.venv\Scripts\python.exe scripts/benchmark.py

Android Build

Compile the Android app from the repository root:

cd android
.\gradlew.bat :app:compileDebugKotlin

The app models are expected in:

• android/app/src/main/assets/span_education_x2.tflite
• android/app/src/main/assets/span_education_x3.tflite

To refresh app assets from optimized model exports:

Copy-Item models/span/optimized/span_education_x2.tflite android/app/src/main/assets/span_education_x2.tflite -Force
Copy-Item models/span/optimized/span_education_x3.tflite android/app/src/main/assets/span_education_x3.tflite -Force

Development Workflow

1. Prepare or update dataset manifests in datasets.
2. Train SPAN checkpoints with models/training.
3. Evaluate PSNR, SSIM, runtime, OCR confidence, and CER through benchmarks.
4. Convert selected checkpoints through models/conversion.
5. Package TFLite assets into android/app/src/main/assets.
6. Record results in benchmarks/results and summarize progress in TRAINING_REPORT.md.

Documentation Map

Need	Start here
Install and run the project	docs/user-guide/installation.md
Dataset organization	datasets/README.md
Model training and conversion	models/README.md
Benchmarking workflow	benchmarks/README.md
Android packaging	docs/guides/android.md
Tooling	docs/guides/tools.md
Thesis materials	thesis/README.md
Full training history	TRAINING_REPORT.md
Details to confirm	docs/RESEARCH_QUESTIONS.md

Repository Hygiene

This repository keeps source code, manifests, documentation, and benchmark summaries visible. Generated data and heavy local artifacts are ignored by .gitignore, including:

• PDF, HTML, Office, and thesis export files
• Python caches, pytest temp folders, and virtual environments
• Android and Gradle build outputs
• generated datasets, raw slides, rendered frames, and logs
• model checkpoints, exported binaries, and downloaded installers

Keep benchmark summaries and manifest CSVs when they are needed to reproduce a reported result. Keep raw datasets, generated videos, and temporary exports outside Git.

Publication Status

EduScale is organized as a research study and implementation monorepo. Before publishing publicly, add a non-empty license file, final contribution rules, and any dataset usage restrictions required by the source materials.