2026-10-27 10:12:25 +00:00
2026-10-27 10:12:25 +00:00
2026-10-27 10:12:25 +00:00
2026-10-26 16:07:39 +00:00
2026-10-27 09:14:16 +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 <your-repository-url>
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

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
  • Patricio Rodrigues
  • Carlos Grilo
  • Rolando Miragaia

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.

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