Morphology

Mathematical morphology module.

Morphological operators consists of a set of operators that transform images according to shape, size convexity or connectivity. The basic morphological operators are erosion, dilation, opening and closing.

Available mathematical morphology operators are:

  • dilation

  • erosion

  • closing: dilation then erosion

  • opening: erosion then dilation

  • hat-closing: hat transform (‘closing’ - image), enhances small dark structures

  • hat-opening: inverse hat transform (image - ‘opening’), enhances small bright structures

  • contrast

  • gradient: morphological gradient (‘dilated’ - ‘eroded’)

  • oc_alternate_sequential_filter alternates opening and closing operators with increasing element radius.

  • co_alternate_sequential_filter alternates closing and opening operators with increasing element radius.

  • coc_alternate_sequential_filter alternates closing, opening and closing operators with increasing element radius.

  • oco_alternate_sequential_filter alternates opening, closing and opening operators with increasing element radius.

timagetk.algorithms.morphology.DEF_MAX_RADIUS = 3

Default radius of the structuring elements

timagetk.algorithms.morphology.label_filtering(image, method='dilation', **kwargs)[source]

Mathematical morphology algorithms for labelled images.

Valid method values are:

  • dilation

  • erosion

  • closing: dilation then erosion

  • opening: erosion then dilation

  • hat-closing: hat transform (‘closing’ - image), enhances small dark structures

  • hat-opening: inverse hat transform (image - ‘opening’), enhances small bright structures

  • gradient: morphological gradient (‘dilated’ - ‘eroded’)

  • oc_alternate_sequential_filter alternates opening and closing operators with increasing element radius.

  • co_alternate_sequential_filter alternates closing and opening operators with increasing element radius.

  • coc_alternate_sequential_filter alternates closing, opening and closing operators with increasing element radius.

  • oco_alternate_sequential_filter alternates opening, closing and opening operators with increasing element radius.

Parameters:

  • image (timagetk.LabelledImage) – Apply the morphological operator to this segmented image.

  • method (str in INTENSITY_MORPHOLOGY_METHODS, optional) – The mathematical morphology operator to use, DEF_RE_METHOD by default.

  • radius (int, optional) – Radius of the structuring element. Defaults to 1.

  • iterations (int, optional) – Number of time to apply the morphological operation. Defaults to 1.

  • max_radius (int, optional) – Maximum value reached by radius, starting from 1, when performing ‘sequential filtering’ methods. Defaults to 3.

  • connectivity (int, optional) – Use it to override the default ‘sphere’ parameter for the structuring element. Using sphere=True is equivalent to using connectivity=18.

  • sphere (bool) – If True, the structuring element is the true euclidean sphere.

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

Returns:

LabelledImage – Segmented image after morphological operation.

Raises:

  • TypeError – If image is not a LabelledImage.

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

See also

timagetk.algorithm.morphology.DEF_MAX_RADIUS, timagetk.third_party.vt_parser.INTENSITY_MORPHOLOGY_METHODS, timagetk.third_party.vt_parser.DEF_MORPHO_METHOD, timagetk.third_party.vt_parser.morphology_kwargs, timagetk.third_party.vt_parser.structuring_element_kwargs, timagetk.third_party.vt_parser.general_kwargs, timagetk.third_party.vt_parser.parallel_kwargs

Notes

Using the connectivity parameter override the sphere parameter.

Connectivity is among the 4-, 6-, 8-, 18-, 26-neighborhoods. 4 and 8 are for 2D images, the others for 3D images.

Example

>>> from timagetk.algorithms.morphology import label_filtering, DEF_MORPHO_METHOD
>>> from timagetk.io.util import shared_data
>>> from timagetk.io import imread
>>> from timagetk import LabelledImage
>>> from timagetk.visu.mplt import grayscale_imshow
>>> img = LabelledImage(imread(shared_data('sphere_membrane_0.0_seg.inr.gz', 'sphere')), not_a_label=0)

>>> # EXAMPLE #1 - Apply label filtering with default parameters:
>>> out_img = label_filtering(img)
>>> # - Display label filtering effect:
>>> mid_z = img.get_shape('z') // 2
>>> img_titles = ["Original", f"{DEF_MORPHO_METHOD}"]
>>> grayscale_imshow([img, out_img], slice_id=mid_z, suptitle="Effect of label filtering", title=img_titles, cmap='glasbey')

>>> # EXAMPLE #2 - Apply label filtering with opening-closing alternate sequential filter:
>>> out_img = label_filtering(img, 'oc_alternate_sequential_filter')
>>> # - Display label filtering effect:
>>> mid_z = img.get_shape('z') // 2
>>> img_titles = ["Original", 'Opening-closing alternate sequential filter']
>>> grayscale_imshow([img, out_img], slice_id=mid_z, suptitle="Effect of label filtering", title=img_titles, cmap='glasbey')
timagetk.algorithms.morphology.label_filtering_co_alternate_sequential_filter(image, max_radius=3, **kwargs)[source]

Closing Opening alternate sequential filter on labelled image.

Parameters:

  • image (timagetk.LabelledImage) – Apply the morphological operator to this labelled image.

  • max_radius (int, optional) – Maximum value reached by radius, starting from 1. Defaults to DEF_MAX_RADIUS.

Returns:

LabelledImage – Transformed labelled image and its metadata.

See also

timagetk.algorithm.morphology.DEF_MAX_RADIUS

Example

>>> from timagetk.io.util import shared_dataset
>>> from timagetk.io import imread
>>> from timagetk.visu.mplt import grayscale_imshow
>>> img = imread(shared_dataset('p58', 'segmented', 0)[0], LabelledImage)
>>> from timagetk.algorithms.morphology import label_filtering_co_alternate_sequential_filter
>>> asf = label_filtering_co_alternate_sequential_filter(img, 2)
>>> grayscale_imshow([img, asf], slice_id=img.get_shape('z')//2, axis='z', title=['Original', 'OC asf'], cmap='glasbey')
timagetk.algorithms.morphology.label_filtering_coc_alternate_sequential_filter(image, max_radius=3, **kwargs)[source]

Closing Opening Closing alternate sequential filter on labelled image.

Parameters:

  • image (timagetk.LabelledImage) – Apply the morphological operator to this labelled image.

  • max_radius (int, optional) – Maximum value reached by radius, starting from 1. Defaults to DEF_MAX_RADIUS.

Returns:

LabelledImage – Transformed labelled image and its metadata.

See also

timagetk.algorithm.morphology.DEF_MAX_RADIUS

Example

>>> from timagetk import LabelledImage
>>> from timagetk.io import imread
>>> from timagetk.io.util import shared_dataset
>>> from timagetk.visu.mplt import grayscale_imshow
>>> img = imread(shared_dataset('p58', 'segmented', 0)[0], LabelledImage)
>>> from timagetk.algorithms.morphology import label_filtering_coc_alternate_sequential_filter
>>> asf = label_filtering_coc_alternate_sequential_filter(img, 2)
>>> grayscale_imshow([img, asf], slice_id=img.get_shape('z')//2, axis='z', title=['Original', 'COC asf'], cmap='glasbey')
timagetk.algorithms.morphology.label_filtering_oc_alternate_sequential_filter(image, max_radius=3, **kwargs)[source]

Opening Closing alternate sequential filter on labelled image.

Parameters:

  • image (timagetk.LabelledImage) – Apply the morphological operator to this labelled image.

  • max_radius (int, optional) – Maximum value reached by radius, starting from 1. Defaults to DEF_MAX_RADIUS.

Returns:

LabelledImage – Transformed labelled image and its metadata.

See also

timagetk.algorithm.morphology.DEF_MAX_RADIUS

Example

>>> from timagetk import LabelledImage
>>> from timagetk.io import imread
>>> from timagetk.io.util import shared_dataset
>>> from timagetk.visu.mplt import grayscale_imshow
>>> img = imread(shared_dataset('p58', 'segmented', 0)[0], LabelledImage)
>>> from timagetk.algorithms.morphology import label_filtering_oc_alternate_sequential_filter
>>> asf = label_filtering_oc_alternate_sequential_filter(img, 2)
>>> grayscale_imshow([img, asf], slice_id=img.get_shape('z')//2, axis='z', title=['Original', 'OC asf'], cmap='glasbey')
timagetk.algorithms.morphology.label_filtering_oco_alternate_sequential_filter(image, max_radius=3, **kwargs)[source]

Opening Closing Opening alternate sequential filter on labelled image.

Parameters:

  • image (timagetk.LabelledImage) – Apply the morphological operator to this labelled image.

  • max_radius (int, optional) – Maximum value reached by radius, starting from 1. Defaults to DEF_MAX_RADIUS.

Returns:

LabelledImage – Transformed labelled image and its metadata.

See also

timagetk.algorithm.morphology.DEF_MAX_RADIUS

Example

>>> from timagetk import LabelledImage
>>> from timagetk.io import imread
>>> from timagetk.io.util import shared_dataset
>>> from timagetk.visu.mplt import grayscale_imshow
>>> img = imread(shared_dataset('p58', 'segmented', 0)[0], LabelledImage)
>>> from timagetk.algorithms.morphology import label_filtering_oco_alternate_sequential_filter
>>> asf = label_filtering_oco_alternate_sequential_filter(img, 2)
>>> grayscale_imshow([img, asf], slice_id=img.get_shape('z')//2, axis='z', title=['Original', 'OCO asf'], cmap='glasbey')
timagetk.algorithms.morphology.morphology(image, method='dilation', **kwargs)[source]

Mathematical morphology algorithms for intensity images.

Parameters:

  • image (timagetk.components.spatial_image.SpatialImage or timagetk.components.multi_channel.MultiChannelImage) – Apply the morphological operator to this intensity image.

  • method (str in INTENSITY_MORPHOLOGY_METHODS, optional) – The mathematical morphology operator to use, DEF_RE_METHOD by 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.

  • radius (int, optional) – Radius of the structuring element. Defaults to 1.

  • iterations (int, optional) – Number of time to apply the morphological operation. Defaults to 1.

  • max_radius (int, optional) – Maximum value reached by radius, starting from 1, when performing ‘sequential filtering’ methods. Defaults to DEF_MAX_RADIUS.

  • connectivity (int, optional) – Use it to override the default ‘sphere’ parameter for the structuring element. Using sphere=True is equivalent to using connectivity=18.

  • sphere (bool) – If True, the structuring element is the true Euclidean sphere.

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

Returns:

timagetk.SpatialImage or timagetk.MultiChannelImage – Intensity image after morphological operation.

Raises:

  • TypeError – If image is not a SpatialImage.

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

See also

timagetk.algorithm.morphology.DEF_MAX_RADIUS, timagetk.third_party.vt_parser.INTENSITY_MORPHOLOGY_METHODS, timagetk.third_party.vt_parser.DEF_MORPHO_METHOD, timagetk.third_party.vt_parser.morphology_kwargs, timagetk.third_party.vt_parser.structuring_element_kwargs, timagetk.third_party.vt_parser.general_kwargs, timagetk.third_party.vt_parser.parallel_kwargs

Notes

Using the connectivity parameter override the sphere parameter.

Connectivity is among the 4-, 6-, 8-, 18-, 26-neighborhoods. 4 and 8 are for 2D images, the others for 3D images.

Example

>>> from timagetk.algorithms.morphology import morphology, DEF_MORPHO_METHOD
>>> from timagetk.synthetic_data.wall_image import example_layered_sphere_wall_image
>>> from timagetk.visu.mplt import grayscale_imshow
>>> img = example_layered_sphere_wall_image()

>>> # EXAMPLE #1 - Apply morphology with default parameters:
>>> out_img = morphology(img)
>>> # - Display morphological filtering effect:
>>> mid_z = img.get_shape('z') // 2
>>> img_titles = ["Original", f"{DEF_MORPHO_METHOD}"]
>>> grayscale_imshow([img, out_img], slice_id=mid_z, suptitle="Effect of morphological filtering", title=img_titles, val_range=[0, 255])

>>> # EXAMPLE #2 - Apply morphology with opening-closing alternate sequential filter:
>>> out_img = morphology(img, 'oc_alternate_sequential_filter')
>>> # - Display morphological filtering effect:
>>> mid_z = img.get_shape('z') // 2
>>> img_titles = ["Original", 'Opening-closing alternate sequential filter']
>>> grayscale_imshow([img, out_img], slice_id=mid_z, suptitle="Effect of morphological filtering", title=img_titles, val_range=[0, 255])
timagetk.algorithms.morphology.morphology_co_alternate_sequential_filter(image, max_radius=3, **kwargs)[source]

Closing Opening alternate sequential filter on grayscale image.

Parameters:

  • image (timagetk.SpatialImage) – Apply the morphological operator to this intensity image.

  • max_radius (int, optional) – Maximum value reached by radius, starting from 1. Defaults to DEF_MAX_RADIUS.

Returns:

timagetk.SpatialImage – Transformed intensity image and its metadata.

See also

timagetk.algorithm.morphology.DEF_MAX_RADIUS

Example

>>> from timagetk.io.util import shared_dataset
>>> from timagetk.io import imread
>>> from timagetk.visu.mplt import grayscale_imshow
>>> img = imread(shared_dataset('p58', 'intensity', 0)[0])
>>> from timagetk.algorithms.morphology import morphology_co_alternate_sequential_filter
>>> asf = morphology_co_alternate_sequential_filter(img, 2)
>>> grayscale_imshow([img, asf], slice_id=img.get_shape('z')//2, axis='z', title=['Original', 'CO asf'])
timagetk.algorithms.morphology.morphology_coc_alternate_sequential_filter(image, max_radius=3, **kwargs)[source]

Closing Opening Closing alternate sequential filter on grayscale image.

Parameters:

  • image (timagetk.SpatialImage) – Apply the morphological operator to this intensity image.

  • max_radius (int, optional) – Maximum value reached by radius, starting from 1. Defaults to DEF_MAX_RADIUS.

Returns:

timagetk.SpatialImage – Transformed intensity image and its metadata.

See also

timagetk.algorithm.morphology.DEF_MAX_RADIUS

Example

>>> from timagetk.io.util import shared_dataset
>>> from timagetk.io import imread
>>> from timagetk.visu.mplt import grayscale_imshow
>>> img = imread(shared_dataset('p58', 'intensity', 0)[0])
>>> from timagetk.algorithms.morphology import morphology_coc_alternate_sequential_filter
>>> asf = morphology_coc_alternate_sequential_filter(img, 2)
>>> grayscale_imshow([img, asf], slice_id=img.get_shape('z')//2, axis='z', title=['Original', 'COC asf'])
timagetk.algorithms.morphology.morphology_oc_alternate_sequential_filter(image, max_radius=3, **kwargs)[source]

Opening Closing alternate sequential filter on grayscale image.

Parameters:

  • image (timagetk.SpatialImage) – Apply the morphological operator to this intensity image.

  • max_radius (int, optional) – Maximum value reached by radius, starting from 1. Defaults to DEF_MAX_RADIUS.

Returns:

timagetk.SpatialImage – Transformed intensity image and its metadata

See also

timagetk.algorithm.morphology.DEF_MAX_RADIUS

Example

>>> from timagetk.io.util import shared_dataset
>>> from timagetk.io import imread
>>> from timagetk.visu.mplt import grayscale_imshow
>>> img = imread(shared_dataset('p58', 'intensity', 0)[0])
>>> from timagetk.algorithms.morphology import morphology_oc_alternate_sequential_filter
>>> asf = morphology_oc_alternate_sequential_filter(img, 2)
>>> grayscale_imshow([img, asf], slice_id=img.get_shape('z')//2, axis='z', title=['Original', 'OC asf'])
timagetk.algorithms.morphology.morphology_oco_alternate_sequential_filter(image, max_radius=3, **kwargs)[source]

Opening Closing Opening alternate sequential filter on grayscale image.

Parameters:

  • image (timagetk.SpatialImage) – Apply the morphological operator to this intensity image.

  • max_radius (int, optional) – Maximum value reached by radius, starting from 1. Defaults to DEF_MAX_RADIUS.

Returns:

timagetk.SpatialImage – Transformed intensity image and its metadata.

See also

timagetk.algorithm.morphology.DEF_MAX_RADIUS

Example

>>> from timagetk.io.util import shared_dataset
>>> from timagetk.io import imread
>>> from timagetk.visu.mplt import grayscale_imshow
>>> img = imread(shared_dataset('p58', 'intensity', 0)[0])
>>> from timagetk.algorithms.morphology import morphology_oco_alternate_sequential_filter
>>> asf = morphology_oco_alternate_sequential_filter(img, 2)
>>> grayscale_imshow([img, asf], slice_id=img.get_shape('z')//2, axis='z', title=['Original', 'OCO asf'])