RedLionfish 0.5

Fast Richardson-Lucy deconvolution of 3D volume data using GPU or CPU with napari plugin.

Red lionfish (RL) deconvolution

Richardson-Lucy deconvolution for fishes, scientists and engineers.

Richardson-Lucy is an iterative deconvolution algorithm that is useful for removing point spread function (PSF) or optical transfer function artifacts in experimental images.

The method was originally developed for astronomy, to remove optical effects and simultaneously reduce poisson noise in 2D images.

Lucy, L. B. An iterative technique for the rectification of observed distributions. The Astronomical Journal 79, 745 (1974). DOI: 10.1086/111605

It has a version that runs on CPU and another that runs on GPU using OpenCL through Reikna library. By default it uses the GPU OpenCL version. If data is too big for doing GPU deconvolution, it will do the calculation in blocks, therefore preventing memory issues.

Installation

It is strongly recommended to install this package under a python anaconda or miniconda environment. This is because some calculations use PyOpenCL, and this is best installed in a conda environment.

conda install reikna pyopencl -c conda-forge
pip install redlionfish

In Linux , the package ocl-icd-system is also useful.

conda install reikna pyopencl ocl-icd-system -c conda-forge
pip install redlionfish

Napari plugin

If you follow the installation instructions above, and install the napari in the same conda environment then the plugin should be immediately available in the Menu -> Plugins -> RedLionfish.

Alternatively, you can use the Napari's plugin installation in Menu -> Plugins -> Install/Uninstall Plugins.... If you chose to use this method, GPU acceleration will not be available and it will use the CPU backend.

Anaconda/miniconda installation

At the moment of this writting this package is NOT AVAILABLE available yet in conda-forge. This work is under progress.

Manual installation using the conda package file.

Download the appropriate conda package .bz2 at https://github.com/rosalindfranklininstitute/RedLionfish/releases

In the command line, successively run:

conda install <filename.bz2>
conda update --all -c conda-forge

The second line is needed because you are installing from a local file, conda installer will not install dependencies. Right after this you should run the update command given.

Manual installation (advanced and for developers)

Please note that in order to use OpenCL GPU accelerations, PyopenCL must be installed. The best way to get it working is to install it under a conda environment.

conda install reikna pyopencl

or conda install reikna pyopencl ocl-icd-system -c conda-forge (Linux)

Clone/donload from source https://github.com/rosalindfranklininstitute/RedLionfish/

and run

python setup.py install

Debug

If you want to test and modify the code then you should probably install instead using:

python setup.py develop

Coding

Please feel free to browse /test folder for examples.

In your code, add the import.

import RedLionfishDeconv

in order to use the functions.

The most useful function is perhaps the following.

def doRLDeconvolutionFromNpArrays(data_np , psf_np ,*, niter=10, method='gpu', useBlockAlgorithm=False, callbkTickFunc=None, resAsUint8 = False)

This will do the Richardson-Lucy deconvolution on the data_np (numpy, 3 dimensional data volume) using the provided PSF data volume, for 10 iterations. GPU method is generally faster but it may fail. If it does fail, the program will automatically use the CPU version from scipy.imaging.

Manually building the conda package

For this installation, ensure that the conda-build package is installed

conda install conda-build

In windows, simply execute

conda-create-package.bat

Or, execute the command-line to create the installation package for RedLionfish

conda-build --output-folder ./conda-built-packages -c conda-forge conda-recipe

and the conda package will be created in folder conda-built-packages.

Otherwise, navigate to conda-recipe, and execute on the command-line conda build .

It will take a while to complete.