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

v0.2.0: asian data

🛡️ DeepGuard v0.2.0 — 2nd-gen Asian Release

Deployment-ready DeepFake detection weights built for high-traffic inference.
The 2nd generation extends coverage to Korean data via KoDF — a Large-Scale Korean DeepFake Detection Dataset.

---

📦 Available Weights

Architecture	Variant	kodf
MS-EffGCViT	b0	✅
MS-EffGCViT	b5	✅

• b0 → Fast variant (lightweight, CPU-friendly)
• b5 → Pro variant (high precision)

---

🚀 Usage

Option A. timm API

Install the package and import deepguard to register the models into the timm registry.

!pip install -q git+https://github.com/HanMoonSub/DeepGuard.git
 
import timm
import deepguard  # registers models into timm
 
model = timm.create_model("ms_eff_gcvit_b0", pretrained=True, dataset="kodf")
model = timm.create_model("ms_eff_gcvit_b5", pretrained=True, dataset="kodf")

Option B. Direct deepguard import ✨ (recommended)

Import the model builders directly — no timm dependency required.

!pip install -q git+https://github.com/HanMoonSub/DeepGuard.git
 
from deepguard import ms_eff_gcvit_b0, ms_eff_gcvit_b5
 
model = ms_eff_gcvit_b0(pretrained=True, dataset="kodf")
model = ms_eff_gcvit_b5(pretrained=True, dataset="kodf")

---

🔧 Arguments

Arg	Type	Options	Description
pretrained	bool	True / False	Load pretrained weights
dataset	str	"kodf"	Training dataset of the weights to load

---

🔁 Changelog

• ➕ Added kodf weights for ms_eff_gcvit_b0 and ms_eff_gcvit_b5
• 🌏 Expanded dataset coverage from Western (celeb_df_v2, ff++) to Korean (kodf)

v0.1.0: 1st-gen western data

🛡️ DeepGuard v0.1.0 — 1st-gen Western Release

Deployment-ready DeepFake detection weights built for high-traffic inference.
The 1st generation is trained on Western datasets (Celeb-DF-v2, FaceForensics++).

---

📦 Available Weights

Architecture	Variant	celeb_df_v2	ff++
MS-EffViT	b0	✅	✅
MS-EffViT	b5	✅	✅
MS-EffGCViT	b0	✅	✅
MS-EffGCViT	b5	✅	✅

• b0 → Fast variant (lightweight, CPU-friendly)
• b5 → Pro variant (high precision)

---

🚀 Usage

Option A. timm API

Clone the repo and import deepguard to register the models into the timm registry.

!git clone https://github.com/HanMoonSub/DeepGuard.git
%cd DeepGuard
 
import timm
import deepguard  # registers models into timm
 
model = timm.create_model("ms_eff_gcvit_b0", pretrained=True, dataset="celeb_df_v2")
model = timm.create_model("ms_eff_gcvit_b5", pretrained=True, dataset="ff++")

Option B. Direct deepguard import ✨ (recommended)

Install the package and import the model builders directly — no timm dependency required.

!pip install deepguard
# latest dev build: pip install -U git+https://github.com/HanMoonSub/DeepGuard.git
 
from deepguard import ms_eff_gcvit_b0, ms_eff_gcvit_b5
 
model = ms_eff_gcvit_b0(pretrained=True, dataset="celeb_df_v2")
model = ms_eff_gcvit_b5(pretrained=True, dataset="ff++")

---

🔧 Arguments

Arg	Type	Options	Description
pretrained	bool	True / False	Load pretrained weights
dataset	str	"celeb_df_v2", "ff++"	Training dataset of the weights to load

---

📋 Full Model List

from deepguard import (
    ms_eff_vit_b0,
    ms_eff_vit_b5,
    ms_eff_gcvit_b0,
    ms_eff_gcvit_b5,
)
 
# each supports: dataset="celeb_df_v2" | "ff++"