novas bibliotecas

This commit is contained in:
kl3z00
2026-10-27 09:14:16 +00:00
parent 8b91a01e60
commit 06b8812a2b
3 changed files with 248 additions and 129 deletions
+186 -126
View File
@@ -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
{
\&#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
}
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(
\&#x20; folder\\\_path="dataset",
\&#x20; 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.
+15 -2
View File
@@ -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",
]
+47 -1
View File
@@ -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
return df