Deconvolution#

The primary function for performing deconvolution is decon().

This convenience function is capable of receiving a variety of input types (filenames, directory names, numpy arrays, or a list of any of those) and will handle setting up and breaking down the FFT plan on the GPU for all files being deconvolved. Keywords arguments will be passed internally to the RLContext context manager or the make_otf() rl_decon() functions.

The setup and breakdown for the GPU-deconvolution can also be performed manually:

  1. call rl_init() with the shape of the raw data and path to OTF file.

  2. perform deconvolution(s) with rl_decon().

  3. cleanup with rl_cleanup()

As a convenience, the RLContext context manager will perform the setup and breakdown automatically:

data = tiffile.imread('some_file.tif') otf = 'path_to_otf.tif' with
RLContext(data.shape, otf) as ctx:
    result = rl_decon(data, output_shape=ctx.out_shape)

API#

class pycudadecon.RLContext(rawdata_shape, otfpath, dzdata=0.5, dxdata=0.1, dzpsf=0.1, dxpsf=0.1, deskew=0, rotate=0, width=0)[source]#

Bases: object

Context manager to setup the GPU for RL decon.

Takes care of handing the OTF to the GPU, preparing a cuFFT plane, and cleaning up after decon. Internally, this calls rl_init(), stores the shape of the expected output volume after any deskew/decon, then calls rl_cleanup() when exiting the context.

For parameters, see rl_init().

Examples

>>> with RLContext(data.shape, otfpath, dz) as ctx:
...     result = rl_decon(data, ctx.out_shape)
pycudadecon.decon(images, psf, fpattern='*.tif', **kwargs)[source]#

Deconvolve an image or images with a PSF or OTF file.

If images is a directory, use the fpattern argument to select files by filename pattern.

Parameters
  • images (str, np.ndarray, or sequence of either) – The array, filepath, directory, or list/tuple thereof to deconvolve

  • psf (str or np.ndarray) – a filepath of a PSF or OTF file, or a 3D numpy PSF array. Function will auto-detect whether the file is a 3D PSF or a filepath representing a 2D complex OTF.

  • fpattern (str, optional) – Filepattern to use when a directory is provided in the images argument, by default *.tif

  • kwargs (**) – All other kwargs must be valid for either rl_init() or rl_decon().

Returns

The deconvolved image(s)

Return type

np.ndarray or list of array

Raises
  • ValueError – If save_deskewed is True and deskew is unset or 0

  • IOError – If a directory is provided as input and fpattern yields no files

  • NotImplementedError – If psf is provided as a complex, 2D numpy array (OTFs can only be provided as filenames created with pycudadecon.make_otf())

Examples

deconvolve a 3D TIF volume with a 3D PSF volume (e.g. a single bead stack)

>>> result = decon('/path/to/image.tif', '/path/to/psf.tif')

deconvolve all TIF files in a specific directory that match a certain filename pattern, (in this example, all TIFs with the string ‘560nm’ in their name)

>>> result = decon(
...     '/directory/with/images', '/path/to/psf.tif', fpattern='*560nm*.tif'
... )

deconvolve a list of images, provided either as np.ndarrays, filepaths, or directories

>>> imarray = tifffile.imread('some_other_image.tif')
>>> inputs = ['/directory/with/images', '/path/to/image.tif', imarray]
>>> result = decon(inputs, '/path/to/psf.tif', fpattern='*560nm*.tif')
pycudadecon.rl_cleanup()[source]#

Release GPU buffer and cleanup after deconvolution.

Call this before program quits to release global GPUBuffer d_interpOTF.

  • Resets any bleach corrections

  • Removes OTF from GPU buffer

  • Destroys cuFFT plan

  • Releases GPU buffers

Return type

None

pycudadecon.rl_decon(im, background=80, n_iters=10, shift=0, save_deskewed=False, output_shape=None, napodize=15, nz_blend=0, pad_val=0.0, dup_rev_z=False, skewed_decon=False)[source]#

Perform Richardson Lucy Deconvolution.

Performs actual deconvolution. GPU must first be initialized with pycudadecon.rl_init()

Parameters
  • im (np.ndarray) – 3D image volume to deconvolve

  • background (int or 'auto') – User-supplied background to subtract. If ‘auto’, the median value of the last Z plane will be used as background. by default 80

  • n_iters (int, optional) – Number of iterations, by default 10

  • shift (int, optional) – If deskewed, the output image’s extra shift in X (positive->left), by default 0

  • save_deskewed (bool, optional) – Save deskewed raw data as well as deconvolution result, by default False

  • output_shape (tuple of int, optional) – Specify the output shape after deskewing. Usually this is unnecessary and can be autodetected. Mostly intended for use within a pycudadecon.RLContext context, by default None

  • napodize (int, optional) – Number of pixels to soften edge with, by default 15

  • nz_blend (int, optional) – Number of top and bottom sections to blend in to reduce axial ringing, by default 0

  • pad_val (float, optional) – Value with which to pad image when deskewing, by default 0.0

  • dup_rev_z (bool, optional) – Duplicate reversed stack prior to decon to reduce axial ringing, by default False

  • skewed_decon (bool, optional) – If True, perform deconvolution in skewed space, by default False.

Returns

The deconvolved result. If save_deskewed is True, returns (decon_result, deskew_result)

Return type

np.ndarray or 2-tuple of np.ndarray

Raises

ValueError – If im.ndim is not 3, or output_shape is provided but not length 3

pycudadecon.rl_init(rawdata_shape, otfpath, dzdata=0.5, dxdata=0.1, dzpsf=0.1, dxpsf=0.1, deskew=0, rotate=0, width=0, skewed_decon=False)[source]#

Initialize GPU for deconvolution.

Prepares cuFFT plan for deconvolution with a given data shape and OTF. Must be used prior to pycudadecon.rl_decon()

Parameters
  • rawdata_shape (Tuple[int, int, int]) – 3-tuple of data shape

  • otfpath (str) – Path to OTF TIF

  • dzdata (float, optional) – Z-step size of data, by default 0.5

  • dxdata (float, optional) – XY pixel size of data, by default 0.1

  • dzpsf (float, optional) – Z-step size of the OTF, by default 0.1

  • dxpsf (float, optional) – XY pixel size of the OTF, by default 0.1

  • deskew (float, optional) – Deskew angle. If not 0.0 then deskewing will be performed before deconvolution, by default 0

  • rotate (float, optional) – Rotation angle; if not 0.0 then rotation will be performed around Y axis after deconvolution, by default 0

  • width (int, optional) – If deskewed, the output image’s width, by default 0 (do not crop)

  • skewed_decon (bool, optional) – If True, perform deconvolution in skewed space, by default False.

Examples

>>> rl_init(im.shape, otfpath)
>>> decon_result = rl_decon(im)
>>> rl_cleanup()
Return type

None