# 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: ```bash git clone cd spectralforensics python -m pip install -e . ``` The package is not yet advertised as a stable PyPI release. ## Quick start ### Analyse a single image ```python 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 ```python 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: ```python 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: ```python 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`. ```python 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: ```python from spectralforensics import ( bar_plot, box_plot, correlation_plot, line_plot, scatter_plot, ) ``` ### Correlation analysis ```python 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`](examples) directory: ```bash 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 ```text 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.