diff --git a/README.md b/README.md index 2fdbf28..2faf858 100644 --- a/README.md +++ b/README.md @@ -1,292 +1,86 @@ -SpectralForensics - - - -SpectralForensics is an open-source Python library for image forensic analysis using Fast Fourier Transform (FFT) and frequency-domain feature extraction. - +# 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 - - +## Features SpectralForensics extracts a set of interpretable spectral descriptors from images: - - -Spectral Entropy - -Anisotropy - -Dominant Frequency - -Energy Density - -High Frequency Ratio - -Mean Spectral Energy - - +- 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 -AI-generated image detection - -Deepfake forensics - -Diffusion model fingerprinting - -Frequency-domain analysis - -Explainable machine learning pipelines - -Installation - -Local installation +### Local installation +```bash py -m pip install -e . -Future PyPI installation + +### Future PyPI installation pip install spectralforensics -Supported Image Formats +## Quick Start +### Extract Features from a Single Image -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" - -) - +```python +from spectralforensics import extract_spectral_features +features = extract_spectral_features("image.jpg") print(features) +``` +### Example Output - -Example output: - - - +```python { - - "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 - + "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 +### Extract Features from an Entire Folder +```python +from spectralforensics import extract_features_from_folder - -df = extract\_features\_from\_folder( - - folder\_path="dataset", - - output\_csv="results.csv" - +df = extract_features_from_folder( + folder_path="dataset", + output_csv="results.csv" ) - - print(df.head()) +``` +### Example Output - -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 - +| 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 |