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

Python wrapper for CUDA-accelerated 3D deconvolution.

class pycudadecon.RLContext(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]

Bases: object

Context manager to setup the GPU for RL decon.

Takes care of handing the OTF to the GPU, preparing a cuFFT plan, 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', *, dzpsf=0.1, dxpsf=0.1, wavelength=520, na=1.25, nimm=1.3, otf_bgrd=None, krmax=0, fixorigin=10, cleanup_otf=False, max_otf_size=60000, dzdata=0.5, dxdata=0.1, deskew=0, rotate=0, width=0, skewed_decon=False, background=80, n_iters=10, shift=0, save_deskewed=False, napodize=15, nz_blend=0, pad_val=0.0, dup_rev_z=False)[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.

Note that all other kwargs are passed to either make_otf(), rl_init(), or rl_decon().

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

  • dzpsf (float, optional) – Z-step size in microns, by default 0.1

  • dxpsf (float, optional) – XY-Pixel size in microns, by default 0.1

  • wavelength (int, optional) – Emission wavelength in nm, by default 520

  • na (float, optional) – Numerical Aperture, by default 1.25

  • nimm (float, optional) – Refractive indez of immersion medium, by default 1.3

  • otf_bgrd (int, optional) – Background to subtract. “None” = autodetect., by default None

  • krmax (int, optional) – pixels outside this limit will be zeroed (overwriting estimated value from NA and NIMM), by default 0

  • fixorigin (int, optional) – for all kz, extrapolate using pixels kr=1 to this pixel to get value for kr=0, by default 10

  • cleanup_otf (bool, optional) – clean-up outside OTF support, by default False

  • max_otf_size (int, optional) – make sure OTF is smaller than this many bytes. Deconvolution may fail if the OTF is larger than 60KB (default: 60000), by default 60000

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

  • dxdata (float, optional) – XY pixel size of data, 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. Same as the “-dcbds” command line option. If deskewing, do it after decon; require sample-scan PSF and non-Rotational Averaged 3D OTF

  • 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

  • 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

Returns:

The deconvolved image(s). Will be a list if images was a sequence of length >=2.

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. :rtype: None

  • Resets any bleach corrections

  • Removes OTF from GPU buffer

  • Destroys cuFFT plan

  • Releases GPU buffers

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. Same as the “-dcbds” command line option. If deskewing, do it after decon; require sample-scan PSF and non-Rotational Averaged 3D OTF

Return type:

None

Examples

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