DeepTrace ELA (Error Level Analysis) Forensics Engine

An open-source, NIST-grade Error Level Analysis (ELA) and JPEG compression artifact forensics toolkit developed by Shaheer Ul Hassan.

🔍 Overview

When an image is modified or spliced (such as pasting a fake signature, changing numbers on a document, or splicing digital elements), the newly pasted regions typically have a distinct JPEG compression history from the ambient background.

deeptrace-ela re-compresses the input image at a known quality level ($Q = 95$ by default), evaluates the absolute residual error between the input and re-compressed pixels, amplifies compression discrepancies, and detects anomalous noise clusters indicative of cut-and-paste manipulation.

Extracted from the DeepTrace document forensics pipeline. Source code and issue tracking are maintained at samjanjua6/deeptrace-ela.

🚀 Installation

# Standard installation (lightweight, zero OpenCV bloat)
pip install deeptrace-ela

# With OpenCV for sub-pixel morphological contour clustering
pip install deeptrace-ela[cv]

# With development and test dependencies
pip install deeptrace-ela[dev]

💻 CLI Usage

Analyze any image directly from your terminal:

# Basic ELA analysis (displays summary & saves heatmap to input_ela.png)
deeptrace-ela sample_check.jpg

# Save output heatmap to a custom file
deeptrace-ela contract.jpg --output heatmap.png

# Custom JPEG quality & amplification scale
deeptrace-ela invoice.png --quality 95 --scale 20.0

# Output structured JSON for automated pipelines
deeptrace-ela document.jpg --json

CLI Output Example

============================================================
 DeepTrace ELA — Image Forensics Engine
 Author: Shaheer Ul Hassan (https://shaheerulhassan.com/)
============================================================
Image:        invoice.jpg (1920x1080)
Resave Q:     95
Max Delta:    84
Mean Error:   3.42
Std Error:    2.15
Threshold:    10.95 (ambient mean + 3.5σ)
Status:       ⚠️ SUSPICIOUS (2 anomalous compression cluster(s) detected)

Detected Anomalies:
  [#1] Bounding Box: [x=420, y=310, w=180, h=45] | Peak Delta: 68.2
  [#2] Bounding Box: [x=915, y=740, w=120, h=35] | Peak Delta: 72.1

Heatmap saved to: invoice_ela.png

🐍 Python API

You can easily integrate deeptrace-ela into your Python scripts or web services:

from deeptrace_ela import analyze_ela

# Run ELA forensics analysis
result = analyze_ela("document.jpg", quality=95, scale=15.0)

print(f"Forensic Verdict: {result.verdict}")        # 'SUSPICIOUS' or 'CLEAN'
print(f"Is Suspicious:    {result.is_suspicious}")   # True / False
print(f"Mean error:       {result.mean_error:.2f}")

# Iterate over detected anomaly regions
for box in result.anomalies:
    print(f"Anomaly at (x={box.x}, y={box.y}, w={box.w}, h={box.h}) | peak delta: {box.peak_delta}")

# Export structured dictionary for JSON APIs
data = result.to_dict()

# Save amplified heatmap directly
result.save_heatmap("analyzed_ela.png")

🔬 Algorithm Specification

1. Re-compression: The input image is converted to RGB and saved to an in-memory JPEG stream at quality $Q$ (standard $Q = 95$).
2. Differential Residual: Pixel-by-pixel absolute difference is computed between the original and the re-saved JPEG: $$\Delta(x, y) = |I_{orig}(x, y) - I_{resaved}(x, y)|$$
3. Contrast Amplification: Differences are amplified dynamically by scaling factor $S = \min(15.0, 255 / \max(\Delta))$ to highlight microscopic compression rate mismatches.
4. Adaptive Baseline Masking: An adaptive statistical threshold ($\mu + 3.5\sigma$) computes the localized anomaly score across non-edge ambient surface pixels.

👤 Author & Maintainer

• Author: Shaheer Ul Hassan
• Website: shaheerulhassan.com
• GitHub: @samjanjua6
• Source Code: samjanjua6/deeptrace-ela
• Architecture Deep-Dive: Engineering an NIST-Grade ELA Forensics Engine
• Parent Platform: samjanjua6/DeepTrace
• LinkedIn: Shaheer Ul Hassan

📄 License

This project is licensed under the MIT License.