first commit

This commit is contained in:
2026-06-16 18:38:08 +01:00
commit 3cb712c582
10 changed files with 435 additions and 0 deletions
+292
View File
@@ -0,0 +1,292 @@
SpectralForensics
SpectralForensics is an open-source Python library for image forensic analysis using Fast Fourier Transform (FFT) and frequency-domain feature extraction.
The library was designed to support research in digital image forensics, synthetic media detection, diffusion model analysis, and explainable artificial intelligence (XAI).
Features
SpectralForensics extracts a set of interpretable spectral descriptors from images:
Spectral Entropy
Anisotropy
Dominant Frequency
Energy Density
High Frequency Ratio
Mean Spectral Energy
These descriptors can be used for:
AI-generated image detection
Deepfake forensics
Diffusion model fingerprinting
Frequency-domain analysis
Explainable machine learning pipelines
Installation
Local installation
py -m pip install -e .
Future PyPI installation
pip install spectralforensics
Supported Image Formats
The library currently supports:
JPG
JPEG
PNG
BMP
TIFF
WEBP
Additional formats can easily be added.
Quick Start
Extract features from a single image
from spectralforensics import extract\_spectral\_features
features = extract\_spectral\_features(
  "image.jpg"
)
print(features)
Example output:
{
  "filename": "image.jpg",
  "spectral\_entropy": 2.31,
  "anisotropy": 0.021,
  "dominant\_frequency": 12.7,
  "energy\_density": 58210.3,
  "high\_frequency\_ratio": 0.000091,
  "mean\_energy": 58210.3
}
Extract features from an entire folder
from spectralforensics import extract\_features\_from\_folder
df = extract\_features\_from\_folder(
  folder\_path="dataset",
  output\_csv="results.csv"
)
print(df.head())
Example output:
filename spectral\_entropy anisotropy dominant\_frequency energy\_density high\_frequency\_ratio
real\_001.jpg 1.21 0.012 11.0 91327 0.000037
dalle\_001.png 2.50 0.034 16.0 68150 0.000177
flux\_001.jpg 2.51 0.019 6.0 61004 0.000064
Spectral Features
Spectral Entropy
Measures the randomness of the spectral energy distribution.
Higher values generally indicate a more dispersed frequency distribution.
Anisotropy
Measures directional imbalance of spectral energy.
Can reveal artificial directional patterns introduced by generative models.
Dominant Frequency
Represents the strongest non-DC frequency component in the Fourier spectrum.
Energy Density
Measures the amount of spectral energy normalized by image size.
High Frequency Ratio
Measures the proportion of energy located in high-frequency regions.
Useful for detecting residual artefacts and synthetic textures.
Scientific Background
Diffusion-based generative models such as:
Stable Diffusion
FLUX
DALL·E
Midjourney
generate images through iterative denoising processes.
Although visually realistic, these models may introduce latent frequency-domain artefacts that remain detectable through Fourier analysis.
SpectralForensics aims to provide an explainable framework for investigating these spectral fingerprints and supporting synthetic media detection research.
Research Applications
Potential applications include:
Digital Image Forensics
Deepfake Detection
AI-Generated Content Verification
Synthetic Media Analysis
Explainable AI (XAI)
Frequency-Domain Machine Learning
Cybersecurity Research
Roadmap
Future planned features:
Radial Distribution Analysis
Spectral Heatmaps
Average FFT Fingerprints
Statistical Validation (t-test, ANOVA, Mann–Whitney)
Random Forest Classification
SVM Classification
XGBoost Classification
Diffusion Model Attribution
Batch Processing Pipelines
S
+34
View File
@@ -0,0 +1,34 @@
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
[project]
name = "spectralforensics"
version = "0.1.0"
description = "Spectral feature extraction for image forensic analysis using FFT"
readme = "README.md"
requires-python = ">=3.10"
authors = [
{name = "Jose Garcia"}
]
dependencies = [
"numpy",
"pandas",
"pillow"
]
keywords = [
"fft",
"image forensics",
"deepfake detection",
"frequency analysis",
"spectral fingerprints"
]
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent"
]
+14
View File
@@ -0,0 +1,14 @@
Metadata-Version: 2.4
Name: spectralforensics
Version: 0.1.0
Summary: Spectral feature extraction for image forensic analysis using FFT
Author: Jose Garcia
Keywords: fft,image forensics,deepfake detection,frequency analysis,spectral fingerprints
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pillow
+10
View File
@@ -0,0 +1,10 @@
README.md
pyproject.toml
spectralforensics/__init__.py
spectralforensics/dataset.py
spectralforensics/features.py
spectralforensics.egg-info/PKG-INFO
spectralforensics.egg-info/SOURCES.txt
spectralforensics.egg-info/dependency_links.txt
spectralforensics.egg-info/requires.txt
spectralforensics.egg-info/top_level.txt
@@ -0,0 +1 @@
+3
View File
@@ -0,0 +1,3 @@
numpy
pandas
pillow
+1
View File
@@ -0,0 +1 @@
spectralforensics
+4
View File
@@ -0,0 +1,4 @@
from .features import extract_spectral_features
from .dataset import extract_features_from_folder
__version__ = "0.1.0"
+32
View File
@@ -0,0 +1,32 @@
from pathlib import Path
import pandas as pd
from .features import extract_spectral_features
SUPPORTED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".bmp", ".tif", ".tiff", ".webp"}
def extract_features_from_folder(folder_path,output_csv=None,image_size=(512, 512),high_freq_threshold=0.65):
folder_path = Path(folder_path)
if not folder_path.exists():
raise FileNotFoundError(f"Folder not found: {folder_path}")
image_files = [
file for file in folder_path.iterdir()
if file.suffix.lower() in SUPPORTED_EXTENSIONS
]
results = []
for image_file in image_files:
try:
features = extract_spectral_features(
image_file,
image_size=image_size,
high_freq_threshold=high_freq_threshold
)
results.append(features)
except Exception as e:
results.append({
"filename": image_file.name,
"path": str(image_file),
"error": str(e)
})
df = pd.DataFrame(results)
if output_csv:
df.to_csv(output_csv, index=False, encoding="utf-8-sig")
return df
+44
View File
@@ -0,0 +1,44 @@
from pathlib import Path
import numpy as np
from PIL import Image
def extract_spectral_features(image_path,image_size=(512, 512), high_freq_threshold=0.65, center_exclusion=5):
image_path = Path(image_path)
img = Image.open(image_path).convert("L")
img = img.resize(image_size)
img_array = np.array(img, dtype=np.float32) / 255.0
fft = np.fft.fft2(img_array)
fft_shift = np.fft.fftshift(fft)
magnitude = np.abs(fft_shift)
energy = magnitude ** 2
total_energy = np.sum(energy) + 1e-12
mean_energy = np.mean(energy)
probability = energy / total_energy
spectral_entropy = -np.sum(probability * np.log2(probability + 1e-12))
h, w = energy.shape
cy, cx = h // 2, w // 2
y, x = np.indices((h, w))
radius = np.sqrt((x - cx) ** 2 + (y - cy) ** 2)
horizontal_energy = np.sum(energy[cy - 2:cy + 3, :])
vertical_energy = np.sum(energy[:, cx - 2:cx + 3])
anisotropy = abs(horizontal_energy - vertical_energy) / (horizontal_energy + vertical_energy + 1e-12)
energy_no_center = energy.copy()
energy_no_center[cy - center_exclusion:cy + center_exclusion + 1,cx - center_exclusion:cx + center_exclusion + 1] = 0
dominant_position = np.unravel_index(np.argmax(energy_no_center),energy_no_center.shape)
dominant_frequency = radius[dominant_position]
energy_density = total_energy / (h * w)
max_radius = np.max(radius)
high_freq_mask = radius > (high_freq_threshold * max_radius)
high_frequency_energy = np.sum(energy[high_freq_mask])
high_frequency_ratio = high_frequency_energy / total_energy
return {
"filename": image_path.name,
"path": str(image_path),
"spectral_entropy": float(spectral_entropy),
"anisotropy": float(anisotropy),
"dominant_frequency": float(dominant_frequency),
"energy_density": float(energy_density),
"high_frequency_ratio": float(high_frequency_ratio),
"mean_energy": float(mean_energy)
}