Metadata-Version: 2.4
Name: granatpy
Version: 0.1.3
Summary: Gradient Naturalization for image quality assessment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: joblib
Requires-Dist: scikit-image
Requires-Dist: imageio
Requires-Dist: torch-fidelity
Requires-Dist: torchmetrics[image]>=0.10.0
Dynamic: license-file

# **GraNatPy** - Gradient Naturalization for Image Enhancement and Evaluation

This repository is a collection of metrics to evaluate procedurally generated image datasets.

## Gradient Naturalization

Notabily, we include a Python implementation of the [paper](https://ieeexplore.ieee.org/abstract/document/7347339):
> Y. Gong and I. F. Sbalzarini. A natural-scene gradient distribution prior and its application in light-microscopy image processing. IEEE Journal of
  Selected Topics in Signal Processing, 10(1):99–114, 2016. 

The original code can be found [here](https://github.com/mosaic-group/MosaicSuite/blob/develop/src/main/java/mosaic/plugins/Naturalization.java).

In short, Naturalness is a gradient-based metric that can be computed for an arbitrary image; Naturalization is the method that can enhance images based on this metric.

The Naturalness metric reflects the similarity in the gradient distribution of a sample image to a gradient distribution learned from large image datasets. The closer the Naturalness is to 1, the closer the image is to what we perceive as natural. This is useful for evaluating the perceived quality of synthetically created images.

From their abstract:

> [...] We argue here that the gradient distribution of natural-scene images may provide a versatile and well-founded prior for light-microscopy images that does not impose assumptions about the geometry of the ground-truth signal, but only about its gradient spectrum. We provide motivation for this choice from different points of view, and we illustrate the resulting regularizer for use on light-microscopy images. We provide a simple parametric model for the resulting prior, leading to efficiently solvable variational problems. We demonstrate the use of these models and solvers in a variety of common image-processing tasks, including contrast enhancement, noise-level estimation, denoising, blind deconvolution, and dehazing. [...]

The **GraNatPy** package contains the following classes and functions:
- `GraNat`: convenience class wrapping the full pipeline: loading, naturalization, visualization and saving
- `naturalize_rgb_image`: core function to naturalize an RGB or grayscale image
- `naturalize_single_channel`: core function to naturalize a single image channel
- `compute_all_metrics`: compute and print the dNf (delta Naturalness factor), MSE, PSNR, SSIM and NRMSE between two images
- `compare_images`: compare a reference image against a set of similar (e.g., synthetic) images and print a summary
- `overlay_naturalness_heatmap`: visualize per-region naturalness as a heatmap overlay on the original image

## Installation

The simplest way is to install the package via pip:

```bash
pip install granatpy
```

Alternatively, clone the repository and install in editable mode:
```bash
git clone https://github.com/casus/GraNatPy
cd granatpy
pip install -e .
```

## Quick Start
```python
from granatpy import GraNat

# Load, naturalize and save
GraNat.load_image("photo.tif").naturalize(show=True).save("output.png")

# Visualize naturalness heatmap
from granatpy import overlay_naturalness_heatmap
import imageio.v3 as imageio
import numpy as np

img = imageio.imread("photo.tif")
fig, ax, heatmap = overlay_naturalness_heatmap(img, grid_rows=20, grid_cols=30)

# Compare images
from granatpy import compare_images

images = {
    "photo_low.tif",
    "photo_high.tif",
}
real = "photo_real.tif"
results = compare_images(real, images)
```

You can also find an example notebook in `example/example.ipynb`

## Metrics

We include several metrics for measuring various dataset properties and to compare real and synthetic image pairs; they are saved in `metrics.py`. 

`from granatpy import compare_images` to compare a real and synthetic image, passed as Numpy arrays. This returns PSNR, MSE, SSIM, NRMSE, Naturalness factors for both images, and dNf as the absolute difference between the two.

You can calculate the Shannon entropies of images or datasets with `image_entropy` and `dataset_entropy`, respectively.

### LPIPS -- Comparing image pairs

To compare the perceptual similarity of image pairs, we provide two options:

#### 1. Torchmetrics Implementation (Recommended)
This uses the standard `torchmetrics` library, which is fully compatible with PyPI package installations and modern PyTorch.
```py
from granatpy.metrics import compute_lpips_torch

compute_lpips_torch("./real.tif", "./synthetic.tif")
```

#### 2. Original richzhang/PerceptualSimilarity Implementation (Paper Version)
If you require the exact implementation used in our paper (based on `richzhang/PerceptualSimilarity`), you can use:
```py
from granatpy.metrics import compute_lpips

compute_lpips("./real.tif", "./synthetic.tif")
```
*Note: The first call to `compute_lpips` will automatically attempt to install the specific version of `lpips` from the official GitHub repository (`richzhang/PerceptualSimilarity@082bb24`) using pip.*

For more usage information, refer to: [github.com/richzhang/PerceptualSimilarity](https://github.com/richzhang/PerceptualSimilarity)

### FID -- Comparing datasets

The Fréchet Increption Distance (FID) is useful to assess the quality of generated datasets by calculating the distance between two latent feature distributions; typically a synthetic and a real dataset. To calculate the FID, use the `torch-fidelity` package included with our dependencies and call it via the command-line as follows:

```
fidelity --gpu 0 --fid --input1 path/to/synthetic/data/folder --input2 path/to/real/data/folder --samples-find-deep --samples-find-ext tif --kid-subset-size 100 --rng_seed 420
```
`--samples-find-ext`: allows you to query for specific data types, we use TIF files. \
`--rng_seed`: allows you to create reproducible results.


For more usage information, see: [github.com/toshas/torch-fidelity](https://github.com/toshas/torch-fidelity).

## License

This project is licensed under the GPL-3.0 License. See `LICENSE` for details.

For attribution of example images, see `ATTRIBUTION.md`.


