spectralforensics

This commit is contained in:
2026-07-22 20:04:52 +01:00
parent 3cb712c582
commit 861242b3e7
23 changed files with 666 additions and 303 deletions
+187
View File
@@ -0,0 +1,187 @@
Metadata-Version: 2.4
Name: spectralforensics
Version: 0.1.0
Summary: Explainable spectral forensic analysis
Author: José Garcia, Patricio Rodrigues, Carlos Grilo, Rolando Miragaia
Maintainer-email: José Garcia <2023144112@my.ipleiria.pt>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: pillow
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: scikit-image
\# SpectralForensics
SpectralForensics is an open-source Python library for image forensic analysis using \*\*Fast Fourier Transform (FFT)\*\* and frequency-domain feature extraction.
The library was designed to support research in digital image forensics, synthetic media detection, diffusion model analysis, and explainable artificial intelligence (XAI).
\## Features
SpectralForensics extracts a set of interpretable spectral descriptors from images:
\- 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
```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)
```
\### Example Output
```python
{
\&#x20; "filename": "image.jpg",
\&#x20; "spectral\\\_entropy": 2.31,
\&#x20; "anisotropy": 0.021,
\&#x20; "dominant\\\_frequency": 12.7,
\&#x20; "energy\\\_density": 58210.3,
\&#x20; "high\\\_frequency\\\_ratio": 0.000091,
\&#x20; "mean\\\_energy": 58210.3
}
```
\---
\### Extract Features from an Entire Folder
```python
from spectralforensics import extract\\\_features\\\_from\\\_folder
df = extract\\\_features\\\_from\\\_folder(
\&#x20; folder\\\_path="dataset",
\&#x20; output\\\_csv="results.csv"
)
print(df.head())
```
\### Example Output
| filename | spectral\_entropy | anisotropy | dominant\_frequency | energy\_density | high\_frequency\_ratio |
|-----------|----------------|------------|-------------------|----------------|---------------------|
| real\_001.jpg | 1.21 | 0.012 | 11.0 | 91327 | 0.000037 |
| dalle\_001.png | 2.50 | 0.034 | 16.0 | 68150 | 0.000177 |
| flux\_001.jpg | 2.51 | 0.019 | 6.0 | 61004 | 0.000064 |
@@ -0,0 +1,15 @@
README.md
pyproject.toml
spectralforensics.egg-info/PKG-INFO
spectralforensics.egg-info/SOURCES.txt
spectralforensics.egg-info/dependency_links.txt
spectralforensics.egg-info/requires.txt
spectralforensics.egg-info/top_level.txt
src/spectralforensics/__init__.py
src/spectralforensics/dataset.py
src/spectralforensics/features.py
src/spectralforensics.egg-info/PKG-INFO
src/spectralforensics.egg-info/SOURCES.txt
src/spectralforensics.egg-info/dependency_links.txt
src/spectralforensics.egg-info/requires.txt
src/spectralforensics.egg-info/top_level.txt
@@ -0,0 +1 @@
@@ -0,0 +1,6 @@
numpy
pillow
pandas
scipy
matplotlib
scikit-image
@@ -0,0 +1 @@
spectralforensics
+3
View File
@@ -0,0 +1,3 @@
from .dataset import extract_features
__all__ = ["extract_features"]
+28
View File
@@ -0,0 +1,28 @@
from pathlib import Path
import pandas as pd
from .features import extract_features as extract_image_features
from tqdm import tqdm
support_ext = {".jpg", ".jpeg", ".png", ".bmp", ".tif", ".tiff", ".webp"}
def extract_features(path, output_csv=None, image_size=(255, 255), high_freq_threshold=0.65, output="all", show_progress=True):
path = Path(path)
if not path.exists():
raise FileNotFoundError(f"Path not found: {path}")
if path.is_file():
if path.suffix.lower() not in support_ext:
raise ValueError(f"Unsupported image format: {path.suffix}")
return extract_image_features(path, image_size=image_size, high_freq_threshold=high_freq_threshold, output=output)
image_files = [file for file in path.iterdir() if file.is_file() and file.suffix.lower() in support_ext]
iterator = (tqdm(image_files,total=len(image_files),desc="Extracting features",unit="image") if show_progress else image_files)
results = []
for image_file in iterator:
try:
features = extract_image_features(image_file, image_size=image_size, high_freq_threshold=high_freq_threshold, output=output)
results.append(features)
except Exception as e:
results.append({"filename": image_file.name, "path": str(image_file), "error": str(e)})
df = pd.DataFrame(results)
if output_csv:
df.to_csv(output_csv, index=False, encoding="utf-8-sig")
return df
+148
View File
@@ -0,0 +1,148 @@
from pathlib import Path
import numpy as np
from PIL import Image
from scipy.ndimage import median_filter, sobel, uniform_filter
from skimage.filters.rank import entropy
from skimage.morphology import disk
def extract_features(image_path, image_size=(255, 255), high_freq_threshold=0.65, center_exclusion=5, output="all"):
image_path = Path(image_path)
output = str(output).lower()
valid_outputs = {"all", "spectral", "spatial", "residual", "quantitative", "visual"}
if output not in valid_outputs:
raise ValueError("output must be one of: 'all', 'spectral', 'spatial', 'residual', 'quantitative', 'visual'")
if not image_path.exists():
raise FileNotFoundError(f"Image not found: {image_path}")
if not image_path.is_file():
raise ValueError(f"Expected an image file: {image_path}")
image = Image.open(image_path).convert("L")
image = image.resize(image_size)
img_array = np.asarray(image, dtype=np.float32) / np.float32(255.0)
filename_lower = image_path.name.lower()
if "gen" in filename_lower:
target = "0"
elif "real" in filename_lower:
target = "1"
else:
target = None
results = {"filename": image_path.name,"path": str(image_path),"target": target}
calculate_spectral = output in {"all", "spectral", "quantitative", "visual"}
calculate_spatial = output in {"all", "spatial", "quantitative", "visual"}
calculate_residual = output in {"all", "residual", "quantitative", "visual"}
return_spectral_values = output in {"all", "spectral", "quantitative"}
return_spatial_values = output in {"all", "spatial", "quantitative"}
return_residual_values = output in {"all", "residual", "quantitative"}
return_visual_maps = output in {"all", "visual"}
if calculate_spectral:
fft = np.fft.fft2(img_array)
fft_shift = np.fft.fftshift(fft)
magnitude = np.abs(fft_shift).astype(np.float32)
energy = np.square(magnitude, dtype=np.float32)
total_energy = float(np.sum(energy, dtype=np.float64)) + 1e-12
height, width = energy.shape
center_y = height // 2
center_x = width // 2
y_indices, x_indices = np.indices((height, width), dtype=np.float32)
radius = np.sqrt((x_indices - center_x) ** 2 + (y_indices - center_y) ** 2).astype(np.float32)
if return_spectral_values:
probability = energy / total_energy
spectral_entropy = -np.sum(probability * np.log2(probability + 1e-12), dtype=np.float64)
horizontal_energy = np.sum(energy[max(0, center_y - 2):min(height, center_y + 3), :], dtype=np.float64)
vertical_energy = np.sum(energy[:, max(0, center_x - 2):min(width, center_x + 3)], dtype=np.float64)
anisotropy = abs(horizontal_energy - vertical_energy) / (horizontal_energy + vertical_energy + 1e-12)
energy_no_center = energy.copy()
y_start = max(0, center_y - center_exclusion)
y_end = min(height, center_y + center_exclusion + 1)
x_start = max(0, center_x - center_exclusion)
x_end = min(width, center_x + center_exclusion + 1)
energy_no_center[y_start:y_end, x_start:x_end] = 0
dominant_position = np.unravel_index(np.argmax(energy_no_center), energy_no_center.shape)
dominant_frequency = radius[dominant_position]
energy_density = total_energy / (height * width)
maximum_radius = np.max(radius)
high_frequency_mask = radius > high_freq_threshold * maximum_radius
high_frequency_energy = np.sum(energy[high_frequency_mask], dtype=np.float64)
high_frequency_ratio = high_frequency_energy / total_energy
mean_energy = np.mean(energy, dtype=np.float64)
results.update({
"spectral_entropy": float(spectral_entropy),
"anisotropy": float(anisotropy),
"dominant_frequency": float(dominant_frequency),
"energy_density": float(energy_density),
"high_frequency_ratio": float(high_frequency_ratio),
"mean_energy": float(mean_energy)})
del probability
del energy_no_center
if return_visual_maps:
fft_spectrum_raw = np.log1p(magnitude)
fft_minimum = fft_spectrum_raw.min()
fft_maximum = fft_spectrum_raw.max()
fft_spectrum = (255.0 * (fft_spectrum_raw - fft_minimum) / (fft_maximum - fft_minimum + 1e-12)).astype(np.uint8)
results["fft_spectrum"] = fft_spectrum
del fft_spectrum_raw
del fft
del fft_shift
del magnitude
del energy
del radius
del y_indices
del x_indices
if calculate_spatial:
gradient_x = sobel(img_array, axis=1, mode="reflect").astype(np.float32)
gradient_y = sobel(img_array, axis=0, mode="reflect").astype(np.float32)
gradient_raw = np.sqrt(gradient_x ** 2 + gradient_y ** 2).astype(np.float32)
local_mean = uniform_filter(img_array, size=7, mode="reflect").astype(np.float32)
local_squared_mean = uniform_filter(np.square(img_array, dtype=np.float32), size=7, mode="reflect").astype(np.float32)
local_variance_raw = np.maximum(local_squared_mean - local_mean ** 2, 0).astype(np.float32)
image_uint8 = (img_array * 255).astype(np.uint8)
local_entropy_raw = entropy(image_uint8, footprint=disk(3)).astype(np.float32)
if return_spatial_values:
results.update({
"mean_brightness": float(np.mean(img_array, dtype=np.float64)),
"mean_darkness": float(np.mean(1.0 - img_array, dtype=np.float64)),
"mean_gradient": float(np.mean(gradient_raw, dtype=np.float64)),
"mean_local_entropy": float(np.mean(local_entropy_raw, dtype=np.float64)),
"mean_local_variance": float(np.mean(local_variance_raw, dtype=np.float64))})
if return_visual_maps:
brightness_map = img_array.copy()
darkness_map = (1.0 - img_array).astype(np.float32)
gradient_minimum = gradient_raw.min()
gradient_maximum = gradient_raw.max()
gradient_map = ((gradient_raw - gradient_minimum) / (gradient_maximum - gradient_minimum + 1e-12)).astype(np.float32)
entropy_minimum = local_entropy_raw.min()
entropy_maximum = local_entropy_raw.max()
local_entropy_map = ((local_entropy_raw - entropy_minimum) / (entropy_maximum - entropy_minimum + 1e-12)).astype(np.float32)
variance_minimum = local_variance_raw.min()
variance_maximum = local_variance_raw.max()
local_variance_map = ((local_variance_raw - variance_minimum) / (variance_maximum - variance_minimum + 1e-12)).astype(np.float32)
results.update({"brightness_map": brightness_map,"darkness_map": darkness_map,"gradient_map": gradient_map,"local_entropy_map": local_entropy_map,"local_variance_map": local_variance_map})
del gradient_x
del gradient_y
del gradient_raw
del local_mean
del local_squared_mean
del local_variance_raw
del local_entropy_raw
del image_uint8
if calculate_residual:
denoised_image = median_filter(img_array, size=3).astype(np.float32)
residual_noise_raw = (img_array - denoised_image).astype(np.float32)
if return_residual_values:
results.update({
"residual_noise_energy": float(np.mean(np.square(residual_noise_raw, dtype=np.float32), dtype=np.float64)),
"residual_noise_std": float(np.std(residual_noise_raw, dtype=np.float64)),
"residual_noise_mean_absolute": float(np.mean(np.abs(residual_noise_raw), dtype=np.float64))})
if return_visual_maps:
residual_absolute = np.abs(residual_noise_raw).astype(np.float32)
residual_minimum = residual_absolute.min()
residual_maximum = residual_absolute.max()
residual_noise_display = np.sqrt((residual_absolute - residual_minimum) / (residual_maximum - residual_minimum + 1e-12)).astype(np.float32)
results.update({
"residual_noise_raw": residual_noise_raw,
"residual_noise": residual_noise_display})
del residual_absolute
del denoised_image
if not return_visual_maps:
del residual_noise_raw
return results