SpectralForensics
SpectralForensics is an open-source Python library for explainable digital image forensics. It extracts interpretable descriptors from the frequency, spatial, and residual-noise domains and provides interactive tools for exploring the resulting data.
The project is being developed to support research into AI-generated image detection, synthetic media analysis, diffusion-model fingerprints, and explainable machine-learning pipelines.
Note
SpectralForensics is under active development. The public API and extracted features may change before the first stable release.
Features
Spectral analysis
- Spectral entropy
- Anisotropy
- Dominant frequency
- Energy density and mean energy
- High-frequency energy ratio
- Normalized FFT spectrum for visualization
Spatial analysis
- Mean brightness and darkness
- Gradient magnitude
- Local entropy
- Local variance
- Normalized visual maps for each spatial descriptor
Residual-noise analysis
- Residual-noise energy
- Residual-noise standard deviation
- Mean absolute residual noise
- Raw and normalized residual-noise maps
Dataset and visualization tools
- Feature extraction from a single image or a complete folder
- Sequential renaming of real and AI-generated image datasets
- Optional CSV export
- Support for JPG, JPEG, PNG, BMP, TIFF, and WebP images
- Interactive line, bar, scatter, box, and correlation plots
- Selection and filtering of multiple variables directly in the plot window
Requirements
- Python 3.10 or newer
- A graphical desktop environment for the interactive plotting tools
- Tkinter, normally included with standard Python installations
Installation
Clone the repository and install it in editable mode:
git clone https://gittea.kl3z00.com/kl3z/spectralforensics
cd spectralforensics
python -m pip install -e .
The package is not yet advertised as a stable PyPI release.
Quick start
Analyse a single image
from spectralforensics import extract_features
features = extract_features("images/sample.jpg")
print(features["spectral_entropy"])
print(features["mean_gradient"])
print(features["residual_noise_energy"])
For a single image, extract_features returns a dictionary containing the file metadata and the requested descriptors.
Analyse a folder
from spectralforensics import extract_features
data = extract_features("images/", output_csv="spectral_features.csv",output="quantitative")
print(data.head())
When a directory is provided, the function processes supported images in that directory and returns a pandas DataFrame. Folder traversal is currently non-recursive.
Prepare image filenames
SpectralForensics can rename all supported images in a folder using the
real or gen prefixes:
from spectralforensics import rename_generated_images, rename_real_images
real_files = rename_real_images("dataset/real")
generated_files = rename_generated_images("dataset/generated")
The resulting filenames follow the real1.jpg, real2.png, gen1.jpg, and gen2.png patterns. Each function returns a list of the new paths. Renaming is non-recursive and preserves each image format.
Extraction modes
Use the output argument to control which results are calculated and returned:
| Mode | Result |
|---|---|
"all" |
All quantitative descriptors and visual maps |
"spectral" |
Spectral descriptors only |
"spatial" |
Spatial descriptors only |
"residual" |
Residual-noise descriptors only |
"quantitative" |
All numerical descriptors, without visual maps |
"visual" |
Visual maps, without quantitative descriptors |
The use image_size is set as default image_size=(255, 255); however, the module is designed to support other image dimensions.
Example:
features = extract_features("images/sample.jpg", image_size=(255, 255), high_freq_threshold=0.65, output="spectral", )
If a filename contains gen, the generated-image target is set to "0". If it contains real, the target is set to "1"; otherwise, the target is left as None.
Interactive visualizations
The plotting functions accept dictionaries, pandas DataFrame objects, and other data structures supported by pandas.DataFrame.
from spectralforensics import line_plot, scatter_plot
data = {"sample": [1, 2, 3, 4, 5], "spectral_entropy": [2.1, 2.5, 2.2, 2.9, 2.6],"anisotropy": [0.10, 0.30, 0.20, 0.40, 0.25],}
line_plot(data, x="sample", y="spectral_entropy")
scatter_plot(data, x="spectral_entropy", y="anisotropy")
Available plotting functions:
from spectralforensics import (
bar_plot,
box_plot,
correlation_plot,
line_plot,
scatter_plot,
)
Correlation analysis
from spectralforensics import correlation_plot
correlation_data = {
"spectral_entropy": [2.1, 2.5, 2.2, 2.9, 2.6],
"anisotropy": [0.10, 0.30, 0.20, 0.40, 0.25],
"target": [0, 1, 0, 1, 1],
}
correlation_plot(
correlation_data,
correlation_columns=["spectral_entropy", "anisotropy", "target"],
method="pearson",
target="target",
kind="barh",
)
Set show=False to generate and retrieve the Matplotlib figure, axes, and correlation tables without opening the interactive window.
Examples
Runnable examples are available in the examples directory:
python examples/line_plot.py
python examples/bar_plot.py
python examples/scatter_plot.py
python examples/box_plot.py
python examples/correlation_plot.py
Project structure
spectralforensics/
|-- examples/ # Usage examples
|-- src/
| `-- spectralforensics/
| |-- dataset.py # File and folder processing
| |-- features.py # Feature extraction
| |-- plotting*.py # Interactive visualization tools
| `-- assets/ # Plot interface assets
|-- pyproject.toml # Package metadata and dependencies
`-- README.md
Research scope
SpectralForensics is intended as a research and experimentation toolkit. Extracted descriptors can support statistical analysis and machine-learning models, but they should not be treated as standalone proof that an image is authentic or AI-generated.
Authors
- Jose Garcia - University of Leiria and Oeste (ULO)
- Patricio Rodrigues - University of Leiria and Oeste (ULO)
- Carlos Grilo - University of Leiria and Oeste (ULO)
- Rolando Miragaia - University of Leiria and Oeste (ULO)
Contributing
Contactar
Citation
Artigo