CoolFace
Apppublic

Nas0x1/ai-image-forensics

sourceHugging Facemitupdated 4mo agoView on Hugging Face
2likes
App README

AI Image Forensics - Multi-Model Ensemble

1. What this Space does

This Hugging Face Gradio Space analyzes an uploaded image and estimates whether it is likely AI GENERATED, REAL, MANIPULATED / EDITED, or INCONCLUSIVE. It combines forensic algorithms, metadata checks, camera/focal plausibility, shadow and lighting consistency, texture analysis, and GPU-capable ML model adapters.

AI image detection is probabilistic. Results can be wrong, especially after compression, screenshots, editing, resizing, metadata stripping, or adversarial manipulation. Heatmaps are visual explanations of detector signals, not definitive proof.

2. How the detector ensemble works

Each detector returns an AI probability, manipulation probability, confidence, weight, status, explanation, warnings, and optional visual artifacts. The fusion layer only includes detectors with status="ok" in the main weighted calculation. Detectors that are not_loaded, error, or skipped are shown in the table but do not affect the final score.

Confidence is based on detector confidence, detector coverage, detector agreement, and ML-model consensus. Neutral metadata and compression signals can still reduce confidence, but strong AI-model evidence is now preserved as a separate signal.

The dashboard reports camera signal, focal consistency, shadow/light consistency, and ML consensus. These are supporting signals only.

3. Detector list

  1. 1.MetadataDetector
  2. 2.EXIFSoftwareDetector
  3. 3.ELACompressionDetector
  4. 4.FFTFrequencyDetector
  5. 5.DCTFrequencyDetector
  6. 6.NoiseResidualDetector
  7. 7.JPEGQualityDetector
  8. 8.JPEGQuantizationDetector
  9. 9.SobelEdgeDetector
  10. 10.LaplacianEdgeDetector
  11. 11.PatchConsistencyDetector
  12. 12.CLIPDetector
  13. 13.CapCheck ViT Detector
  14. 14.EfficientNetDetector
  15. 15.DimaDeepfakeDetector
  16. 16.NYUADAIDetector
  17. 17.SmogyAIDetector
  18. 18.OrganikaSDXLDetector
  19. 19.AIRealNetDetector
  20. 20.DiffusionArtifactDetector
  21. 21.GANTextureDetector

4. What the verdict means

AI GENERATED means the ensemble found multiple signals consistent with synthetic generation.

AI GENERATED - MIXED SIGNALS means at least one dedicated ML detector is strongly AI-leaning, but other forensic or ML detectors disagree. This is still probabilistic and should be reviewed carefully.

REAL means the ensemble found low AI and manipulation probabilities with sufficient confidence.

MANIPULATED / EDITED means the ensemble found stronger editing, recompression, or local inconsistency signals.

INCONCLUSIVE means detector agreement, confidence, or available signal quality was not strong enough for a clear classification.

5. Heatmap and forensic maps explanation

The app can display the original image, Error Level Analysis, noise residual, frequency spectrum, patch map, combined suspicious-region visualization, and per-model heatmaps. Heatmaps use a blue-to-red gradient: blue means lower detector signal, while yellow, orange, and red mean stronger suspicious-region signal. These maps are not proof.

Camera and focal signals use EXIF fields such as camera make/model, lens, focal length, 35mm-equivalent focal length, f-number, exposure time, and ISO where available. Shadow and lighting consistency checks compare directional illumination, highlight behavior, shadow color consistency, saturation mismatch, and illumination smoothness.

6. How to run locally

bash
pip install -r requirements.txt
python app.py

Then open the local Gradio URL printed in the terminal.

7. How to deploy to Hugging Face Spaces

  1. 1.Create a new Hugging Face Space.
  2. 2.Choose the Gradio SDK.
  3. 3.Upload this repository with app.py, requirements.txt, README.md, and the module folders.
  4. 4.Use GPU hardware if you want faster ML model heatmaps.

You can also deploy from this folder:

bash
set HF_TOKEN=hf_your_write_token
set HF_SPACE_ID=your-username/ai-image-forensics
python scripts/deploy_to_hf.py

On PowerShell:

powershell
$env:HF_TOKEN="hf_your_write_token"
$env:HF_SPACE_ID="your-username/ai-image-forensics"
python scripts/deploy_to_hf.py

Model weights are not committed to this repo. The Space downloads public Hugging Face model checkpoints at runtime. For private or gated models, add a Space secret named HF_TOKEN.

8. GPU ML model configuration

This version includes GPU-capable ML dependencies and lazy-loaded model adapters. Models are not loaded at app startup; they load the first time an image is analyzed.

Installed ML dependencies:

text
torch
torchvision
transformers
timm
open_clip_torch

Default ML model configuration:

text
VIT_FORENSICS_MODELS=capcheck/ai-image-detection
VIT_FORENSICS_MAX_MODELS=1
EFFICIENTNET_FORENSICS_MODEL=KakoSan/siftai-efficientnet-b4-v2
CLIP_FORENSICS_MODEL=ViT-B-32
CLIP_FORENSICS_PRETRAINED=laion2b_s34b_b79k
FORENSICS_DEVICE=auto

Additional detector rows use:

text
dima806/deepfake_vs_real_image_detection
NYUAD-ComNets/AI-generated_images_detector
Smogy/SMOGY-Ai-images-detector
Organika/sdxl-detector
XenArcAI/AIRealNet

FORENSICS_DEVICE=auto uses CUDA when available, then MPS, then CPU. You can force a device:

text
FORENSICS_DEVICE=cuda
FORENSICS_DEVICE=cpu

The CLIP detector uses zero-shot prompt agreement as a weak semantic ML signal. The app also runs several dedicated Hugging Face image classifiers as separate detector rows. If a model cannot be downloaded or loaded, that detector returns not_loaded or error and does not crash the Space.

The dashboard includes an ML consensus metric. This helps explain cases where the full forensic ensemble is uncertain but the dedicated AI-image models lean strongly AI-generated.

9. Heatmap controls

Per-model heatmaps are generated with occlusion sensitivity. The app hides image tiles, re-runs each ML model, and highlights regions that most affect that model's suspicious-output score. Blue regions had lower impact; orange/red regions had stronger impact on that model's suspicious score.

text
ENABLE_MODEL_HEATMAPS=1
PROCESSING_MAX_SIDE=1600
PATCH_TILE_SIZE=48
MODEL_HEATMAP_GRID=7
MODEL_HEATMAP_BATCH_SIZE=32

For a strong GPU, try:

text
PROCESSING_MAX_SIDE=2048
PATCH_TILE_SIZE=32
MODEL_HEATMAP_GRID=9
MODEL_HEATMAP_BATCH_SIZE=48

Use ENABLE_MODEL_HEATMAPS=0 to disable per-model heatmaps.

10. Limitations

No detector is 100% accurate. Metadata can be stripped or forged. Compression, screenshots, social-media resizing, edits, and adversarial manipulation can hide forensic signals or create false signals. Different ML detectors can disagree because they were trained on different datasets and generator families.

11. Ethical disclaimer

Use this Space as an assistive forensic triage tool. Do not use it as the sole basis for accusations, moderation decisions, legal claims, hiring decisions, or other high-impact judgments. Always combine detector signals with source context, chain of custody, and expert review when stakes are high.