Linear filtering

Linear filtering module.

Linear filtering consists of applying a linear operator on an input signal, here the intensity or labelled images. The basic linear filter operators are Gaussian filtering, gradiant and Laplacian.

Available linear filtering methods are:

  • smoothing: gaussian smoothing

  • gradient: ||grad(I)||

  • hessian: grad(I).H(I).grad(I)

  • laplacian: ??

  • gradient-hessian: gradient modulus onto zero-crossings of hessian image

  • gradient-laplacian: gradient modulus onto zero-crossings of laplacian image

  • zero-crossings-hessian: ??

  • zero-crossings-laplacian: ??

  • gradient-extrema: ??

timagetk.algorithms.linearfilter.gaussian_filter(image, sigma=1.0, real=True, **kwargs)[source]

Gaussian filter.

Parameters:

  • image (timagetk.SpatialImage or timagetk.MultiChannelImage) – Intensity image to filter.

  • sigma (float or list of float, optional) – The sigma to apply for every axis if a float, for each axis if a list of floats.

  • real (bool, optional) – Define if the sigma to apply is in voxel or real units (default).

  • channel (str) – If a MultiChannelImage is used as input image, the algorithm will be applied only to this channel. Else it will be applied to all channels of the multichannel image.

Returns:

timagetk.SpatialImage – The filtered image.

See also

scipy.ndimage.gaussian_filter

Examples

>>> from timagetk.io.util import shared_data
>>> from timagetk.io import imread
>>> from timagetk.algorithms.linearfilter import gaussian_filter
>>> from timagetk.visu.mplt import grayscale_imshow

>>> # EXAMPLE #1 - Apply linear filtering with default parameters:
>>> img = imread(shared_data('sphere_membrane_0.0.inr.gz', 'sphere'))
>>> # -- Gaussian smoothing, sigma=1.0 in real units
>>> f_img = gaussian_filter(img, sigma=0.5)
>>> # - Display linear filtering effect:
>>> mid_z = img.get_shape('z') // 2
>>> img_titles = ["Original", "Sigma=0.5µm"]
>>> grayscale_imshow([img, f_img], slice_id=mid_z, suptitle="Effect of Gaussian filtering", title=img_titles)
timagetk.algorithms.linearfilter.linearfilter(image, method='smoothing', sigma=1.0, real=True, **kwargs)[source]

Linear filtering algorithms.

Parameters:

  • image (timagetk.SpatialImage or timagetk.MultiChannelImage) – Intensity image(s) to filter.

  • method ({"smoothing", "gradient", "hessian", "laplacian", "zero-crossings-hessian", "zero-crossings-laplacian", "gradient-hessian", "gradient-laplacian", "gradient-extrema"}, optional) – The method to use for linear filtering. Defaults to ‘smoothing’.

  • sigma (float or list(float), optional) – The sigma to apply for every axis if a float, for each axis if a list of floats.

  • real (bool, optional) – Define if the sigma to apply is in voxel or real units (default).

  • channel (str) – If a MultiChannelImage is used as input image, the algorithm will be applied only to this channel. Else it will be applied to all channels of the multichannel image.

  • gaussian_type ({"deriche", "fidrich", "young-1995", "young-2002", "gabor-young-2002", "convolution"}) – Type of implementation to use for the gaussian methods. All except “convolution” are recursive filters. Method “convolution” is a convolution with a truncated gaussian mask.

  • negative (bool) – If True zero-crossings are set on the negative values.

  • positive (bool) – If True zero-crossings are set on the positive values, default when using a zero-crossing method.

  • 2D (bool) – If True, performs 2D filtering of XY slices in a 3D volume.

  • edges (bool) – If True, edge-oriented normalization of first order derivative filters.

  • params (str, optional) – CLI parameter string used by vt.linear_filter method.

Returns:

timagetk.SpatialImage – The filtered image.

Raises:

  • TypeError – If image is not a SpatialImage.

  • ValueError – If the image returned by vt.linear_filter is None.

See also

timagetk.third_party.vt_parser.FILTERING_METHODS, timagetk.third_party.vt_parser.DEF_F_METHOD, timagetk.third_party.vt_parser.GAUSSIAN_IMPLEMENTATION, timagetk.third_party.vt_parser.DEF_GAUSS, timagetk.third_party.vt_parser.linfilter_kwargs, timagetk.third_party.vt_parser.general_kwargs, timagetk.third_party.vt_parser.parallel_kwargs

Notes

Beware of sigma values as they are in real units by default.

Changing to voxel may lead to erroneous result if the image is not isometric. An option is to provide a list of sigma values adapted to the voxel-size.

Examples

>>> from timagetk import SpatialImage
>>> from timagetk import MultiChannelImage
>>> from timagetk.io import imread
>>> from timagetk.io.util import shared_data
>>> from timagetk.algorithms.linearfilter import linearfilter
>>> from timagetk.visu.mplt import grayscale_imshow

>>> # EXAMPLE #1 - Apply linear filtering with default parameters:
>>> img = imread(shared_data('sphere_membrane_0.0.inr.gz', 'sphere'))
>>> # -- Gaussian smoothing, sigma=1.0 in real units
>>> out_img = linearfilter(img, sigma=0.5, param=True)
>>> # - Display linear filtering effect:
>>> mid_z = img.get_shape('z') // 2
>>> img_titles = ["Original", "Gaussian, sigma=0.5µm"]
>>> from timagetk.visu.mplt import grayscale_imshow
>>> grayscale_imshow([img, out_img], slice_id=mid_z, suptitle="Effect of linear filtering", title=img_titles, val_range=[0, 255])

>>> # EXAMPLE #2 - Apply linear filtering with no-default parameters:
>>> # -- Gaussian smoothing, sigma=2.0 in real units
>>> out_img = linearfilter(img, method="smoothing", sigma=2., real=False)
>>> # - Display linear filtering effect:
>>> mid_z = img.get_shape('z') // 2
>>> img_titles = ["Original", "Gaussian, sigma=2voxels"]
>>> grayscale_imshow([img, out_img], slice_id=mid_z, suptitle="Effect of linear filtering", title=img_titles, val_range=[0, 255])

>>> # EXAMPLE #3 - Apply linear filtering on a multichannel image:
 >>> im_url = "https://zenodo.org/record/3737795/files/qDII-CLV3-PIN1-PI-E35-LD-SAM4.czi"
>>> ch_names = ['DII-VENUS-N7', 'pPIN1:PIN1-GFP', 'Propidium Iodide', 'pRPS5a:TagBFP-SV40', 'pCLV3:mCherry-N7']
>>> img = imread(im_url, channel_names=ch_names)
>>> # Apply the algorithm to all channels (with same parameters):
>>> out_img = linearfilter(img, method="smoothing", sigma=2., real=False)
>>> isinstance(out_img, MultiChannelImage)
True
>>> # Apply the algorithm to a single channel and get the resulting SpatialImage:
>>> out_img = linearfilter(img, channel='Propidium Iodide', method="smoothing", sigma=2., real=False)
>>> isinstance(out_img, MultiChannelImage)
False
>>> isinstance(out_img, SpatialImage)
True
timagetk.algorithms.linearfilter.list_linear_methods()[source]

List the available methods to call with linear_filtering.

Returns:

list of str – The list of available methods.