# aakash-kr-7/screen-recapture-detector architecture

> Architecture diagram of the GitHub repository aakash-kr-7/screen-recapture-detector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aakash-kr-7/screen-recapture-detector
- Repository: https://github.com/aakash-kr-7/screen-recapture-detector

## Overview

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: [`src/train.py`](https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/src/train.py) (Training), [`src/features.py`](https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/src/features.py) (Features), [`models/model.pkl`](https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/models/model.pkl) (Model file), [`predict.py`](https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/predict.py) (Predict CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data"]
  node_dataset_real[("Real photos<br/>image dataset")]
  node_dataset_screen[("Screen recaptures<br/>image dataset")]
end

subgraph group_modeling["Modeling"]
  node_feature_extractor["Features<br/>cv feature extractor<br/>[features.py]"]
  node_train_pipeline["Training<br/>[train.py]"]
  node_session_validation(("Session split<br/>LOGO validation"))
  node_preprocessing["Preprocess<br/>feature-specific prep"]
  node_classifier_pipeline["Model pipeline<br/>sklearn pipeline"]
  node_benchmark_tool["Benchmark<br/>latency probe<br/>[benchmark.py]"]
  node_feature_space(("39 features<br/>descriptor vector"))
end

subgraph group_serving["Serving"]
  node_predict_cli["Predict CLI<br/>inference cli<br/>[predict.py]"]
  node_web_ui["Web UI<br/>local dashboard<br/>[app.py]"]
  node_score_output(("Score<br/>normalized output"))
end

subgraph group_artifacts["Artifacts"]
  node_model_artifact[("Model file<br/>serialized model<br/>[model.pkl]")]
  node_metadata_artifact["Metadata<br/>run record<br/>[metadata.json]"]
end

node_dataset_real -->|"train class"| node_train_pipeline
node_dataset_screen -->|"train class"| node_train_pipeline
node_train_pipeline -->|"uses"| node_session_validation
node_train_pipeline -->|"configures"| node_preprocessing
node_preprocessing -->|"feeds"| node_feature_extractor
node_feature_extractor -->|"produces"| node_feature_space
node_feature_space -->|"inputs"| node_classifier_pipeline
node_train_pipeline -->|"fits"| node_classifier_pipeline
node_classifier_pipeline -->|"exports"| node_model_artifact
node_train_pipeline -->|"writes"| node_metadata_artifact
node_model_artifact -->|"loads"| node_predict_cli
node_model_artifact -->|"loads"| node_web_ui
node_feature_extractor -->|"extracts"| node_predict_cli
node_feature_extractor -->|"extracts"| node_web_ui
node_predict_cli -->|"emits"| node_score_output
node_web_ui -->|"shows"| node_score_output
node_feature_extractor -->|"measures"| node_benchmark_tool
node_model_artifact -->|"benchmarks"| node_benchmark_tool

click node_dataset_real "https://github.com/aakash-kr-7/screen-recapture-detector/tree/main/dataset/real"
click node_dataset_screen "https://github.com/aakash-kr-7/screen-recapture-detector/tree/main/dataset/screen"
click node_feature_extractor "https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/src/features.py"
click node_train_pipeline "https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/src/train.py"
click node_benchmark_tool "https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/src/benchmark.py"
click node_predict_cli "https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/predict.py"
click node_web_ui "https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/app.py"
click node_model_artifact "https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/models/model.pkl"
click node_metadata_artifact "https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/models/metadata.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dataset_real,node_dataset_screen toneBlue
class node_feature_extractor,node_train_pipeline,node_session_validation,node_preprocessing,node_classifier_pipeline,node_benchmark_tool,node_feature_space toneAmber
class node_predict_cli,node_web_ui,node_score_output toneMint
class node_model_artifact,node_metadata_artifact toneRose
```

## Components

### Data

Session-structured image datasets for authentic photos and recaptures.

- [Real photos](https://github.com/aakash-kr-7/screen-recapture-detector/tree/main/dataset/real): image dataset · Authentic photo sessions used as the negative class. · `dataset/real`
- [Screen recaptures](https://github.com/aakash-kr-7/screen-recapture-detector/tree/main/dataset/screen): image dataset · Screen and printout recapture sessions used as the positive class. · `dataset/screen`

### Modeling

Feature extraction, validation, training, and benchmarking.

- [Features](https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/src/features.py): cv feature extractor · Turns an image into the 39-dimensional hand-engineered descriptor vector. · `src/features.py`
- [Training](https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/src/train.py): cv training · Runs session-aware validation, model selection, and final artifact export. · `src/train.py`
- **Session split**: LOGO validation · Leave-one-session-out evaluation to measure generalization across capture sessions.
- **Preprocess**: feature-specific prep · Applies feature-dependent resizing and color/grayscale handling before extraction.
- **Model pipeline**: sklearn pipeline · StandardScaler followed by RandomForestClassifier for final prediction.
- [Benchmark](https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/src/benchmark.py): latency probe · Measures inference latency of the pipeline. · `src/benchmark.py`
- **39 features**: descriptor vector · The compact classical CV representation consumed by the classifier.

### Serving

CLI and local UI that run inference for end users.

- [Predict CLI](https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/predict.py): inference cli · Loads one image, extracts features, and emits a normalized authenticity score. · `predict.py`
- [Web UI](https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/app.py): local dashboard · Interactive upload-based interface for inspecting predictions in memory. · `app.py`
- **Score**: normalized output · User-facing score where 0.0 means authentic and 1.0 means recapture.

### Artifacts

Saved deployable model and training metadata.

- [Model file](https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/models/model.pkl): serialized model · Deployable fitted pipeline used for inference. · `models/model.pkl`
- [Metadata](https://github.com/aakash-kr-7/screen-recapture-detector/blob/main/models/metadata.json): run record · Stores feature names, configuration, and evaluation results. · `models/metadata.json`

## Connections

- 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.
