elgw / deconwolf

Deconvolution of widefield microscopy images and generation of point spread functions
GNU General Public License v3.0
42 stars 1 forks source link
born-wolf-model deconvolution point-spread-function richardson-lucy scaled-heavy-ball vkfft widefield-microscopy

deconwolf v0.4.3

deconwolf[^9] is a software for 3-D deconvolution of fluorescent wide-field images:

Deconwolf does not:

Except for this README.me there is also a short USAGE.md, a CHANGELOG.md and a TODO.md.

After building and installing you will find two binaries:

At the moment we don't provide pre-built packages. You will have to build deconwolf from the source code, instructions follows below.

Method

The deconvolution algorithm is based on the Richardson-Lucy (RL) method [^2][^3]. The scaled heavy ball (SHB) [^4] is used for acceleration, i.e. to do more work per iteration. Compared to the "Biggs" acceleration, it use less memory, it also has a proven convergence without any modifications to the algorithm.

The default boundary handling method is based on [^1] , although extended to 3D. In our experiments it cause the least artifacts close to the image borders, especially important in the axial direction. To disable boundary handling, i.e. use periodic deconvolution, the option --periodic can be used.

The PSF calculations in dw_bw implements the "Born and Wolf" model [^5] which is also decribed well in [^6]. It is possible to speed up the calculations using the method from [^7] using the --li argument. At some point (after some more testing) it might become the default method. An important difference to the PSFGenerator is that each pixel in the PSF is integrated full, rather than just using one sample at the pixel centre. This modification gives measureable improvements, especially when the pixel size to resolution limit is low. dw psf also contains a few other PSF models which eventually will be documented as well.

For GPU calculations dw use VkFFT [^8] via OpenCL. Until version 0.3.6 libclfft2 was used for this purpose. Since OpenCL is vendor neutral, this option should work for all major GPU brands. On the CPU side FFTW is used, although it can of course be swapped with API compatible alternatives like MKL.

Build and install

Deconwolf runs on 64-bit machines with, both aarch64 and x86_64, and require no special hardware. For some platforms there are pre-compiled binaries available, see releases.

To compile and install deconwolf should take less than a minute on a Linux machine but might be more cumbersome on MacOS and Windows. For platform specific build instructions, see INSTALL.md. We hope to provide pre-compiled binaries in the future.

Dependencies

Deconwolf uses:

If these libraries are available for your platform, chances are that deconwolf can be built as well.

To enable GPU acceleration, deconwolf also requires a GPU and OpenCL drivers installed.

Performance hints

The performance depends on the system and the image size. Except for some initialization (read images, padding, cropping ... ) and writing the output, the time is linear with the number of iterations.

Here is a table with performance figures for some real images. Run on a system with: a 4-core Intel i7-6700K CPU, 64 GB RAM, NVIDIA GeForce RTX 3090, using the --gpu flag and 50 iterations (--iter 50).

software image size job size time (s) sys-mem (Mb)
dw 1.3.7 2048x2048x35 2228x2228x103 37 28,748
dw 1.3.7 1024x1024x35 1204x1204x103 11 9,686
dw 1.3.7 512x512x35 692x692x103 4 7,564

Running only on the CPU the throughput drops drastically on this machine, having only 4 cores:

software image size job size time (s) sys-mem (Mb)
dw 1.3.7 2048x2048x35 2228x2228x103 1,079 10,802
dw 1.3.7 1024x1024x35 1204x1204x103 222 3,300
dw 1.3.7 512x512x35 692x692x103 78 1,238

Yes, deconvolution is time consuming without a GPU :(

Below there will be some hints on the performance relative to other software. For that purpose synthetic data will be used where periodic boundary conditions (--periodic) can be used. dw should not try to crop the PSF (which is usually done automatically to save some memory/gain some speed) in this case, hence the flag --xyfactor 0 is added as well.

Benchmarking is performed on the microtubules image using the accompanying PSF. Please note that it does not simulate "real" wide field data very well since it is created by periodic convolution.

System: Ubuntu 22.04.4 LTS, AMD Ryzen 7 3700X 8-Core Processor, 64 GB RAM, 12 GB RX 6700 XT GPU. Iterations: 115.

software time (s) self-mem (Mb) sys-mem (Mb)
DeconvolutionLab2 1,025 1,582 48,511
DeconvolutionLab2 + FFTW2 862 1,353 47,387
MATLAB/deconvlucy 104 5,270
dw 1.3.7 --threads 1 52 344
dw 1.3.7 --threads 2 32 419
dw 1.3.7 --threads 4 21 566
dw 1.3.7 --threads 8 18 1,124
dw 1.3.7 --gpu 3 5,085

Notes:

Installation

These instructions should work under Linux, BSD, Windows (via WSL), and MacOS.

  1. Get the dependencies. The required libraries should be found on most platforms, however, the installation process differs slightly. See INSTALL.md for per-platform advice.

  2. Compile and install

mkdir builddir
cd builddir
cmake ..
cmake --build .
sudo make install

Once again, see INSTALL.md for more options.

Minimal usage example

To generate a parametric PSF and deconvolve an image, all you need is something like this:

# generate PSF.tif
dw_bw --resxy 130 \
--resz 250 \
--NA 1.46 \
--ni 1.518 \
--lambda 460 PSF.tiff
# Deconvolve image.tiff -> dw_image.tiff
dw --iter 50 image.tiff PSF.tiff

For available options, please see

dw --help
dw_bw --help

To validate that dw does not create random garbage, run it on /demo/dapi_001.tif

cd demo
make
imagej dapi_001.tif dw_dapi_001.tif

The run time on an AMD 3700x was 8s. To use GPU accelerated deconvolution, test

dw --iter 20 dapi_001.tif PSF_dapi.tif --gpu --prefix dwgpu

The results should be visually identical.

For more documentation see the short usage guide, and the manual pages for both binaries, man dw man dw_bw.

Bugs

Most likely there are bugs and they can only be fixed when they are known. Please open a new ticket if you have any issues with the program.

Alternatives

This is a non-complete list of alternative deconvolution software:

Deconvolution

Free and open source:

Commercial:

Point spread functions

Others

References

[^1]: M. Bertero and P. Boccacci, A simple method for the reduction of boundary effects in the Richardson-Lucy approach to image deconvolution, A&A 437, 369-374 (2005). doi

[^2]: Richardson, William Hadley (1972). "Bayesian-Based Iterative Method of Image Restoration". JOSA. 62 (1): 55–59. doi

[^3]: Lucy, L. B. (1974). "An iterative technique for the rectification of observed distributions". Astronomical Journal. 79 (6): 745–754. doi

[^4]: Wang H, et al. Scaled Heavy-Ball Acceleration of the Richardson-Lucy Algorithm for 3D Microscopy Image Restoration. IEEE Trans Image Process. 2014 doi.

[^5]: Max Born. Principles of optics : electromagnetic theory of propagation, interference, and diffraction of light. Cambridge: Cambridge University Press, 2019. ISBN: 978-1-108-47743-7.

[^6]: F. Aguet. “Super-Resolution Fluorescence Microscopy Based on Physical Models”. EPFL Thesis no. 4418 (2009), 209 p. Swiss Federal Institute of Technology Lausanne (EPFL), May 2009 url

[^7]: Jizhou Li, Feng Xue, and Thierry Blu. “Fast and accurate three-dimensional point spread function computation for fluorescence microscopy”. In: Journal of the Optical Society of America A 34.6 (May 2017), p. 1029. doi

[^8]: D. Tolmachev, "VkFFT-A Performant, Cross-Platform and Open-Source GPU FFT Library," in IEEE Access, vol. 11, pp. 12039-12058, 2023, doi

[^9]: E. Wernersson et al. "Deconwolf enables high-performance deconvolution of widefield fluorescence microscopy images", in Nature Methods, 2024, doi