Metadata-Version: 2.4
Name: deepblur_napari
Version: 0.1.0
Summary: Blind deblurring and PSF metrology with neural networks, for microscopy
Author-email: Pierre Weiss <pierre.weiss@cnrs.fr>, Florian Sarron <florian.sarron@irit.fr>, Minh-Hai NGUYEN <nguyenhai7120qh@gmail.com>
License-Expression: BSD-3-Clause
Project-URL: Source Code, https://github.com/pierre-weiss/deepblur-napari
Project-URL: Bug Tracker, https://github.com/pierre-weiss/deepblur-napari/issues
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: napari
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: magicgui
Requires-Dist: napari>=0.6
Requires-Dist: qtpy
Requires-Dist: deepinv>=0.5.0
Requires-Dist: torch>=2.7.0
Requires-Dist: torchvision>=0.22.0
Requires-Dist: pyyaml
Requires-Dist: imageio
Requires-Dist: huggingface_hub
Provides-Extra: all
Requires-Dist: napari[all]; extra == "all"
Provides-Extra: testing
Requires-Dist: tox; extra == "testing"
Requires-Dist: pytest; extra == "testing"
Requires-Dist: pytest-cov; extra == "testing"
Requires-Dist: pytest-qt; extra == "testing"
Requires-Dist: napari[all]; extra == "testing"
Dynamic: license-file

# DeepBlur for napari

[![License BSD-3](https://img.shields.io/pypi/l/deepblur-napari.svg?color=green)](https://opensource.org/licenses/BSD-3-Clause)
[![PyPI](https://img.shields.io/pypi/v/deepblur-napari.svg?color=green)](https://pypi.org/project/deepblur-napari)
[![Python Version](https://img.shields.io/pypi/pyversions/deepblur-napari.svg?color=green)](https://python.org)
[![napari hub](https://img.shields.io/endpoint?url=https://api.napari-hub.org/shields/deepblur-napari)](https://napari-hub.org/plugins/deepblur-napari)
[![npe2](https://img.shields.io/badge/plugin-npe2-blue?link=https://napari.org/stable/plugins/index.html)](https://napari.org/stable/plugins/index.html)

DeepBlur estimates the blur of an image with neural networks, without
calibration, and deblurs the image. The blur (point spread function, PSF)
may vary across the field of view, as in most microscopes. From the
estimated PSFs, the plugin also measures the quality of the optics: maps of
the EE50, of the FWHM and of the cut-off frequency.

## Usage

Open the plugin with Plugins > DeepBlur > DeepBlur, or with
`napari -w deepblur_napari`. 

You can drag&drop images, then open the plugin to treat them. 
An alternative is to just launch the plugin and demo images will be displayed. 
You can still add yours by drag&drop.
The **Help** button of the plugin explains the main features.

The main processing pipeline is:
- 1/ add your image
- 2/ estimate the operator
- 3/ estimate the noise
- 4/ deblur

1. **Images**: DeepBlur processes 2D grayscale and RGB images. Each image
   added to napari joins the *Active Image* menu.
2. **Identification model**: the network that estimates the PSF. Use
   `z3_z36` for microscopes and optical blurs, `motion` or `motion_x_z3_z16`
   for motion blurs.
3. **Operator estimation**: *Estimate Operator* builds the blur operator of
   the image from the PSFs estimated on overlapping tiles. It uses a single
   PSF (`constant`), PSFs interpolated through eigen-PSFs (`eigen_psf`), or
   PSFs blended between the tiles (`tiled_psf`).
4. **Noise**: set the Gaussian noise and the bit depth, which sets the
   Poisson noise, or estimate them with *Estimate noise*.
5. **Deblurring**: *Deblur Image* with Tikhonov, TV, DPIR or RAM (usually
   the best).

**Metrology**: *Grid* and clicks on the image display the estimated PSFs.
*EE50 Map*, *FWHM Map* and *Cut-off Map* map the radius containing 50% of
the energy of the PSF, its full width at half maximum, and the cut-off
frequency of the optics.

Computations run in the background. The first use of a network downloads
its weights.

## Installation

DeepBlur needs Python 3.10 to 3.13 (PyTorch has no wheels for Intel Macs).
It runs on CPU and, much faster, on NVIDIA GPUs.

In an environment that has napari, install it from napari's plugin manager
(Plugins > Install/Uninstall Plugins), or with

```sh
pip install deepblur-napari
```

In a new environment, `pip install "deepblur-napari[all]"` also installs
napari with its Qt backend.

On Linux, the PyTorch wheels of PyPI use CUDA. To get a CPU-only PyTorch, or
one for another CUDA version, install it first by following
https://pytorch.org/get-started/locally/, then install the plugin.

### From the sources

[uv] creates the environment `.venv` with the versions locked in `uv.lock`:

```sh
git clone https://github.com/pierre-weiss/deepblur-napari.git
cd deepblur-napari
uv sync --extra all      # add --extra testing for the test tools
uv run napari -w deepblur_napari
```

`uv run python debug.py` opens the same window, e.g. to debug the plugin in
an editor. With pip, run `pip install -e ".[all]"` in a new environment, or
`pip install -e .` in an environment that has napari.

### Weights

The networks download their weights on first use from the MAMBO server, or from the Hugging Face hub
(`mhnguyen712/deepblur`) if the server is unreachable. They are cached in
`~/.cache/deepblur/weights`. You can change the server and the cache folder
with the environment variables `DEEPBLUR_WEIGHTS_URL` and `DEEPBLUR_CACHE`.

## Contributing

Contributions are very welcome. Run the tests with `uv run pytest` (after
`uv sync --extra all --extra testing`) or with [tox], and please ensure the
coverage at least stays the same before you submit a pull request. The
tests download the weights of the networks the first time.

To release, push a tag: `git tag v0.1.0 && git push origin v0.1.0`. The
continuous integration runs the tests, builds the package from a clean
checkout (the version comes from the tag) and publishes it on PyPI.

## License

Distributed under the terms of the [BSD-3] license, deepblur-napari is free
and open source software.

## Acknowledging this work

If you find this plugin useful for your research, please cite : 

Blind spatially varying PSF estimation for fluorescence microscopy
Minh Hai Nguyen, Florian Sarron, Paul Escande, Sylvain Cantaloube, Thomas Mangeat and Pierre Weiss

## The main contributors to this plugin are 

Minh Hai Nguyen, Florian Sarron, Paul Escande, Pierre Weiss

## Issues

If you encounter any problems, please [file an issue] along with a detailed
description.

[BSD-3]: http://opensource.org/licenses/BSD-3-Clause
[file an issue]: https://github.com/pierre-weiss/deepblur-napari/issues
[tox]: https://tox.readthedocs.io/en/latest/
[uv]: https://docs.astral.sh/uv/
