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
Issues, suggestions, and contributions are welcome. For substantial changes, open an issue first to discuss the proposed approach and its impact on the public API.
Citation
If you use SpectralForensics in academic work, please cite the repository. A formal citation and publication reference will be added as the project matures.