Mathematical morphology ======================= Binary operators ---------------- binary-closing ball|box ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs a binary morphological closing on the input image. The image is supposed to be binary, with the background set to 0 and the foreground set to 1. This operator provides the same result than the more general closing operator (see ``closing``) but its implementation specific to binary images is more efficient. The first parameter of this filter specifies the shape of the structuring element (neighbourhood). When set to ``ball``, circular (2D) or spherical (3D) structuring elements are used. When set to ``box``, square (2D) or cubic (3D) structuring elements are used. The size of the structuring element is controlled by the ``radius`` parameter. binary-dilation ball|box ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs a binary morphological dilation on the input image. The image is supposed to be binary, with the background set to 0 and the foreground set to 1. This operator provides the same result than the more general dilation operator (see ``max-filter``) but its implementation specific to binary images is more efficient. The first parameter of this filter specifies the shape of the structuring element (neighbourhood). When set to ``ball``, circular (2D) or spherical (3D) structuring elements are used. When set to ``box``, square (2D) or cubic (3D) structuring elements are used. The size of the structuring element is controlled by the ``radius`` parameter. binary-erosion ball|box ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs a binary morphological erosion on the input image. The image is supposed to be binary, with the background set to 0 and the foreground set to 1. This operator provides the same result than the more general erosion operator (see ``min-filter``) but its implementation specific to binary images is more efficient. The first parameter of this filter specifies the shape of the structuring element (neighbourhood). When set to ``ball``, circular (2D) or spherical (3D) structuring elements are used. When set to ``box``, square (2D) or cubic (3D) structuring elements are used. The size of the structuring element is controlled by the ``radius`` parameter. binary-inner-ring ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator computes the inner ring of objects in a binary image. The ``width`` parameter controls the size of the ring. The inner ring is defined as the part of objects that is removed during their erosion (:numref:`fig:binary-rings`): .. math:: \mathrm{Inner Ring}(I)=I-(I\ominus B_w) where :math:`I\ominus B_w` denotes the erosion of image :math:`I` by a circular (2D) or spherical (3D) structuring element :math:`B_w` of radius :math:`w`. Note that the inner ring includes the object contours. .. figure:: ../../include/nuclei-binary-rings.png :name: fig:binary-rings Operators for binary mathematical morphology: inner and outer rings. binary-opening ball|box ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs a binary morphological opening on the input image. The image is supposed to be binary, with the background set to 0 and the foreground set to 1. This operator provides the same result than the more general opening operator (see ``opening``) but its implementation specific to binary images is more efficient. The first parameter of this filter specifies the shape of the structuring element (neighbourhood). When set to ``ball``, circular (2D) or spherical (3D) structuring elements are used. When set to ``box``, square (2D) or cubic (3D) structuring elements are used. The size of the structuring element is controlled by the ``radius`` parameter. binary-outer-ring ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator computes the outer ring of objects in a binary image. The ``width`` parameter controls the size of the ring. The outer ring is defined as the part of objects that is added during their dilation (:numref:`fig:binary-rings`): .. math:: \mathrm{Outer Ring}(I)=(I\oplus B_w)-I where :math:`I\oplus B_w` is the dilation of image :math:`I` by a circular (2D) or spherical (3D) structuring element :math:`B_w` of radius :math:`w`. Note that the outer ring does not include object contours. fast-binary-closing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs a binary closing on the input image. The structuring element is a disk in 2D and a sphere in 3D. The output is the same as the one obtained with the ``binary-closing`` operator using a ball as structuring element. However, the ``fast-binary-closing`` operator runs in constant time (with regards to the size of the structuring element). It is thus more efficient when using large structuring elements. The ``radius`` parameter controls the size of the structuring element. It is expressed in pixels (2D) or voxels (3D). fast-binary-dilation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs a binary dilation on the input image. The structuring element is a disk in 2D and a sphere in 3D. The output is the same as the one obtained with the ``binary-dilation`` operator using a ball as structuring element. However, the ``fast-binary-dilation`` operator runs in constant time (with regards to the size of the structuring element). It is thus more efficient when using large structuring elements. The ``radius`` parameter controls the size of the structuring element. It is expressed in pixels (2D) or voxels (3D). fast-binary-erosion ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs a binary erosion on the input image. The structuring element is a disk in 2D and a sphere in 3D. The output is the same as the one obtained with the ``binary-erosion`` operator using a ball as structuring element. However, the ``fast-binary-erosion`` operator runs in constant time (with regards to the size of the structuring element). It is thus more efficient when using large structuring elements. The ``radius`` parameter controls the size of the structuring element. It is expressed in pixels (2D) or voxels (3D). fast-binary-opening ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs a binary opening on the input image. The structuring element is a disk in 2D and a sphere in 3D. The output is the same as the one obtained with the ``binary-opening`` operator using a ball as structuring element. However, the ``fast-binary-opening`` operator runs in constant time (with regards to the size of the structuring element). It is thus more efficient when using large structuring elements. The ``radius`` parameter controls the size of the structuring element. It is expressed in pixels (2D) or voxels (3D). fill-holes [-n 4,6|8,26] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator fills holes present in a binary image. A hole is a set of background values completely surrounded by foreground values. Completely surrounded means these background values are not connected to a connected set of background values that reach the image border. The connectivity used to define the neighbourhood system when computing the connected components is set using the ``-n`` option. See :ref:`sec-neighbourhood-system` for more information about the meaning and usage of this option. ultimate-erosion [-n 4,6|8,26] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator computes the ultimate eroded set of the input image. When progressively eroding a binary image, the ultimate eroded set is defined as the union of the connected component that disappear at each erosion step. In practice, the ultimate eroded is computed as the regional maxima of the distance transform of the input image :cite:p:`Soille2003`. In our implementation, the output image contains the values of the distance transform in the ultimate eroded set. The connectivity used to define the neighbourhood system when computing the connected components is set using the ``-n`` option. See :ref:`sec-neighbourhood-system` for more information about the meaning and usage of this option. Grayscale operators ------------------- asf-closing-opening ball|box ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This filter smooths the input image through a sequence of alternated closing and opening operations, starting first with a closing. It is useful to smooth out noise or other undesired structures when they cover a range of different scales and introduces less distorsion than applying opening and closing with a large structuring element :cite:p:`Sternberg1986`. The first parameter of this filter specifies the shape of the neighbourhood (structuring element) used in openings and closings. When set to ``ball``, circular (2D) or spherical (3D) neighbourhoods are used. When set to ``box``, square (2D) or cubic (3D) neighbourhoods are used. The radius of the neighbourhood is varied step-by-step from ``first-radius`` to ``last-radius``. Hence, running this operator with a ball neighbourhood and with ``first-radius`` set to 1 and ``last-radius`` set to 3 is equivalent to applying the following pipeline: :: closing ball 1 opening ball 1 closing ball 2 opening ball 2 closing ball 3 opening ball 3 asf-opening-closing ball|box ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This filter smooths the input image through a sequence of alternated opening and closing operations, starting first with an opening. It is useful to smooth out noise or other undesired structures when they cover a range of different scales and introduces less distorsion than applying opening and closing with a large structuring element :cite:p:`Sternberg1986`. The first parameter of this filter specifies the shape of the neighbourhood (structuring element) used in openings and closings. When set to ``ball``, circular (2D) or spherical (3D) neighbourhoods are used. When set to ``box``, square (2D) or cubic (3D) neighbourhoods are used. The radius of the neighbourhood is varied step-by-step from ``first-radius`` to ``last-radius``. closing ball|box ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs a morphological closing on the input image. Closing is a combination of a dilation (see ``max-filter``) followed by an erosion (see ``min-filter``), where the dilation and erosion are performed using the same structuring element. A morphological closing fills dark holes that are smaller than the structuring element. This operator can be applied to both binary and grey-level images. The first parameter of this filter specifies the shape of the structuring element (neighbourhood). When set to ``ball``, circular (2D) or spherical (3D) structuring elements are used. When set to ``box``, square (2D) or cubic (3D) structuring elements are used. The size of the structuring element is controlled by the ``radius`` parameter. dilation-reconstruction [-n 4,6|8,26] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs the reconstruction by dilation of the specified mask from the input image. The reconstruction by dilation is the geodesic dilation iterated until stability. The implementation follows the hybrid algorithm :cite:p:`Vincent1993`. The connectivity used for propagation is set using the ``-n`` option. See :ref:`sec-neighbourhood-system` for more information about the meaning and usage of this option. erosion-reconstruction [-n 4,6|8,26] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs the reconstruction by erosion of the specified mask from the input image. The reconstruction by erosion is the geodesic erosion iterated until stability. The implementation follows the hybrid algorithm :cite:p:`Vincent1993`. The connectivity used for propagation is set using the ``-n`` option. See :ref:`sec-neighbourhood-system` for more information about the meaning and usage of this option. extended-maxima [-n 4,6|8,26] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator computes the extended maxima of the input image. The extended maxima are the regional maxima of the h-maxima transform of the image. This transform labels bright domains that are significant in the sense that their height is equal or larger than specified ``h`` value. The connectivity used in the algorithm is set using the ``-n`` option. See :ref:`sec-neighbourhood-system` for more information about the meaning and usage of this option. extended-minima [-n 4,6|8,26] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator computes the extended minima of the input image. The extended minima are the regional minima of the h-minima transform of the image. This transform labels dark domains that are significant in the sense that their depth is equal or larger than the specified ``h`` value. The connectivity used in the algorithm is set using the ``-n`` option. See :ref:`sec-neighbourhood-system` for more information about the meaning and usage of this option. h-maxima [-n 4,6|8,26] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator computes the h-maxima transform of the input image. This transforms filters out all peaks with height smaller than the specified ``h`` value. Other peaks are preserved, but their altitude is decreased by ``h``. Note. The h-maxima transform of an image :math:`f` is the geodesic reconstruction by dilation of :math:`f` from :math:`f-h`: :math:`\textrm{h-maxima}(f)=R_f^{\delta}(f-h)`. The implementation of the corresponding algorithm takes care of possible numerical overflows when computing the difference :math:`f-h`. The connectivity used in the reconstruction algorithm is set using the ``-n`` option. See :ref:`sec-neighbourhood-system` for more information about the meaning and usage of this option. h-minima [-n 4,6|8,26] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator computes the h-minima transform of the input image. This transforms filters out all troughs with depth smaller than the specified ``h`` value. Other troughs are preserved, but their depth is decreased by ``h``. Note. The h-minima transform of an image :math:`f` is the geodesic reconstruction by erosion of :math:`f` from :math:`f+h`: :math:`\textrm{h-minima}(f)=R_f^{\varepsilon}(f+h)`. The implementation of the corresponding algorithm takes care of possible numerical overflows when computing the sum :math:`f+h`. The connectivity used in the reconstruction algorithm is set using the ``-n`` option. See :ref:`sec-neighbourhood-system` for more information about the meaning and usage of this option. max-filter ball|box ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs a morphological dilation on the input image using a flat structuring element. This corresponds to a local maximum filter, where each position is assigned the largest value observed over its neighbourhood. This operator can be applied to both binary and grey-level images. The first parameter of this filter specifies the shape of the structuring element (neighbourhood). When set to ``ball``, circular (2D) or spherical (3D) structuring elements are used. When set to ``box``, square (2D) or cubic (3D) structuring elements are used. The size of the structuring element is controlled by the ``radius`` parameter. min-filter ball|box ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs a morphological erosion on the input image using a flat structuring element. This corresponds to a local minimum filter, where each position is assigned the smallest value observed over its neighbourhood. This operator can be applied to both binary and grey-level images. The first parameter of this filter specifies the shape of the structuring element (neighbourhood). When set to ``ball``, circular (2D) or spherical (3D) structuring elements are used. When set to ``box``, square (2D) or cubic (3D) structuring elements are used. The size of the structuring element is controlled by the ``radius`` parameter. opening ball|box ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs a morphological opening on the input image. Opening is a combination of an erosion (see ``min-filter``) followed by a dilation (see ``max-filter``), where the dilation and erosion are performed using the same structuring element. A morphological opening removes bright objects that are smaller than the structuring element. This operator can be applied to both binary and grey-level images. The first parameter of this filter specifies the shape of the structuring element (neighbourhood). When set to ``ball``, circular (2D) or spherical (3D) structuring elements are used. When set to ``box``, square (2D) or cubic (3D) structuring elements are used. The size of the structuring element is controlled by the ``radius`` parameter. regional-maxima [-n 4,6|8,26] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator computes the regional maxima in the input image. A regional maximum is a connected set of positions that share the same value and for which neighbours not included in the set have strictly smaller values. In the output image, positions not belonging to regional maxima are set to the lowest value of the image numerical type. Positions in regional maxima keep their original (input) value. This behaviour may change in the future. The connectivity used when computing connected components is set using the ``-n`` option. See :ref:`sec-neighbourhood-system` for more information about the meaning and usage of this option. regional-minima [-n 4,6|8,26] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator computes the regional minima in the input image. A regional minimum is a connected set of positions that share the same value and for which neighbours not included in the set have strictly higher values. In the output image, positions not belonging to regional minima are set to 0. Positions in regional minima are assigned the maximum value of the image numerical type. This behaviour may change in the future. The connectivity used when computing connected components is set using the ``-n`` option. See :ref:`sec-neighbourhood-system` for more information about the meaning and usage of this option. size-closing [-n 4,6|8,26] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs a closing by size attribute on the input image. When applied to a binary image, this operator fills all the background components with size below the specified threshold. When applied to a grey-scale image, this operator assigns to each position the smallest value at which the position still belongs to a connected trough component of size equal or above the specified threshold. This operator is in particular useful to filter images containing thin or elongated structures :cite:p:`Vincent1993b`. The implemented algorithm is a corrected but close to literal version of the union-find algorithm described in :cite:p:`Meijster2002`. The connectivity used for propagation is set using the ``-n`` option. See :ref:`sec-neighbourhood-system` for more information about the meaning and usage of this option. size-opening [-n 4,6|8,26] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator performs an opening by size attribute on the input image. When applied to a binary image, this operator selects all the components with size equal or above the specified threshold. When applied to a grey-scale image, this operator assigns to each position the highest value at which the position still belongs to a connected peak component of size equal or above the specified threshold. This operator is in particular useful to filter images containing thin or elongated structures :cite:p:`Vincent1993b`. The implemented algorithm is a corrected but close to literal version of the union-find algorithm described in :cite:p:`Meijster2002`. The connectivity used for propagation is set using the ``-n`` option. See :ref:`sec-neighbourhood-system` for more information about the meaning and usage of this option. toggle-filter [-i ] ball|box ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This filter performs local contrast enhancement using mathematical morphology operators :cite:p:`Kramer1975`. Each position is assigned its corresponding value in the eroded or in the dilated image, depending on which one is the closest to its original (input) value. The first parameter of this filter specifies the shape of the structuring element (neighbourhood) used in the dilation and erosion operations. When set to ``ball``, circular (2D) or spherical (3D) structuring elements are used. When set to ``box``, square (2D) or cubic (3D) structuring elements are used. The size of the structuring element is controlled by the ``radius`` parameter. By default, the filter is applied only once on the image. The ``-i`` option can be used to apply the filter recursively an arbitrary number of times. Increasing the number of iterations reinforces the effect of the filter. tophat-black ball|box ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator applies the top-hat transform (“black” version) to the input image, obtained by subtracting the original image to the result of its closing by a structuring element. This operation achieves a background removal in situations where the background is brighter (higher intensities) than the objects of interest. The structuring element should be taken as least as large as the objects of interest. Objects larger than the structuring element will be lumped into the background by this operation. The first parameter of this operator specifies the shape of the structuring element (neighbourhood) used in the opening operation. When set to ``ball``, circular (2D) or spherical (3D) structuring elements are used. When set to ``box``, square (2D) or cubic (3D) structuring elements are used. The size of the structuring element is controlled by the ``radius`` parameter. tophat-white ball|box ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This operator applies the top-hat transform (“white” version) to the input image, obtained by subtracting to the original image the result of its opening by a structuring element. This operation achieves a background removal in situations where the background is darker (lower intensities) than the objects of interest. The structuring element should be taken as least as large as the objects of interest. Objects larger than the structuring element will be lumped into the background by this operation. The first parameter of this operator specifies the shape of the structuring element (neighbourhood) used in the opening operation. When set to ``ball``, circular (2D) or spherical (3D) structuring elements are used. When set to ``box``, square (2D) or cubic (3D) structuring elements are used. The size of the structuring element is controlled by the ``radius`` parameter.