diff --git a/README.md b/README.md index fcfe51a..342fabd 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ The project is being developed to support research into AI-generated image detec Clone the repository and install it in editable mode: ```bash -git clone +git clone https://gittea.kl3z00.com/kl3z/spectralforensics cd spectralforensics python -m pip install -e . ``` @@ -81,11 +81,7 @@ For a single image, `extract_features` returns a dictionary containing the file ```python from spectralforensics import extract_features -data = extract_features( - "images/", - output_csv="spectral_features.csv", - output="quantitative", -) +data = extract_features("images/",output_csv="spectral_features.csv",output="quantitative",) print(data.head()) ``` @@ -124,14 +120,101 @@ Use the `output` argument to control which results are calculated and returned: Example: ```python -features = extract_features( - "images/sample.jpg", - image_size=(255, 255), - high_freq_threshold=0.65, - output="spectral", -) +features = extract_features("images/sample.jpg",image_size=(255, 255),high_freq_threshold=0.65, output="spectral",) ``` +# Extracted Features and Metadata + +The SpectralForensics library extracts a set of quantitative features and interpretable feature maps designed to characterize images in the frequency and spatial domains, including residual noise analysis. + +## 1. Metadata + +| Variable | Description | +|----------|-------------| +| **`filename`** | Name of the processed image file. | +| **`target`** | Image class label (`0 = Real`, `1 = Synthetic`). | + +--- + +## 2. Spectral Features + +These features characterize the frequency-domain properties of an image using Fourier-based analysis. + +| Variable | Description | +|----------|-------------| +| **`spectral_entropy`** | Measures the complexity of the energy distribution in the frequency domain. Higher values indicate a more dispersed spectral energy distribution. | +| **`anisotropy`** | Quantifies the difference between horizontal and vertical spectral energy, enabling the identification of directional frequency patterns. | +| **`dominant_frequency`** | Measures the distance between the highest-energy frequency component and the center of the Fourier spectrum, representing the dominant spatial frequency of the image. | +| **`energy_density`** | Average spectral energy per Fourier transform coefficient. | +| **`high_frequency_ratio`** | Proportion of spectral energy concentrated in high-frequency components relative to the total spectral energy. | + +--- + +## 3. Spatial Features + +These features describe image intensity, local texture, and structural variations in the spatial domain. + +| Variable | Description | +|----------|-------------| +| **`mean_brightness`** | Average pixel intensity of the grayscale image. | +| **`mean_darkness`** | Average value of the darkness map, indicating the prevalence of dark regions within the image. | +| **`mean_gradient`** | Average gradient magnitude, representing the overall presence of edges and intensity transitions. | +| **`mean_local_entropy`** | Average local entropy, reflecting the complexity and texture variability of the image. | +| **`mean_local_variance`** | Average local intensity variance, characterizing local texture variability. | + +--- + +## 4. Residual Noise Features + +These features quantify the statistical properties of residual noise obtained through image filtering. + +| Variable | Description | +|----------|-------------| +| **`residual_noise_energy`** | Mean energy of the residual noise signal. | +| **`residual_noise_std`** | Standard deviation of the residual noise signal. | +| **`residual_noise_mean_absolute`** | Mean absolute value of the residual noise signal. | + +--- + +## 5. Explainable Feature Maps + +In addition to quantitative features, the library generates interpretable maps that enable visual inspection of spatial structures, texture characteristics, frequency distributions, and residual noise patterns. + +| Variable | Description | +|----------|-------------| +| **`brightness_map`** | Normalized luminance intensity map (`0 = Black`, `1 = White`). | +| **`darkness_map`** | Inverted luminance intensity map (`0 = White`, `1 = Black`). | +| **`gradient_map`** | Gradient magnitude map highlighting edges and intensity transitions. | +| **`local_entropy_map`** | Local entropy map highlighting regions with increased texture complexity and information variability. | +| **`local_variance_map`** | Local variance map highlighting regions with greater local intensity variability. | +| **`residual_noise_raw`** | Raw residual noise obtained by subtracting the filtered image from the original image. Preserves the original residual signal and is used for quantitative analysis. | +| **`residual_noise_display`** | Visual representation of residual noise after normalization and contrast enhancement. Intended exclusively for qualitative inspection. | +| **`fft_spectrum`** | Normalized representation of the Fourier spectrum, illustrating the spatial frequency distribution of the image. | + +--- + +## 6. Feature Summary + +The following table summarizes the metadata, quantitative features, and explainable maps provided by the library. + +| Category | Variables | +|----------|-----------| +| **Metadata** | `filename`, `target` | +| **Spectral Features** | `spectral_entropy`, `anisotropy`, `dominant_frequency`, `energy_density`, `high_frequency_ratio` | +| **Spatial Features** | `mean_brightness`, `mean_darkness`, `mean_gradient`, `mean_local_entropy`, `mean_local_variance` | +| **Residual Noise Features** | `residual_noise_energy`, `residual_noise_std`, `residual_noise_mean_absolute` | +| **Explainable Feature Maps** | `brightness_map`, `darkness_map`, `gradient_map`, `local_entropy_map`, `local_variance_map`, `residual_noise_raw`, `residual_noise_display`, `fft_spectrum` | + +### Summary of Extracted Information + +The library provides: + +- **13 quantitative features**, including spectral, spatial, and residual noise descriptors. +- **8 explainable feature maps** for visual inspection and forensic interpretation. +- **2 metadata fields** for image identification and class labeling. + +These outputs support quantitative image characterization, statistical analysis, machine learning workflows, and forensic investigations involving real and synthetically generated images. + 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 @@ -139,52 +222,82 @@ If a filename contains `gen`, the generated-image target is set to `"0"`. If it 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], -} +from spectralforensics import line_plot, box_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") +box_plot(data, x="spectral_entropy", y="anisotropy") ``` +![SpectralForensics line_plot](img/lines2.jpeg) +![SpectralForensics box_plot](img/boxplot.jpeg) Available plotting functions: ```python -from spectralforensics import ( - bar_plot, - box_plot, - correlation_plot, - line_plot, - scatter_plot, -) +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_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", -) +correlation_plot(correlation_data,correlation_columns=["spectral_entropy", "anisotropy", "target", method="pearson", target="target", kind="barh",) ``` +![SpectralForensics box_plot](img/correlation.jpeg) + Set `show=False` to generate and retrieve the Matplotlib figure, axes, and correlation tables without opening the interactive window. +## Interactive Chart Controls and Navigation + +The interactive chart provides a set of controls that allow users to customize data visualization, explore relationships between variables, and interact with the graphical representation. + +### 1. Axis Configuration and Variable Selection + +At the top of the chart, two dropdown menus allow users to select the variables displayed on the **X-axis** and **Y-axis**. + +- **X-axis:** Supports both categorical (qualitative) and numerical (quantitative) variables, enabling different types of data exploration and comparison. +- **Y-axis:** Accepts only numerical (quantitative) variables, ensuring that the selected data can be represented on a continuous numerical scale. + +When a **categorical variable** is selected for the X-axis, an additional dropdown menu becomes available, allowing users to select specific categories associated with that variable. + +Two additional buttons are provided: + +- **Save Image:** Exports the current chart as an image. +- **Reset View:** Restores the chart to its initial position and visualization settings. + +### 2. Interactive Navigation Toolbar + +An interactive toolbar is located in the **bottom-left corner of the chart**, providing several tools for navigating, adjusting, and exporting the visualization. + +The toolbar includes the following controls, described **from right to left**: + +| Control | Function | +|---------|----------| +| **Save (Floppy Disk Icon)** | Saves a snapshot of the current chart, allowing users to export the visualization as an image file. | +| **Configure Subplots** | Allows users to adjust the chart layout, including subplot dimensions, spacing, and positioning. | +| **Zoom (Magnifying Glass Icon)** | Enables users to zoom into a selected region of the chart for more detailed inspection. | +| **Pan (Multidirectional Arrows Icon)** | Allows users to move or reposition the chart interactively while maintaining the current zoom level. | +| **Forward (Right Arrow Icon)** | Navigates to the next view in the chart's navigation history. | +| **Back (Left Arrow Icon)** | Returns to the previous view in the chart's navigation history. | +| **Home (House Icon)** | Restores the chart to its original view, resetting the zoom level and axis positioning. | + + +![SpectralForensics Top bottons](img/lines.jpeg) + +![SpectralForensics Bottom bottons](img/menu.jpeg) + +### 3. Interactive Data Exploration + +Together, these controls provide a flexible environment for exploring and interpreting the extracted image features. + +Users can dynamically select variables, filter categorical data, examine specific regions through zooming and panning, navigate between previous views, and export visualizations for further analysis or documentation. + +These capabilities support **exploratory data analysis (EDA)**, facilitate the identification of patterns and relationships between extracted features, and improve the interpretability of quantitative image forensic analysis. + + ## Examples Runnable examples are available in the [`examples`](examples) directory: diff --git a/img/boxplot.jpg b/img/boxplot.jpg new file mode 100644 index 0000000..46d6255 Binary files /dev/null and b/img/boxplot.jpg differ diff --git a/img/correlation.jpg b/img/correlation.jpg new file mode 100644 index 0000000..01fc521 Binary files /dev/null and b/img/correlation.jpg differ diff --git a/img/lines.jpg b/img/lines.jpg new file mode 100644 index 0000000..2a41914 Binary files /dev/null and b/img/lines.jpg differ diff --git a/img/lines2.jpg b/img/lines2.jpg new file mode 100644 index 0000000..04396c2 Binary files /dev/null and b/img/lines2.jpg differ diff --git a/img/menu.jpg b/img/menu.jpg new file mode 100644 index 0000000..1ad9d6c Binary files /dev/null and b/img/menu.jpg differ