2026-10-27 09:51:07 +00:00
2026-10-26 16:07:39 +00:00
2026-10-27 09:28:01 +00:00
2026-10-26 16:07:39 +00:00
2026-10-27 09:51:07 +00:00

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

S
Description
No description provided
Readme 1.5 MiB
Languages
Python 100%