How aakash-kr-7/screen-recapture-detector works
1. What this repo is
- A small Python ML project for binary image classification: distinguish authentic real-world photos from screen or printout recaptures.
- The architecture is centered on hand-engineered computer vision features plus a traditional scikit-learn classifier, not deep learning.
2. Primary runtime entrypoints
- predict.py is the single-image inference CLI.
- app.py is the interactive local web UI for uploading images and inspecting results.
- src/train.py is the training and model export pipeline.
- src/benchmark.py is a latency benchmarking utility.
3. Core ML pipeline
- The saved model in models/model.pkl is a fitted Pipeline combining StandardScaler -> RandomForestClassifier.
- The model is fed by a 39-dimensional feature vector generated by src/features.py.
- models/metadata.json stores run configuration, feature names, and evaluation results.
4. Feature extraction boundary
- src/features.py is the main analytical subsystem: it converts an image into classical CV descriptors.
- The README describes mixed preprocessing rules depending on the feature family:
- RGB standardization via PIL.
- Spatial features use images resized with max dimension capped at 512.
- DCT/block-boundary checks use grayscale at original size to preserve pixel alignment.
- FFT-based checks use resized 512×512 grayscale input.
- This means preprocessing is feature-dependent, not a single uniform transform.
5. Data layout and dataset meaning
- dataset/real/ contains authentic photos.
- dataset/screen/ contains recaptures from screens and printouts.
- Both are organized into 7 sessions each, which matters because the training procedure uses session-aware validation rather than random splitting.
6. Training and evaluation flow
- src/train.py performs Leave-One-Session-Out (LOGO) cross-validation.
- The training loop evaluates candidate classifiers and sweeps PCA components, then prints per-session accuracy metrics.
- After selection, it retrains a final pipeline and writes the production artifacts to models/.
7. Inference data flow
- predict.py takes an image path, loads the image, extracts the feature vector, runs the saved pipeline, and emits a single scalar score.
- The output is normalized for end users as:
- 0.0 = authentic photo
- 1.0 = screen/printout recapture
- This is the key external contract of the system.
8. Web UI boundary
- app.py is a separate presentation layer for interactive use.
- The README says it runs a local dashboard on port 8501 and accepts uploads in memory, so it sits above the same inference stack without persisting files to disk.
9. Benchmarking subsystem
- src/benchmark.py isolates performance measurement from modeling.
- Its role is to measure computational latency of the pipeline, which is useful because the repo emphasizes “lightweight” inference.
10. Artifacts and outputs
- models/model.pkl is the deployable inference artifact.
- models/metadata.json is the companion configuration/evaluation record.
- models/feature_importance.png indicates post-training analysis of model behavior.
- These artifacts form the handoff between training and deployment.
11. Architectural shape
- This is a small offline ML system with three clear layers:
- Data layer: session-structured image datasets.
- Modeling layer: feature extraction + validation + training.
- Serving layer: CLI prediction and optional local UI.
- The main dependency flow is: dataset → feature extractor → classifier pipeline → saved artifacts → inference/UI.
12. Important design constraint
- Because the repository uses classical CV features, the model’s behavior depends heavily on preprocessing consistency and session-based generalization.
- The architecture is therefore optimized for controlled, reproducible offline evaluation and lightweight deployment, not for end-to-end learned representation training.
Main entry points: train.py Training · features.py Features · model.pkl Model file · predict.py Predict CLI
Components 14
Data
Session-structured image datasets for authentic photos and recaptures.
- Real photos · Authentic photo sessions used as the negative class.
dataset/real - Screen recaptures · Screen and printout recapture sessions used as the positive class.
dataset/screen
Modeling
Feature extraction, validation, training, and benchmarking.
- Features · Turns an image into the 39-dimensional hand-engineered descriptor vector.
src/features.py - Training · Runs session-aware validation, model selection, and final artifact export.
src/train.py - Session split · Leave-one-session-out evaluation to measure generalization across capture sessions.
- Preprocess · Applies feature-dependent resizing and color/grayscale handling before extraction.
- Model pipeline · StandardScaler followed by RandomForestClassifier for final prediction.
- Benchmark · Measures inference latency of the pipeline.
src/benchmark.py - 39 features · The compact classical CV representation consumed by the classifier.
Serving
CLI and local UI that run inference for end users.
- Predict CLI · Loads one image, extracts features, and emits a normalized authenticity score.
predict.py - Web UI · Interactive upload-based interface for inspecting predictions in memory.
app.py - Score · User-facing score where 0.0 means authentic and 1.0 means recapture.
Artifacts
Saved deployable model and training metadata.
- Model file · Deployable fitted pipeline used for inference.
models/model.pkl - Metadata · Stores feature names, configuration, and evaluation results.
models/metadata.json
Connections 18
- Real photos → Training: train class · Provides authentic photo examples for learning and validation.
- Screen recaptures → Training: train class · Provides recapture examples for learning and validation.
- Training → Session split: uses · Evaluates candidates with leave-one-session-out splits.
- Training → Preprocess: configures · Selects preprocessing rules by feature family.
- Preprocess → Features: feeds · Prepares images for descriptor computation.
- Features → 39 features: produces · Generates the 39-dimensional feature vector.
- 39 features → Model pipeline: inputs · Features are standardized and classified by the fitted pipeline.
- Training → Model pipeline: fits · Trains and selects the final production model.
- Model pipeline → Model file: exports · Persists the deployable pipeline to disk.
- Training → Metadata: writes · Stores configuration and evaluation summaries.
- Model file → Predict CLI: loads · Prediction CLI uses the saved pipeline for inference.
- Model file → Web UI: loads · Web UI reuses the saved pipeline for interactive inference.
- Features → Predict CLI: extracts · Transforms a single input image before inference.
- Features → Web UI: extracts · Transforms uploaded images before inference.
- Predict CLI → Score: emits · Returns a scalar score normalized for end users.
- Web UI → Score: shows · Displays the same normalized authenticity score.
- Features → Benchmark: measures · Benchmark isolates feature and pipeline latency.
- Model file → Benchmark: benchmarks · Measures deployable inference performance.