{"name":"RedLionfish","display_name":"RedLionfish","visibility":"public","icon":"","categories":[],"schema_version":"0.2.0","on_activate":null,"on_deactivate":null,"contributions":{"commands":[{"id":"RedLionfish.RedLionfish_widget","title":"RedLionfish_widget","python_name":"RedLionfishDeconv.napari_plugin:RedLionfish_widget","short_title":null,"category":null,"icon":null,"enablement":null}],"readers":null,"writers":null,"widgets":[{"command":"RedLionfish.RedLionfish_widget","display_name":"RedLionfish_widget","autogenerate":false}],"sample_data":null,"themes":null,"menus":{},"submenus":null,"keybindings":null,"configuration":[]},"package_metadata":{"metadata_version":"2.1","name":"RedLionfish","version":"0.10","dynamic":null,"platform":null,"supported_platform":null,"summary":"Fast Richardson-Lucy deconvolution of 3D volume data using GPU or CPU with napari plugin.","description":"![RedLionfish Logo](./redlionfish_logo.svg)\n\n# RedLionfish (RL) deconvolution\n\n*Richardson-Lucy deconvolution for fishes, scientists and engineers.*\n\n\nThis software is for filtering 3D data using the Richardson-Lucy deconvolution algorithm.\n\nRichardson-Lucy is an iterative deconvolution algorithm that is used to remove\npoint spread function (PSF) or optical transfer function (OTF) artifacts from experimental images.\n\nThe method was originally developed for astronomy to remove optical effects and simultaneously reduce poisson noise in 2D images.\n\n[Lucy, L. B. An iterative technique for the rectification of observed distributions. The Astronomical Journal 79, 745 (1974). DOI: 10.1086/111605](https://ui.adsabs.harvard.edu/abs/1974AJ.....79..745L/abstract)\n\nThe method can also be applied to 3D data. Nowadays this filtering technique is also widely used by microscopists.\n\nThe Richardson-Lucy deconvolution algorigthm is iterative. Each iteration involves the calculation of 2 convolutions, one element-wise multiplication and one element-wise division.\n\nWhen dealing with 3D data, the Richardson-Lucy algorithm is quite computional intensive primarly due to the calculation of the convolution, and can take a while to complete depending on the resources available. Convolution is significantly sped up using FFT compared to raw convolution.\n\nThis software was developed with the aim to make the R-L computation faster by exploiting GPU resources, and with the use of FFT convolution.\n\nTo make RedLionfish easily accessible, it is available through PyPi and anaconda (conda-forge channel). A useful plugin for Napari is also available.\n\nPlease note that this software only works with 3D data. For 2D data there are many alternatives such as the DeconvolutionLab2 in Fiji (ImageJ) and sckikit-image.\n\n## Napari plugin\n\nYou can now use the Napari's plugin installation in *Menu -> Plugins -> Install/Uninstall Plugins...*.\nHowever, if you chose to use this method, GPU acceleration may not be available and it will use the CPU backend. Better check.\n\n![](resources\\imag1.jpg)\n\nAlternatively, if you follow the installation instructions below, and install the napari in the same python environment\nthen the plugin should be immediately available in the *Menu -> Plugins -> RedLionfish*.\n\n\n## Installation\n\nPreviously there was a problem in installing using `pip`, because no PyOpenCL wheels for windows were avaiable. It is now avaialble.\n\nThis package can be installed using pip or conda.\n\nNapari plugin installation engine can also be used to install this package.\n\n\n### Install from PyPi\n\n```\npip install redlionfish\n```\n\n\n### Conda install\n\nThis package is available in conda-forge channel.\nIt contains the precompiled libraries and it will install all the requirments for GPU-accelerated RL calculations.\n\n`conda install redlionfish -c conda-forge`\n\nIn Linux , the package `ocl-icd-system` may also be useful.\n\n```\nconda install reikna pyopencl ocl-icd-system -c conda-forge\n```\n\n\n#### Manual installation using the conda package file.\n\nDownload the appropriate conda package .bz2 at [https://github.com/rosalindfranklininstitute/RedLionfish/releases](https://github.com/rosalindfranklininstitute/RedLionfish/releases)\n\nIn the command line, successively run:\n```\nconda install <filename.bz2>\nconda update --all -c conda-forge\n```\nThe 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.\n\n\n### Manual installation (advanced and for developers)\n\nPlease note that in order to use OpenCL GPU accelerations, PyOpenCL must be installed.\nThe best way to get it working is to install it under a conda environment.\n\nThe installation is similar to the previously described for PyPi.\n\n`conda install reikna pyopencl`\n\nor\n\n`conda install reikna pyopencl ocl-icd-system -c conda-forge` (Linux)\n\nClone/download from source [https://github.com/rosalindfranklininstitute/RedLionfish/](https://github.com/rosalindfranklininstitute/RedLionfish/)\n\nand run\n\n`python setup.py install`\n\n\n### Debug installation\nIf you want to test and modify the code then you should probably install in debug mode using:\n\n`python setup.py develop`\n\nor\n\n`pip install -e .`\n\n\n## More information\n\nThe software has algorithms for Richardson-Lucy deconvolution that use either CPU and GPU.\n\nThe CPU version is very similar to the [skimage.restoration.richardson_lucy](https://scikit-image.org/docs/dev/api/skimage.restoration.html#skimage.restoration.richardson_lucy) code, with improvments in speed.\nmajor differences are:\n\n- the convolution steps use FFT only.\n- PSF and PSF-flipped FFTs are precalculated before starting iterations.\n\nThe GPU version, was written in to use Reikna package, which does FFT using OpenCL, via PyOpenCL.\n\nUnfortunately, a major limitation in RAM usage exists with PyOpenCL.\nLarge 3D data volumes with cause out-of-memory error when trying to upload data to the GPU for FFT calculations.\nAs such, to overcome this problem, a block algorithm is used, which splits data into blocks with padded data.\nThe results are then combined together to give the final result.\nThis affects the perfomance of the calculation rather significantly, but with the advantage of being possible to handle large data volumes.\n\nIf Richardson-Lucy deconvolution using the GPU method fails, RedLionfish will fallback to CPU calculation. Check console output for messages.\n\nIf you are using the RedLionfish in your code, note that, by default, `def doRLDeconvolutionFromNpArrays()` method it uses the GPU OpenCL version.\n\n## Testing\n\nUse pytest to test the package. Test files are in `/test` folder\n\nMany examples can be found in `/scripts' folder.\n\nA useful way to test and benchmark the package installation can be run from the proect root using the command:\n\n'python scripts/test_and_benchm.py'\n\nor in windows\n\n'python scripts\\test_and_benchm.py'\n\nThis will print out information about your GPU device (if available) and run some deconvolutions.\nIt initially creates some data programatically, convolutes with a gaussian PSF, and add Poisson noise.\nThen it executes executes the\nRichardson-Lucy deconvolution calculation using CPU and GPU methods, for 10 iterations.\nDuring the calculation it will print some information to the console/terminal, including the time it takes to run the calculation.\n\n\nComputer generated data and an experimental PSF can be found in `scripts\\testdata`\n\n### Testing Redlionfish in napari\n\nHere is an example testing the Redlionfish plugin in napari:\n\n1. load data `scripts/testdata/gendata_psfconv_poiss_large.tif` (can use draga and drop)\n2. load psf data `scripts/testdata/PSF_RFI_8bit.tif`\n3. In the RedLionfish side window ensure that 'gendata_psfconv_poiss_large' is selected in data dropdown widget, and `PSF_RFI_8bit` is selected in psfdata widget.\n4. Choose number of iterations (default=10)\n5. Click 'Go' button and wait until result shows as a new data layer.\n6. Use controls of the left panel to compare before and after RL deconvolution: select 'RL-deconvolution' layer and set colormap to red. Hide PSF_RFI_8bit. Make sure that both 'RL-deconvolution' and 'gendata-psfconv' are visible. Now, hide/unhide RL-deconvolution layer to see before and after deconvolution. Adjust contrast limits of each layer as desired.\n\n\n## GPU vs CPU\n\nYou may notice that choosing GPU does not make RL-calculation much faster compared with CPU, and sometimes is slower.\n\nWhich method runs the R-L deconvolution faster. That depends on the computer configuration/architecture.\n\nGPU calculations will be generally faster than CPU with bigger data volumes.\n\nGPU calculation will be significantly faster if using a dedicated GPU card.\n\nPlease see benchmark values that highlights significant variability in calculation speeds.\n\n\n[benchmark_results.md](benchmark_results.md)\n\n\n## Coding\n\nPlease feel free to browse the `/scripts` folder for examples.\n\nIn order to use the functions, add the follwoing import to your code,\n\n`import RedLionfishDeconv`\n\nThe most useful function is perhaps the following.\n\n`def doRLDeconvolutionFromNpArrays(data_np , psf_np ,*, niter=10, method='gpu', useBlockAlgorithm=False, callbkTickFunc=None, resAsUint8 = False) `\n\nThis 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 that uses the scipy fft package.\n\n\n\n## Manually building the conda package\n\nFor this installation, ensure that the conda-build package is installed\n\n`conda install conda-build`\n\nIn windows, simply execute\n\n`conda-create-package.bat`\n\n\nOr, execute the following command-line to create the installation package.\n\n`conda-build --output-folder ./conda-built-packages -c conda-forge conda-recipe`\n\nand the conda package will be created in folder *conda-built-packages*.\n\nOtherwise, navigate to `conda-recipe`, and execute on the command-line `conda build .`\n\nIt will take a while to complete.\n\n## Contact\n\nReport issues and questions in project's github page, please. Please don't try to send emails as they may be igored or spam-filtered.\n\n","description_content_type":"text/markdown","keywords":null,"home_page":"https://github.com/rosalindfranklininstitute/RedLionfish","download_url":null,"author":"Luis Perdigao","author_email":"luis.perdigao@rfi.ac.uk","maintainer":null,"maintainer_email":null,"license":"Apache License, Version 2.0","classifier":["Development Status :: 4 - Beta ","License :: OSI Approved :: Apache Software License","Natural Language :: English","Programming Language :: Python :: 3.8","Operating System :: Microsoft :: Windows","Operating System :: MacOS","Operating System :: POSIX :: Linux","Topic :: Scientific/Engineering :: Image Processing","Framework :: napari"],"requires_dist":["numpy","scipy","pyopencl","reikna"],"requires_python":null,"requires_external":null,"project_url":null,"provides_extra":null,"provides_dist":null,"obsoletes_dist":null},"npe1_shim":true}