README.md

---
title: ImageScreenAI
emoji: 🔍
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
license: mit
tags:
  - ai-detection
  - image-forensics
  - computer-vision
  - content-moderation
  - screening-tool
---

# ImageScreenAI: Statistical Screening Of Images For Authenticity Review

[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.104%2B-009688.svg)](https://fastapi.tiangolo.com/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

> **A transparent, unsupervised first-pass screening system for identifying images requiring human review in production workflows**

---

## 🎯 Overview

**ImageScreenAI** is not a "perfect AI detector." It is a **pragmatic screening tool** designed to reduce manual review workload by flagging potentially AI-generated images based on statistical and physical anomalies.

### What This Is
✅ A workflow efficiency tool  
✅ A transparent, explainable detector  
✅ A model-agnostic screening system  
✅ A first-pass filter, not a verdict engine

### What This Is Not
❌ A definitive "real vs fake" classifier  
❌ A black-box deep learning detector  
❌ A system claiming near-perfect accuracy on 2025 AI models

---

## 🚀 Key Features

- **Multi-Metric Ensemble**: 5 independent statistical detectors analyzing different AI generation failure modes
- **Binary UX**: Only two outcomes - `LIKELY_AUTHENTIC` or `REVIEW_REQUIRED` (no ambiguous "maybe")
- **Full Explainability**: Per-metric scores, confidence levels, and human-readable explanations
- **Batch Processing**: Parallel analysis of up to 50 images with progress tracking
- **Multiple Export Formats**: CSV, JSON, and PDF reports for integration into existing workflows
- **No External Dependencies**: No ML models, no cloud APIs - fully self-contained
- **Production Ready**: FastAPI backend, comprehensive error handling, configurable thresholds

---

## 📊 Detection Approach

### The Core Philosophy

Instead of answering *"Is this image AI or real?"*, we answer:

> **"Does this image require human review?"**

This reframes the problem from classification to prioritization - far more valuable in real-world workflows.

---

## 🔬 Metrics Choice & Rationale

### Why These Five Metrics?

Each metric targets a **different failure mode** of AI image generation models (diffusion models, GANs, etc.):

#### 1. **Gradient-Field PCA** (`metrics/gradient_field_pca.py`)
- **Weight**: 30%
- **Target**: Lighting inconsistencies in diffusion models
- **Rationale**: Real photos have gradients aligned with physical light sources. Diffusion models perform patch-based denoising, creating low-dimensional gradient structures inconsistent with physics.
- **Method**: Sobel gradients → PCA → eigenvalue ratio analysis
- **Threshold**: Eigenvalue ratio < 0.85 indicates suspicious structure
- **Research Basis**: [Gragnaniello et al. 2021](https://arxiv.org/abs/2104.02726) - "Perceptual Quality Assessment of Synthetic Images"

#### 2. **Frequency Analysis (FFT)** (`metrics/frequency_analyzer.py`)
- **Weight**: 25%
- **Target**: Unnatural spectral energy distributions
- **Rationale**: Camera optics and sensors produce characteristic frequency falloffs. AI models can create spectral peaks/gaps not found in nature.
- **Method**: 2D FFT → radial spectrum → high-frequency ratio + roughness + power-law deviation
- **Thresholds**: HF ratio outside [0.08, 0.35] indicates anomalies
- **Research Basis**: [Dzanic et al. 2020](https://arxiv.org/abs/2003.08685) - "Fourier Spectrum Discrepancies in Deep Network Generated Images"

#### 3. **Noise Pattern Analysis** (`metrics/noise_analyzer.py`)
- **Weight**: 20%
- **Target**: Missing or artificial sensor noise
- **Rationale**: Real cameras produce Poisson shot noise + Gaussian read noise with characteristic variance. AI models often produce overly uniform images or synthetic noise.
- **Method**: Patch-based Laplacian filtering → MAD estimation → CV + IQR analysis
- **Thresholds**: CV < 0.15 (too uniform) or > 1.2 (too variable) flags images
- **Research Basis**: [Kirchner & Johnson 2019](https://ieeexplore.ieee.org/document/8625351) - "SPN-CNN: Boosting Sensor Pattern Noise for Image Manipulation Detection"

#### 4. **Texture Statistics** (`metrics/texture_analyzer.py`)
- **Weight**: 15%
- **Target**: Overly smooth or repetitive regions
- **Rationale**: Natural scenes have organic texture variation. GANs can produce suspiciously smooth regions or repetitive patterns.
- **Method**: Patch-based entropy, contrast, edge density → distribution analysis
- **Thresholds**: >40% smooth patches (smoothness > 0.5) indicates anomalies
- **Research Basis**: [Nataraj et al. 2019](https://arxiv.org/abs/1912.11035) - "Detecting GAN Generated Fake Images using Co-occurrence Matrices"

#### 5. **Color Distribution** (`metrics/color_analyzer.py`)
- **Weight**: 10%
- **Target**: Impossible or highly unlikely color patterns
- **Rationale**: Physical light sources create constrained color relationships. AI can generate oversaturated or unnaturally clustered hues.
- **Method**: RGB→HSV conversion → saturation analysis + histogram roughness + hue concentration
- **Thresholds**: Mean saturation > 0.65 or top-3 hue bins > 60% flags images
- **Research Basis**: [Marra et al. 2019](https://arxiv.org/abs/1902.11153) - "Do GANs Leave Specific Traces?"

---

## ⚖️ Ensemble Approach

### Weighted Aggregation Strategy

```python
final_score = (
    0.30 × gradient_score +
    0.25 × frequency_score +
    0.20 × noise_score +
    0.15 × texture_score +
    0.10 × color_score
)
```

### Pros ✅

1. **Robustness**: No single metric failure breaks the system
2. **Diversity**: Each metric captures orthogonal information
3. **Tunability**: Weights can be adjusted based on use case
4. **Explainability**: Per-metric scores preserved for transparency
5. **Fail-Safe**: Neutral scores (0.5) for metric failures prevent cascading errors

### Cons ❌

1. **Hyperparameter Sensitivity**: Weights are manually tuned, not learned
2. **Assumption of Independence**: Metrics may correlate in practice (e.g., frequency ↔ noise)
3. **Fixed Weights**: No adaptive weighting based on image characteristics
4. **Threshold Brittleness**: Single threshold (0.65) for binary decision may not fit all contexts
5. **No Adversarial Robustness**: Trivial post-processing can fool statistical detectors

### Why Not Machine Learning?

- **Transparency**: Statistical methods are auditable; neural networks are black boxes
- **Generalization**: ML models overfit to training generators; unsupervised methods generalize better
- **Deployment**: No GPU required, no model versioning issues
- **Trust**: Users understand "gradient inconsistency" better than "neuron activation patterns"

---

## 🏗️ Architecture

### High-Level Flow

```
Image Upload → Validation → Parallel Metric Execution → Aggregation → Threshold Decision → Report Export
```

### Component Structure

```
ImageScreenAI/
├── app.py                          # FastAPI application entry point
├── config/
│   ├── settings.py                 # Environment variables, weights, thresholds
│   ├── constants.py                # Enums, metric parameters, explanations
│   └── schemas.py                  # Pydantic models for type safety
├── metrics/
│   ├── gradient_field_pca.py       # Gradient structure analysis
│   ├── frequency_analyzer.py       # FFT-based spectral analysis
│   ├── noise_analyzer.py           # Sensor noise pattern detection
│   ├── texture_analyzer.py         # Statistical texture features
│   ├── color_analyzer.py           # Color distribution anomalies
│   └── aggregator.py               # Ensemble combination logic
├── features/
│   ├── batch_processor.py          # Parallel/sequential batch handling
│   ├── threshold_manager.py        # Runtime threshold configuration
│   └── detailed_result_maker.py    # Explainability extraction
├── reporter/
│   ├── csv_reporter.py             # CSV export for workflows
│   ├── json_reporter.py            # JSON API responses
│   └── pdf_reporter.py             # Professional reports
├── utils/
│   ├── logger.py                   # Structured logging
│   ├── image_processor.py          # Image loading, resizing, conversion
│   ├── validators.py               # File validation
│   └── helpers.py                  # Utility functions
└── ui/
    └── index.html                  # Single-page web interface
```

**Detailed Architecture**: See [`docs/Architecture.md`](docs/Architecture.md)

---

## 📈 Performance Expectations

### Detection Rates (Honest Estimates)

| Image Source | Expected Detection Rate |
|-------------|------------------------|
| Consumer AI tools (2022-2023) | 80–90% |
| Stable Diffusion 1.x / 2.x | 70–80% |
| Midjourney v5 / v6 | 55–70% |
| DALL·E 3 / Gemini Imagen 3 | 40–55% |
| Post-processed AI images | 30–45% |
| **False positives on real photos** | **~10–20%** |

### Why These Rates?

1. **Modern Models Are Good**: 2024-2025 generators produce physically plausible images
2. **Post-Processing Erases Traces**: JPEG compression, filters, and resizing remove statistical artifacts
3. **Real Photos Vary Widely**: Macro, long-exposure, and HDR photos trigger false positives
4. **Adversarial Evasion**: Adding noise or slight edits defeats statistical detectors

### Processing Performance

- **Single image**: 2–4 seconds
- **Batch (10 images)**: 15–25 seconds (parallel)
- **Memory**: 50–150 MB per image
- **Max concurrent workers**: 4 (configurable)

---

## 📦 Installation

### Prerequisites

- Python 3.11+
- pip

### Setup

```bash
# Clone repository
git clone https://github.com/itobuztech/ImageScreenAI.git
cd ImageScreenAI

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create required directories
mkdir -p data/{uploads,reports,cache} logs

# Run server
python app.py
```

Server will start at `http://localhost:8005`

---

## 🚀 Quick Start

### Web Interface

1. Open `http://localhost:8005` in browser
2. Upload images (single or batch)
3. View results with per-metric breakdowns
4. Export reports (CSV/PDF)

### API Usage

```bash
# Single image analysis
curl -X POST http://localhost:8005/analyze/image \
  -F "file=@example.jpg"

# Batch analysis
curl -X POST http://localhost:8005/analyze/batch \
  -F "files=@img1.jpg" \
  -F "files=@img2.png" \
  -F "files=@img3.webp"

# Download CSV report
curl -X GET http://localhost:8005/report/csv/{batch_id} -o report.csv
```

**Full API Documentation**: See [`docs/API.md`](docs/API.md)

---

## 📖 Documentation

| Document | Description |
|----------|-------------|
| [`docs/Architecture.md`](docs/Architecture.md) | System architecture, data flow diagrams, component details |
| [`docs/API.md`](docs/API.md) | Complete API reference with examples |

---

## 🔬 Scientific References

### Core Detection Techniques

1. **Gragnaniello, D., Cozzolino, D., Marra, F., Poggi, G., & Verdoliva, L.** (2021). "Are GAN Generated Images Easy to Detect? A Critical Analysis of the State-of-the-Art." *IEEE International Conference on Multimedia and Expo*. [Paper](https://arxiv.org/abs/2104.02726)

2. **Dzanic, T., Shah, K., & Witherden, F.** (2020). "Fourier Spectrum Discrepancies in Deep Network Generated Images." *NeurIPS 2020*. [Paper](https://arxiv.org/abs/2003.08685)

3. **Kirchner, M., & Johnson, M. K.** (2019). "SPN-CNN: Boosting Sensor Pattern Noise for Image Manipulation Detection." *IEEE International Workshop on Information Forensics and Security*. [Paper](https://ieeexplore.ieee.org/document/8625351)

4. **Nataraj, L., Mohammed, T. M., Manjunath, B. S., Chandrasekaran, S., Flenner, A., Bappy, J. H., & Roy-Chowdhury, A. K.** (2019). "Detecting GAN Generated Fake Images using Co-occurrence Matrices." *Electronic Imaging*. [Paper](https://arxiv.org/abs/1912.11035)

5. **Marra, F., Gragnaniello, D., Cozzolino, D., & Verdoliva, L.** (2019). "Detection of GAN-Generated Fake Images over Social Networks." *IEEE Conference on Multimedia Information Processing and Retrieval*. [Paper](https://arxiv.org/abs/1902.11153)

### Diffusion Model Artifacts

6. **Corvi, R., Cozzolino, D., Poggi, G., Nagano, K., & Verdoliva, L.** (2023). "Intriguing Properties of Synthetic Images: from Generative Adversarial Networks to Diffusion Models." *arXiv preprint*. [Paper](https://arxiv.org/abs/2304.06408)

7. **Sha, Z., Li, Z., Yu, N., & Zhang, Y.** (2023). "DE-FAKE: Detection and Attribution of Fake Images Generated by Text-to-Image Diffusion Models." *ACM CCS 2023*. [Paper](https://arxiv.org/abs/2310.16617)

### Ensemble Methods

8. **Wang, S. Y., Wang, O., Zhang, R., Owens, A., & Efros, A. A.** (2020). "CNN-Generated Images Are Surprisingly Easy to Spot... for Now." *CVPR 2020*. [Paper](https://arxiv.org/abs/1912.11035)

---

## ⚠️ Ethical Considerations

### Honest Positioning

This system:
- ✅ Never claims "real" or "fake" with certainty
- ✅ Provides probabilistic screening only
- ✅ Encourages human verification for all flagged images
- ✅ Documents methodology transparently
- ✅ Acknowledges false positive rates upfront

### Appropriate Use Cases

**Suitable for:**
- Content moderation pre-screening (reduces human workload)
- Journalism workflows (identifies images needing verification)
- Stock photo platforms (flags for manual review)
- Legal discovery (prioritizes suspicious documents)

**Not suitable for:**
- Law enforcement as sole evidence
- Automated content rejection without human review
- High-stakes decisions (e.g., criminal prosecution)

### Known Limitations

1. **False Positives**: 10-20% of real photos flagged (especially HDR, macro, long-exposure)
2. **Evolving Generators**: Detection rates decline as AI models improve
3. **Post-Processing Evasion**: Simple filters can defeat statistical detectors
4. **No Adversarial Robustness**: Not designed to resist intentional evasion

---

## 🛠️ Configuration

### Environment Variables

Create `.env` file:

```env
# Server
HOST=localhost
PORT=8005
WORKERS=4
DEBUG=False

# Detection
REVIEW_THRESHOLD=0.65

# Metric Weights (must sum to 1.0)
GRADIENT_WEIGHT=0.30
FREQUENCY_WEIGHT=0.25
NOISE_WEIGHT=0.20
TEXTURE_WEIGHT=0.15
COLOR_WEIGHT=0.10

# Processing
MAX_FILE_SIZE_MB=10
MAX_BATCH_SIZE=50
PROCESSING_TIMEOUT=30
PARALLEL_PROCESSING=True
MAX_WORKERS=4
```

### Sensitivity Modes

Adjust `REVIEW_THRESHOLD` in `config/settings.py`:

- **Conservative** (0.75): Fewer false positives, may miss some AI images
- **Balanced** (0.65): Recommended default
- **Aggressive** (0.55): Catch more AI images, more false positives

---

## 📄 License

This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- Research papers cited above for theoretical foundations
- FastAPI team for excellent web framework
- OpenCV and SciPy communities for image processing tools
- Users providing feedback on detection accuracy

---

<p align="center">
  <i>Built with transparency and honesty in mind.</i><br>
  <i>Screening, not certainty. Efficiency, not perfection.</i>
</p>