From 06b8812a2b4583396299c7eeaa2bd6a65554cbb2 Mon Sep 17 00:00:00 2001 From: kl3z00 <2232565@my.ipleiria.pt> Date: Tue, 27 Oct 2026 09:14:16 +0000 Subject: [PATCH] novas bibliotecas --- README.md | 312 ++++++++++++++++++------------ src/spectralforensics/__init__.py | 17 +- src/spectralforensics/dataset.py | 48 ++++- 3 files changed, 248 insertions(+), 129 deletions(-) diff --git a/README.md b/README.md index c971871..fcfe51a 100644 --- a/README.md +++ b/README.md @@ -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 +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. diff --git a/src/spectralforensics/__init__.py b/src/spectralforensics/__init__.py index 19d900d..23a001e 100644 --- a/src/spectralforensics/__init__.py +++ b/src/spectralforensics/__init__.py @@ -1,8 +1,21 @@ -from .dataset import extract_features +from .dataset import ( + extract_features, + rename_generated_images, + rename_real_images, +) from .plotting import line_plot from .plotting_bars import bar_plot from .plotting_scatter import scatter_plot from .plotting_correlation import correlation_plot from .plotting_box import box_plot -__all__ = ["extract_features", "line_plot", "bar_plot", "scatter_plot", "correlation_plot", "box_plot"] +__all__ = [ + "extract_features", + "rename_real_images", + "rename_generated_images", + "line_plot", + "bar_plot", + "scatter_plot", + "correlation_plot", + "box_plot", +] diff --git a/src/spectralforensics/dataset.py b/src/spectralforensics/dataset.py index aee69d9..895247b 100644 --- a/src/spectralforensics/dataset.py +++ b/src/spectralforensics/dataset.py @@ -1,10 +1,56 @@ from pathlib import Path +from uuid import uuid4 + 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 _rename_images(folder_path, prefix): + folder = Path(folder_path) + if not folder.exists(): + raise FileNotFoundError(f"Folder not found: {folder}") + if not folder.is_dir(): + raise NotADirectoryError(f"Expected a folder: {folder}") + + images = sorted( + ( + file + for file in folder.iterdir() + if file.is_file() and file.suffix.lower() in support_ext + ), + key=lambda file: file.name.lower(), + ) + + # Stage every file first so existing names such as real1.jpg cannot collide. + staged_images = [] + for image in images: + temporary_path = folder / f".spectralforensics-{uuid4().hex}{image.suffix}" + image.rename(temporary_path) + staged_images.append((temporary_path, image.suffix.lower())) + + renamed_images = [] + for index, (temporary_path, suffix) in enumerate(staged_images, start=1): + new_path = folder / f"{prefix}{index}{suffix}" + temporary_path.rename(new_path) + renamed_images.append(new_path) + + print(f"{len(renamed_images)} images renamed with the '{prefix}' prefix.") + return renamed_images + + +def rename_real_images(folder_path): + """Rename supported images sequentially as real1, real2, and so on.""" + return _rename_images(folder_path, "real") + + +def rename_generated_images(folder_path): + """Rename supported images sequentially as gen1, gen2, and so on.""" + return _rename_images(folder_path, "gen") + + 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(): @@ -25,4 +71,4 @@ def extract_features(path, output_csv=None, image_size=(255, 255), high_freq_thr df = pd.DataFrame(results) if output_csv: df.to_csv(output_csv, index=False, encoding="utf-8-sig") - return df \ No newline at end of file + return df