# z1311/image-manipulation-detection architecture

> Architecture diagram of the GitHub repository z1311/image-manipulation-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/z1311/image-manipulation-detection
- Repository: https://github.com/z1311/image-manipulation-detection

## Overview

1. This repository is a small Python inference pipeline for image-forgery detection. Its goal is to classify a single image as authentic or tampered using a two-level analysis flow described in the README.

2. The entry point is `main.py`, which exposes a CLI with a required `-p/--path` flag. The repository is therefore organized around one input artifact: an image file path.

3. Level 1 is metadata inspection, implemented in `level1.py`. This stage looks for software or editing signatures in the image metadata, so it acts as a fast, heuristic first pass before any heavier model inference.

4. Level 2 is the visual-analysis path. The repository uses Error Level Analysis in `ela.py` to transform the input image into a representation that highlights compression inconsistencies and potential tampered regions.

5. The ELA output is then passed into the CNN defined in `model.py` for final classification. The model is not trained at runtime; it uses a pre-trained weight file stored at `model/model_c1.pth`.

6. The training and validation workflow is separated from inference and appears to live in `train.ipynb`. That notebook likely produced the saved CNN weights used by the runtime pipeline.

7. The main architectural boundary is between preprocessing/detection logic and model inference:
   - metadata analysis in Level 1
   - ELA feature generation in Level 2
   - CNN classification using persisted weights

8. The data flow is linear and file-centric: image path in, metadata inspection, optional or parallel ELA generation, CNN inference, classification output. There is no indication of a database, API server, or distributed system.

9. The model is trained on the CASIA dataset, specifically JPEG copy-move and spliced tampering examples. That dataset choice matters because it shapes the CNN’s expected input format and the types of manipulations the system is designed to detect.

10. From an architecture-diagram perspective, the key components to show are:
   - CLI user input
   - `main.py` orchestration
   - `level1.py` metadata scanner
   - `ela.py` preprocessing
   - `model.py` / `model/model_c1.pth` inference engine
   - final authentic-vs-tampered decision

11. The repo is self-contained and local: it depends on Python execution and a saved model artifact, with no obvious external services or runtime infrastructure beyond the filesystem and image-processing/model libraries implied by the implementation.

Main entry points: [`main.py`](https://github.com/z1311/image-manipulation-detection/blob/master/main.py) (Main), [`model.py`](https://github.com/z1311/image-manipulation-detection/blob/master/model.py) (CNN), [`level1.py`](https://github.com/z1311/image-manipulation-detection/blob/master/level1.py) (Level 1), [`ela.py`](https://github.com/z1311/image-manipulation-detection/blob/master/ela.py) (ELA prep)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoint["Entrypoint"]
  node_cli_path["Image path<br/>cli arg"]
  node_main_py["Main<br/>orchestrator<br/>[main.py]"]
  node_final_decision(("Verdict<br/>authentic vs tampered"))
end

subgraph group_detection["Detection"]
  node_level1_py["Level 1<br/>metadata scan<br/>[level1.py]"]
  node_ela_py["ELA prep<br/>feature prep<br/>[ela.py]"]
end

subgraph group_inference["Inference"]
  node_model_py["CNN<br/>classifier<br/>[model.py]"]
end

subgraph group_artifacts["Artifacts"]
  node_model_weights["Weights<br/>pytorch checkpoint<br/>[model_c1.pth]"]
end

subgraph group_training["Training"]
  node_train_ipynb["Training<br/>notebook<br/>[train.ipynb]"]
end

node_cli_path -->|"path input"| node_main_py
node_main_py -->|"run metadata"| node_level1_py
node_main_py -->|"build ELA"| node_ela_py
node_level1_py -->|"heuristic signal"| node_final_decision
node_ela_py -->|"ELA image"| node_model_py
node_model_weights -->|"load params"| node_model_py
node_model_py -->|"classify"| node_final_decision
node_train_ipynb -->|"produces"| node_model_weights

click node_main_py "https://github.com/z1311/image-manipulation-detection/blob/master/main.py"
click node_level1_py "https://github.com/z1311/image-manipulation-detection/blob/master/level1.py"
click node_ela_py "https://github.com/z1311/image-manipulation-detection/blob/master/ela.py"
click node_model_py "https://github.com/z1311/image-manipulation-detection/blob/master/model.py"
click node_model_weights "https://github.com/z1311/image-manipulation-detection/blob/master/model/model_c1.pth"
click node_train_ipynb "https://github.com/z1311/image-manipulation-detection/blob/master/train.ipynb"

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_cli_path,node_main_py,node_final_decision toneBlue
class node_level1_py,node_ela_py toneAmber
class node_model_py toneMint
class node_model_weights toneRose
class node_train_ipynb toneIndigo
```

## Components

### Entrypoint

CLI input and orchestration

- **Image path**: cli arg · Required input image file path supplied via the CLI
- [Main](https://github.com/z1311/image-manipulation-detection/blob/master/main.py): orchestrator · CLI entrypoint that coordinates the two-level forgery detection flow · `main.py`
- **Verdict**: authentic vs tampered · Final classification output for the submitted image

### Detection

Metadata and visual-analysis stages

- [Level 1](https://github.com/z1311/image-manipulation-detection/blob/master/level1.py): metadata scan · Fast heuristic pass that inspects image metadata for editing or software signatures · `level1.py`
- [ELA prep](https://github.com/z1311/image-manipulation-detection/blob/master/ela.py): feature prep · Error Level Analysis transform that highlights compression inconsistencies · `ela.py`

### Inference

CNN classification runtime

- [CNN](https://github.com/z1311/image-manipulation-detection/blob/master/model.py): classifier · Pretrained convolutional model that scores the ELA image for tampering · `model.py`

### Artifacts

Persisted model weights

- [Weights](https://github.com/z1311/image-manipulation-detection/blob/master/model/model_c1.pth): pytorch checkpoint · Saved CNN parameters used at inference time · `model/model_c1.pth`

### Training

Notebook used to produce runtime weights

- [Training](https://github.com/z1311/image-manipulation-detection/blob/master/train.ipynb): notebook · Training and validation workflow that produced the saved CNN weights · `train.ipynb`

## Connections

- Image path → Main: path input · The required image path is passed into the CLI entrypoint
- Main → Level 1: run metadata · Main invokes the Level 1 heuristic inspection
- Main → ELA prep: build ELA · Main prepares the visual-analysis branch for the same input image
- Level 1 → Verdict: heuristic signal · Metadata findings contribute to the overall tamper judgment
- ELA prep → CNN: ELA image · The transformed image is forwarded into the CNN classifier
- Weights → CNN: load params · The classifier uses the persisted checkpoint at runtime
- CNN → Verdict: classify · CNN output is turned into the final authentic-or-tampered verdict
- Training → Weights: produces · The notebook training workflow generates the saved model artifact
