ahmedg12104/Stegno-image-analysis

⦿ STEGANOSCAN — Neural Forensics Terminal v4.2

A Flask-based neural forensics web application for image steganalysis, tamper detection, object detection/tracking, and AI-generated image identification. Trained on 16,505 images and validated on 4,127 images with a 256-dimensional feature vector extracted via SRM (Spatial Rich Model) filters and related steganalysis techniques.

Live Demo: HuggingFace Space

Table of Contents

1. 1.Features
2. 2.Architecture Overview
3. 3.Modules
4. 4.Config (`modules/config.py`)
5. 5.YOLO Detector (`modules/yolo_detector.py`)
6. 6.Stego Analyzer (`modules/stego_analyzer.py`)
7. 7.Residual Heatmap (`modules/residual_heatmap.py`)
8. 8.ELA Forensics (`modules/ela_forensics.py`)
9. 9.Text OCR (`modules/text_ocr.py`)
10. 10.GAN Detector (`modules/gan_detector.py`)
11. 11.Utils (`modules/utils.py`)
12. 12.Trackers (`modules/trackers/`)
13. 13.Feature Extraction Pipeline (256-dim)
14. 14.ML Models
15. 15.Steganalysis Models
16. 16.YOLO Models
17. 17.GAN Detection Model
18. 18.API Endpoints
19. 19.UI / Frontend
20. 20.Installation & Setup
21. 21.Docker & HuggingFace Spaces
22. 22.Project Structure
23. 23.Dependencies

Features

• —Steganalysis Detection — SVM + URD ensemble models detect hidden data in images using 18 feature families (256-dim)
• —YOLO Object Detection — YOLOv8x/YOLOv8s/YOLO11x with SRM residual heatmap overlay
• —Multi-Object Tracking — 5 trackers: ByteTrack, Bot-SORT, Deep SORT, Strong SORT, OC-SORT
• —Error Level Analysis (ELA) — JPEG tamper detection without ML models
• —OCR Text Detection — EasyOCR-based text region extraction
• —GAN/AI Image Detection — Vision Transformer (ViT) + frequency heuristic hybrid
• —All-in-One Forensics Pipeline — Run all 5 analyses in a single request
• —Cyberpunk Terminal UI — Matrix rain, CRT scanlines, glitch animations, glass-morphism panels
• —Interactive Charts — Radar chart, per-dataset bar chart, animated GIF metrics, probability gauge
• —Drag-and-Drop — Image upload via click or drag-and-drop on all analysis tabs

Architecture Overview

User Browser (HTML/JS/CSS)
        │
        ▼ HTTP
  Flask Web Server (app.py)
        │
        ├── /api/predict  ──► Feature Extraction (256-dim) ──► SVM / URD
        ├── /api/yolo/*   ──► YOLODetector + ResidualHeatmap
        ├── /api/forensics/*
        │   ├── ela       ──► ELAAnalyzer
        │   ├── ocr       ──► TextDetector (EasyOCR)
        │   ├── gan       ──► GANDetector (ViT + FFT heuristics)
        │   └── full      ──► All of the above + steganalysis + YOLO
        ├── /api/tracker/* ──► Tracker Factory (5 trackers)
        ├── /api/metrics   ──► Validation metrics + charts
        └── /              ──► index.html (SPA frontend)

Modules

Config (modules/config.py)

Central configuration constants for all modules:

YOLO Detector (modules/yolo_detector.py)

YOLODetector

Wraps Ultralytics YOLO for object detection.

YOLOPool

Multi-model manager with lazy loading.

Models:

Stego Analyzer (modules/stego_analyzer.py)

StegoAnalyzer

Orchestrates combined steganalysis analysis:

1. 1.Runs YOLO detection on the image
2. 2.Computes SRM residual heatmap
3. 3.For each detected region, extracts 256-dim features and runs SVM + URD prediction
4. 4.Returns per-detection probabilities, hotspot contours, and aggregate scores

Residual Heatmap (modules/residual_heatmap.py)

ResidualHeatmap

Computes SRM (Spatial Rich Model) energy maps:

• —Applies 3 SRM filters: f1h (horizontal), f1v (vertical), sq3 (square 3×3)
• —Sliding-window aggregation (32×32 window, 16 stride)
• —Generates COLORMAP_JET overlay
• —Extracts stego hotspot contours (regions with energy > mean + sensitivity × std)
• —Returns heatmap image (base64) and hotspot polygons

ELA Forensics (modules/ela_forensics.py)

ELAAnalyzer

JPEG tamper detection without ML models:

1. 1.Re-saves image at JPEG quality ELA_QUALITY (default 85)
2. 2.Computes pixel-wise absolute difference between original and re-encoded
3. 3.Scales error by ELA_SCALE (default 15×)
4. 4.Thresholds to find suspicious regions (error > 95th percentile)
5. 5.Returns:
6. 6.ela_score — mean error
7. 7.mean_error, max_error, p95_error
8. 8.suspicious_ratio — fraction of pixels above threshold
9. 9.suspicious_regions — bounding contours > 50 px²
10. 10.Overlay heatmap (COLORMAP_HOT)
11. 11.Verdict: "MANIPULATED" (score > 0.3) or "ORIGINAL"

Text OCR (modules/text_ocr.py)

TextDetector

Wraps EasyOCR (default: English, CPU).

GAN Detector (modules/gan_detector.py)

GANDetector

Two-pronged AI-generated image detection:

1. ViT Model (HuggingFace)

• —Model: dima806/deepfake_vs_real_image_detection
• —Vision Transformer fine-tuned for real vs. fake classification
• —Lazy-loaded on first use
• —Gracefully falls back to heuristics if model unavailable

2. Heuristic Analysis

• —FFT Frequency Features: radial power spectrum, high/mid/low frequency ratios, spectral entropy
• —Noise Correlation: local noise std, spatial noise correlation

Combined Score: 0.7 × model_probability + 0.3 × heuristic_probability

Verdict: "AI_GENERATED" (> 0.5) or "NATURAL"

Utils (modules/utils.py)

Trackers (modules/trackers/)

All trackers accept a YOLO model and return tracked objects with track_id, box, confidence, class_id, label.

Feature Extraction Pipeline (256-dim)

The 256-dimensional feature vector is assembled from 18 feature families:

ML Models

Steganalysis Models

Both models auto-download from GitHub Releases if missing:

https://github.com/ahmedA-gif/cv-project-stegno-analysis/releases/download/v1.0.0/robust_svm.pkl
https://github.com/ahmedA-gif/cv-project-stegno-analysis/releases/download/v1.0.0/urd.pkl

Per-Dataset AUC (from validation):

YOLO Models

GAN Detection Model

API Endpoints

System & Status

Steganalysis Prediction

Request: multipart/form-data with image field. Response:

{
  "success": true,
  "inference_time": 1.234,
  "results": {
    "urd": {
      "prediction": "STEGO",
      "probability": 0.8912,
      "threshold": 0.570,
      "confidence": 89.12
    },
    "robust_svm": {
      "prediction": "STEGO",
      "probability": 0.7234,
      "threshold": 0.490,
      "confidence": 72.34
    }
  }
}

YOLO Detection

Tracker

Forensics

UI / Frontend

Single-page application served from templates/index.html with a cyberpunk/hacker-terminal theme.

Tabs

Visual Theme

• —Colors: Neon green (#00ff41), cyan (#00eefc), amber (#ffb000), dark background (#050505)
• —Effects: CRT scanlines overlay, Matrix rain (katakana + ASCII), glass-morphism panels, glitch/flicker animations, animated border pulses
• —Typography: JetBrains Mono (monospace)
• —Custom scrollbar styled in neon green

Installation & Setup

Prerequisites

• —Python 3.12+
• —pip

Local Setup

# 1. Clone the repository
git clone https://github.com/ahmedA-gif/cv-project-stegno-analysis.git
cd cv-project-stegno-analysis

# 2. Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate   # Linux/Mac
# venv\Scripts\activate    # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Run the app
python app.py

The app starts at http://localhost:5050.

Models (robust_svm.pkl, urd.pkl) auto-download from GitHub Releases on first startup. YOLO weights download from Ultralytics on first use.

Configuration

Edit modules/config.py to adjust:

• —YOLO confidence/IoU thresholds
• —Heatmap sensitivity
• —ELA quality/scale
• —OCR languages
• —Max image dimensions

Docker & HuggingFace Spaces

Docker Build

docker build -t steganoscan .
docker run -p 7860:7860 steganoscan

HuggingFace Spaces

The project is configured for Docker-based HuggingFace Spaces:

1. 1.Fork/push the repo to a HF Space
2. 2.Space SDK: Docker
3. 3.Port: 7860
4. 4.The Space auto-builds on push

Environment variables (optional):

• —PORT — server port (default: 5050 dev, 7860 Docker)

Project Structure

cv-project/
├── app.py                      # Flask application (1007 lines)
├── Dockerfile                  # Docker image for HF Spaces
├── requirements.txt            # Python dependencies
├── README.md                   # This file
├── manifest.json               # Training metadata
├── robust_svm.pkl              # SVM model (auto-downloaded)
├── urd.pkl                     # URD ensemble model (auto-downloaded)
├── yolov8x.pt                  # YOLOv8x weights
├── yolov8s.pt                  # YOLOv8s weights
├── yolo11x.pt                  # YOLO11x weights
├── validation_metrics_animated.gif
│
├── templates/
│   └── index.html              # Single-page UI (718 lines)
│
├── static/                     # Static assets
│
├── uploads/                    # Temporary uploads (auto-cleaned)
│
├── modules/
│   ├── __init__.py
│   ├── config.py               # Global configuration
│   ├── yolo_detector.py        # YOLO detection + model pool
│   ├── stego_analyzer.py       # Combined stego region analyzer
│   ├── residual_heatmap.py     # SRM heatmap generation
│   ├── ela_forensics.py        # Error Level Analysis
│   ├── text_ocr.py             # EasyOCR text detection
│   ├── gan_detector.py         # GAN/AI image detection
│   ├── utils.py                # Helper functions
│   └── trackers/
│       ├── __init__.py
│       ├── base_tracker.py     # Abstract interface
│       ├── byte_tracker.py     # ByteTrack
│       ├── bot_sort_tracker.py # Bot-SORT
│       ├── deep_sort_tracker.py# Deep SORT
│       ├── strong_sort_tracker.py # Strong SORT
│       ├── oc_sort_tracker.py  # OC-SORT
│       └── tracker_factory.py  # Factory + registry
│
└── Phase 2/                    # Earlier version (identical structure)

Dependencies

License

MIT