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

This is 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`

## License

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

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


