|
|
|
@@ -1,172 +1,232 @@
|
|
|
|
|
\# SpectralForensics
|
|
|
|
|
# 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.
|
|
|
|
|
|
|
|
|
|
SpectralForensics is an open-source Python library for image forensic analysis using \*\*Fast Fourier Transform (FFT)\*\* and frequency-domain feature extraction.
|
|
|
|
|
> [!NOTE]
|
|
|
|
|
> SpectralForensics is under active development. The public API and extracted features may change before the first stable release.
|
|
|
|
|
|
|
|
|
|
## Features
|
|
|
|
|
|
|
|
|
|
### Spectral analysis
|
|
|
|
|
|
|
|
|
|
The library was designed to support research in digital image forensics, synthetic media detection, diffusion model analysis, and explainable artificial intelligence (XAI).
|
|
|
|
|
- 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
|
|
|
|
|
|
|
|
|
|
\## Features
|
|
|
|
|
### Residual-noise analysis
|
|
|
|
|
|
|
|
|
|
- Residual-noise energy
|
|
|
|
|
- Residual-noise standard deviation
|
|
|
|
|
- Mean absolute residual noise
|
|
|
|
|
- Raw and normalized residual-noise maps
|
|
|
|
|
|
|
|
|
|
### Dataset and visualization tools
|
|
|
|
|
|
|
|
|
|
SpectralForensics extracts a set of interpretable spectral descriptors from images:
|
|
|
|
|
- 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
|
|
|
|
|
|
|
|
|
|
\- Spectral Entropy
|
|
|
|
|
|
|
|
|
|
\- Anisotropy
|
|
|
|
|
|
|
|
|
|
\- Dominant Frequency
|
|
|
|
|
|
|
|
|
|
\- Energy Density
|
|
|
|
|
|
|
|
|
|
\- High Frequency Ratio
|
|
|
|
|
|
|
|
|
|
\- Mean Spectral Energy
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
These descriptors can be used for:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
\- AI-generated image detection
|
|
|
|
|
|
|
|
|
|
\- Deepfake forensics
|
|
|
|
|
|
|
|
|
|
\- Diffusion model fingerprinting
|
|
|
|
|
|
|
|
|
|
\- Frequency-domain analysis
|
|
|
|
|
|
|
|
|
|
\- Explainable machine learning pipelines
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
\## Installation
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
\### Local installation
|
|
|
|
|
|
|
|
|
|
## Installation
|
|
|
|
|
|
|
|
|
|
Clone the repository and install it in editable mode:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
|
|
|
|
py -m pip install -e .
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
\\### Future PyPI installation
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
pip install spectralforensics
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
\\## Quick Start
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
\\### Extract Features from a Single Image
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```python
|
|
|
|
|
|
|
|
|
|
from spectralforensics import extract\\\_spectral\\\_features
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
features = extract\\\_spectral\\\_features("image.jpg")
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
print(features)
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
\### Example Output
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Analyse a single image
|
|
|
|
|
|
|
|
|
|
```python
|
|
|
|
|
from spectralforensics import extract_features
|
|
|
|
|
|
|
|
|
|
{
|
|
|
|
|
|
|
|
|
|
\  "filename": "image.jpg",
|
|
|
|
|
|
|
|
|
|
\  "spectral\\\_entropy": 2.31,
|
|
|
|
|
|
|
|
|
|
\  "anisotropy": 0.021,
|
|
|
|
|
|
|
|
|
|
\  "dominant\\\_frequency": 12.7,
|
|
|
|
|
|
|
|
|
|
\  "energy\\\_density": 58210.3,
|
|
|
|
|
|
|
|
|
|
\  "high\\\_frequency\\\_ratio": 0.000091,
|
|
|
|
|
|
|
|
|
|
\  "mean\\\_energy": 58210.3
|
|
|
|
|
|
|
|
|
|
}
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
\---
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
\### Extract Features from an Entire Folder
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Analyse a folder
|
|
|
|
|
|
|
|
|
|
```python
|
|
|
|
|
from spectralforensics import extract_features
|
|
|
|
|
|
|
|
|
|
from spectralforensics import extract\\\_features\\\_from\\\_folder
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
df = extract\\\_features\\\_from\\\_folder(
|
|
|
|
|
|
|
|
|
|
\  folder\\\_path="dataset",
|
|
|
|
|
|
|
|
|
|
\  output\\\_csv="results.csv"
|
|
|
|
|
|
|
|
|
|
data = extract_features(
|
|
|
|
|
"images/",
|
|
|
|
|
output_csv="spectral_features.csv",
|
|
|
|
|
output="quantitative",
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
print(df.head())
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
\### Example Output
|
|
|
|
|
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")
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
| filename | spectral\_entropy | anisotropy | dominant\_frequency | energy\_density | high\_frequency\_ratio |
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
| real\_001.jpg | 1.21 | 0.012 | 11.0 | 91327 | 0.000037 |
|
|
|
|
|
Use the `output` argument to control which results are calculated and returned:
|
|
|
|
|
|
|
|
|
|
| dalle\_001.png | 2.50 | 0.034 | 16.0 | 68150 | 0.000177 |
|
|
|
|
|
| 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 |
|
|
|
|
|
|
|
|
|
|
| flux\_001.jpg | 2.51 | 0.019 | 6.0 | 61004 | 0.000064 |
|
|
|
|
|
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.
|
|
|
|
|