Files
spectralforensics/README.md
T
2026-10-27 09:14:16 +00:00

233 lines
6.5 KiB
Markdown

# 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 <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
```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.