From 3cb712c5826e0cfcf8c7ea7e81256e308994a9d5 Mon Sep 17 00:00:00 2001 From: Jose Garcia Date: Tue, 16 Jun 2026 18:38:08 +0100 Subject: [PATCH] first commit --- README.md | 292 ++++++++++++++++++ pyproject.toml | 34 ++ spectralforensics.egg-info/PKG-INFO | 14 + spectralforensics.egg-info/SOURCES.txt | 10 + .../dependency_links.txt | 1 + spectralforensics.egg-info/requires.txt | 3 + spectralforensics.egg-info/top_level.txt | 1 + spectralforensics/__init__.py | 4 + spectralforensics/dataset.py | 32 ++ spectralforensics/features.py | 44 +++ 10 files changed, 435 insertions(+) create mode 100644 README.md create mode 100644 pyproject.toml create mode 100644 spectralforensics.egg-info/PKG-INFO create mode 100644 spectralforensics.egg-info/SOURCES.txt create mode 100644 spectralforensics.egg-info/dependency_links.txt create mode 100644 spectralforensics.egg-info/requires.txt create mode 100644 spectralforensics.egg-info/top_level.txt create mode 100644 spectralforensics/__init__.py create mode 100644 spectralforensics/dataset.py create mode 100644 spectralforensics/features.py diff --git a/README.md b/README.md new file mode 100644 index 0000000..2fdbf28 --- /dev/null +++ b/README.md @@ -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 + diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..c33d3f6 --- /dev/null +++ b/pyproject.toml @@ -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" +] \ No newline at end of file diff --git a/spectralforensics.egg-info/PKG-INFO b/spectralforensics.egg-info/PKG-INFO new file mode 100644 index 0000000..bc79886 --- /dev/null +++ b/spectralforensics.egg-info/PKG-INFO @@ -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 diff --git a/spectralforensics.egg-info/SOURCES.txt b/spectralforensics.egg-info/SOURCES.txt new file mode 100644 index 0000000..1c64013 --- /dev/null +++ b/spectralforensics.egg-info/SOURCES.txt @@ -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 \ No newline at end of file diff --git a/spectralforensics.egg-info/dependency_links.txt b/spectralforensics.egg-info/dependency_links.txt new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/spectralforensics.egg-info/dependency_links.txt @@ -0,0 +1 @@ + diff --git a/spectralforensics.egg-info/requires.txt b/spectralforensics.egg-info/requires.txt new file mode 100644 index 0000000..04ca854 --- /dev/null +++ b/spectralforensics.egg-info/requires.txt @@ -0,0 +1,3 @@ +numpy +pandas +pillow diff --git a/spectralforensics.egg-info/top_level.txt b/spectralforensics.egg-info/top_level.txt new file mode 100644 index 0000000..e48e3a1 --- /dev/null +++ b/spectralforensics.egg-info/top_level.txt @@ -0,0 +1 @@ +spectralforensics diff --git a/spectralforensics/__init__.py b/spectralforensics/__init__.py new file mode 100644 index 0000000..c186524 --- /dev/null +++ b/spectralforensics/__init__.py @@ -0,0 +1,4 @@ +from .features import extract_spectral_features +from .dataset import extract_features_from_folder + +__version__ = "0.1.0" \ No newline at end of file diff --git a/spectralforensics/dataset.py b/spectralforensics/dataset.py new file mode 100644 index 0000000..3e28b57 --- /dev/null +++ b/spectralforensics/dataset.py @@ -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 \ No newline at end of file diff --git a/spectralforensics/features.py b/spectralforensics/features.py new file mode 100644 index 0000000..bda667e --- /dev/null +++ b/spectralforensics/features.py @@ -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) + } \ No newline at end of file