Deepfake XAI

🎨 DeepFake-XAI

v0.3.0 introduces a production-ready XAI Toolkit that turns DeepGuard's black-box deepfake score into actionable forensic evidence — visualizing where and why the model flags a face as manipulated.

Validated on the hybrid CNN-ViT architectures MS-EffViT and MS-EffGCViT.

---

✨ Highlights

• Dual-Branch Explainability — heatmaps mirror the model's own multi-scale reasoning, with each XAI method assigned to the branch where it performs best empirically.
• 6 CAM methods across low/high branches.
• 3 visualization modes — heatmap, bounding box, and full overlay.

---

🧠 Dual-Branch Analysis

Branch	Feature Map	Focus	Best For
🔵 Low-level	High Resolution	Local forgery artifacts	Skin texture, boundary blending, compression traces
🔴 High-level	Low Resolution	Global semantic structure	Lighting inconsistency, facial geometry, shadow artifacts

Smoothing options

• aug_smooth — TTA (horizontal flips) averaged before CAM → smoother, more object-aligned maps
• eigen_smooth — PCA noise reduction → retains the dominant forgery pattern only

---

💡 Usage

Pick an explainer from the branch you want, then call one of the visualization modes.

from explainability import HiResCAMExplainer, EigenGradCAMExplainer
Low-Level Branch — Local Artifact Detection
explainer = HiResCAMExplainer(

model_name   = "ms_eff_gcvit_b0",  # or ms_eff_vit_b0, ms_eff_gcvit_b5, ms_eff_vit_b5

dataset      = "celeb_df_v2",      # or ff++, kodf

branch_level = "low",

)

---

🎨 Visualization Modes

1. Heatmap — Continuous activation distribution

result = explainer.display_heatmap_on_image(
    img_path     = "path/to/image.jpg",
    category     = 1,      # 0: Real, 1: Fake
    threshold    = 0.5,    # binarization cutoff (0.5~1.0), or "auto" for Otsu
    image_weight = 0.5,    # 0.0: heatmap only ← → 1.0: original only
    aug_smooth   = False,  # TTA smoothing (not supported on 'pro' models)
    eigen_smooth = False,  # PCA noise reduction
)

2. Bounding Box — Discrete forgery region localization

result = explainer.display_bbox_on_image(
    img_path     = "path/to/image.jpg",
    category     = 1,
    threshold    = 0.5,
    thickness    = 1,
    aug_smooth   = False,
    eigen_smooth = False,
)

3. Heatmap + BBox — Full overlay (recommended for reporting)

result = explainer.display_heatmap_bbox_on_image(
    img_path     = "path/to/image.jpg",
    category     = 1,
    threshold    = 0.5,
    image_weight = 0.5,
    aug_smooth   = False,
    eigen_smooth = False,
)

---

📦 Supported Models & Datasets

• Architectures: ms_eff_vit_b0/b5, ms_eff_gcvit_b0/b5
• Datasets: celeb_df_v2, ff++, kodf

---

Full Changelog: https://github.com/HanMoonSub/DeepGuard/compare/v0.2.0...v0.3.0