Filtering » Binary image filters module

#include "diplib/binary.h"

void dip::BinaryDilation(dip::Image const& in, dip::Image& out, dip::sint connectivity = -1, dip::uint iterations = 3, dip::String const& edgeCondition = S::BACKGROUND)

Binary morphological dilation operation.

The connectivity parameter defines the metric, that is, the shape of the structuring element (see Connectivity). Alternating connectivity is only implemented for 2D and 3D images.

The edgeCondition parameter specifies whether pixels past the border of the image should be treated as object (by passing "object") or as background (by passing "background").

For dilations with arbitrary structuring elements, see dip::Dilation, for dilations with an isotropic (disk) structuring element, see dip::IsotropicDilation.

void dip::BinaryErosion(dip::Image const& in, dip::Image& out, dip::sint connectivity = -1, dip::uint iterations = 3, dip::String const& edgeCondition = S::OBJECT)

Binary morphological erosion operation.

The connectivity parameter defines the metric, that is, the shape of the structuring element (see Connectivity). Alternating connectivity is only implemented for 2D and 3D images.

The edgeCondition parameter specifies whether pixels past the border of the image should be treated as object (by passing "object") or as background (by passing "background").

For erosions with arbitrary structuring elements, see dip::Erosion, for erosions with an isotropic (disk) structuring element, see dip::IsotropicDilation.

void dip::BinaryClosing(dip::Image const& in, dip::Image& out, dip::sint connectivity = -1, dip::uint iterations = 3, dip::String const& edgeCondition = S::SPECIAL)

Binary morphological closing operation.

The connectivity parameter defines the metric, that is, the shape of the structuring element (see Connectivity). Alternating connectivity is only implemented for 2D and 3D images.

The edgeCondition parameter specifies whether pixels past the border of the image should be treated as object (by passing "object") or as background (by passing "background"). Additionally, you can set it to "special" for special handling: "background" for the dilation, "object" for the erosion; this avoids the border effect you can get in the corners of the image in some cases.

For closings with arbitrary structuring elements, see dip::Closing.

void dip::BinaryOpening(dip::Image const& in, dip::Image& out, dip::sint connectivity = -1, dip::uint iterations = 3, dip::String const& edgeCondition = S::SPECIAL)

Binary morphological opening operation.

The connectivity parameter defines the metric, that is, the shape of the structuring element (see Connectivity). Alternating connectivity is only implemented for 2D and 3D images.

The edgeCondition parameter specifies whether pixels past the border of the image should be treated as object (by passing "object") or as background (by passing "background"). Additionally, you can set it to "special" for special handling: "object" for the erosion, "background" for the dilation; this avoids the border effect you can get in the corners of the image in some cases.

For openings with arbitrary structuring elements, see dip::Opening.

void dip::IsotropicDilation(dip::Image const& in, dip::Image& out, dip::dfloat distance)

Isotropic dilation of binary image.

Does a threshold of the dip::EuclideanDistanceTransform of the background of in. This is much faster than applying dip::Dilation with a disk structuring element of diameter 2 * distance, for larger sizes.

For other structuring element shapes, or for gray-scale images, use dip::Dilation. See also dip::BinaryDilation.

void dip::IsotropicErosion(dip::Image const& in, dip::Image& out, dip::dfloat distance)

Isotropic erosion of binary image.

Does a threshold of the dip::EuclideanDistanceTransform of in. This is much faster than applying dip::Erosion with a disk structuring element of diameter 2 * distance, for larger sizes.

For other structuring element shapes, or for gray-scale images, use dip::Erosion. See also dip::BinaryErosion.

void dip::IsotropicClosing(dip::Image const& in, dip::Image& out, dip::dfloat distance)

Isotropic closing of binary image.

Composition of dip::IsotropicDilation and dip::IsotropicErosion.

For other structuring element shapes, or for gray-scale images, use dip::Closing. See also dip::BinaryClosing.

void dip::IsotropicOpening(dip::Image const& in, dip::Image& out, dip::dfloat distance)

Isotropic opening of binary image.

Composition of dip::IsotropicErosion and dip::IsotropicDilation.

For other structuring element shapes, or for gray-scale images, use dip::Opening. See also dip::BinaryOpening.

void dip::BinaryPropagation(dip::Image const& inSeed, dip::Image const& inMask, dip::Image& out, dip::sint connectivity = 1, dip::uint iterations = 0, dip::String const& edgeCondition = S::BACKGROUND)

Morphological propagation of binary objects.

inSeed contains the seeds to propagate. To use no seeds, simply pass a raw image, i.e. dip::Image(). inMask contains the mask in which propagation is allowed.

The connectivity parameter defines the metric, that is, the shape of the structuring element (see Connectivity). Alternating connectivity is only implemented for 2D and 3D images.

The edgeCondition parameter specifies whether pixels past the border of the image should be treated as object (by passing "object") or as background (by passing "background").

The algorithm is repeated iterations times. Pass 0 to continue until propagation is completed. With iterations==0, a faster algorithm is used.

See also dip::MorphologicalReconstruction, which is less flexible but works for gray-scale images.

void dip::EdgeObjectsRemove(dip::Image const& c_in, dip::Image& out, dip::uint connectivity = 1)

Remove edge objects from a binary or labeled image.

Removes those objects from in that are connected to the edges of the image.

If the input image is binary. this function calls dip::BinaryPropagation with no seed image and edgeCondition set to "object". The result of the propagation is xor-ed with the input image. In this case, the connectivity parameter defines the metric, that is, the shape of the structuring element (see Connectivity).

If the input image is labeled, this function erases the labels that touch the image edge. In this case, connectivity is ignored. Note that a labeled image must be of an unsigned integer type.

void dip::FillHoles(dip::Image const& in, dip::Image& out, dip::uint connectivity = 1)

Fill holes in binary image.

Removes holes in binary objects in in that are not connected to the edges of the image. This function calls dip::BinaryPropagation using the inverted in, with no seed image, and edgeCondition set to "object". This finds the background connected to the edge, which is the only background to be preserved.

The connectivity parameter defines the metric, that is, the shape of the structuring element (see Connectivity).

void dip::ConditionalThickening2D(dip::Image const& c_in, dip::Image const& c_mask, dip::Image& out, dip::uint iterations = 0, dip::String const& endPixelCondition = S::LOSE, dip::String const& edgeCondition = S::BACKGROUND)

Thickens the image in conditioned on the mask (2D only).

A thickening is a dilation that preserves topology. If no mask is given (i.e. the image is raw), it will produce an inverse skeleton of the background (given sufficient iterations). If a mask is given, the dilation will not propagate outside of the set pixels in mask.

The dilation always uses the unit 4-connected neighborhood. That is, it iteratively propagates using a connectivity of 1. The topology preserved is that of the 8-connected background. iterations iterations are applied. If iterations is 0, the algorithm iterates until idempotency.

endPixelCondition determines if background branches are kept. The string "keep" is equivalent to the "natural" end pixel condition in dip::EuclideanSkeleton, and "lose" causes branches to not be kept (meaning that only single background pixels and loops in background are kept).

The edgeCondition parameter specifies whether the border of the image should be treated as object ("object") or as background ("background"). Note that the algorithm doesn’t propagate into the pixels around the edge of the image. The edgeCondition is used to modify the input image before the iterative process starts.

void dip::ConditionalThinning2D(dip::Image const& in, dip::Image const& mask, dip::Image& out, dip::uint iterations = 0, dip::String const& endPixelCondition = S::LOSE, dip::String const& edgeCondition = S::BACKGROUND)

Thins the image in conditioned on the mask (2D only).

A thinning is an erosion that preserves topology. If no mask is given (i.e. the image is raw), it will produce a skeleton of the object (given sufficient iterations). If a mask is given, the erosion will not propagate outside of the set pixels in mask. Note that dip::EuclideanSkeleton produces a better skeleton.

The erosion always uses the unit 4-connected neighborhood. That is, it iteratively propagates using a connectivity of 1. The topology preserved is that of the 8-connected foreground. iterations iterations are applied. If iterations is 0, the algorithm iterates until idempotency.

endPixelCondition determines if background branches are kept. The string "keep" is equivalent to the "natural" end pixel condition in dip::EuclideanSkeleton, and "lose" causes branches to not be kept (meaning that only single background pixels and loops in background are kept).

The edgeCondition parameter specifies whether the border of the image should be treated as object ("object") or as background ("background"). Note that the algorithm doesn’t propagate into the pixels around the edge of the image. The edgeCondition is used to modify the input image before the iterative process starts.

void dip::BinaryAreaOpening(dip::Image const& in, dip::Image& out, dip::uint filterSize, dip::uint connectivity = 0, dip::String const& edgeCondition = S::BACKGROUND)

Computes the area opening of a binary image

The area opening removes all connected components that have an area smaller than the given parameter filterSize, and is equivalent to the supremum of openings with all possible connected structuring elements of that area.

connectivity determines what a connected component is. See Connectivity for information on the connectivity parameter.

The edgeCondition parameter specifies whether pixels past the border of the image should be treated as object (by passing "object") or as background (by passing "background").

The operation is implemented through dip::Label.

void dip::EuclideanSkeleton(dip::Image const& in, dip::Image& out, dip::String const& endPixelCondition = S::NATURAL, dip::String const& edgeCondition = S::BACKGROUND)

Accurate binary skeleton (2D and 3D only).

This algorithm computes quasi-Euclidean distances and tests Hilditch conditions to preserve topology. In 2D, integer distances to neighbors are as follows:

and in 3D as follows:

The endPixelCondition parameter determines what is considered an “end pixel” in the skeleton, and thus affects how many branches are generated. It is one of the following strings:

• "loose ends away": Loose ends are eaten away (nothing is considered an end point).
• "natural": “natural” end pixel condition of this algorithm.
• "one neighbor": Keep endpoint if it has one neighbor.
• "two neighbors": Keep endpoint if it has two neighbors.
• "three neighbors": Keep endpoint if it has three neighbors.

The edgeCondition parameter specifies whether the border of the image should be treated as object ("object") or as background ("background").

void dip::CountNeighbors(dip::Image const& in, dip::Image& out, dip::uint connectivity = 0, dip::String const& mode = S::FOREGROUND, dip::String const& edgeCondition = S::BACKGROUND)

Counts the number of set neighbors for each pixel in the binary image in.

Out will contain, for each set pixel, 1 + the number of neighbors that are also set. The neighborhood is given by connectivity, see Connectivity for more information. If mode is set to "all", the count is computed for all pixels, not only the foreground ones. In this case, for the non-set pixels the count is not increased by 1, and therefore yields simply the count of set pixels in the full neighborhood.

edgeCondition determines the value of pixels outside the image domain, and can be "object" or "background".

This function is typically used on the output of dip::EuclideanSkeleton to distinguish different types of pixels.

void dip::MajorityVote(dip::Image const& in, dip::Image& out, dip::uint connectivity = 0, dip::String const& edgeCondition = S::BACKGROUND)

Filters the binary image by setting each pixel to the phase with more pixels in the neighborhood.

The majority vote filter is the binary equivalent to the median filter. If in the neighborhood of a pixel there are more foreground than background pixels, the pixel will be set to foreground. Otherwise it will be set to background. The pixel itself is part of the neighborhood, and therefore the neighborhood always has an odd number of pixels.

Note that this is equivalent to (but more efficient than):

dip::uint neighborhoodSize = dip::NeighborList( { "connected", connectivity }, in.Dimensionality() ).Size();
out = dip::CountNeighbors( in, connectivity, "all", edgeCondition ) > neighborhoodSize / 2;

with neighborhoodSize the number of pixels in the neighborhood given by connectivity.

edgeCondition determines the value of pixels outside the image domain, and can be "object" or "background".

void dip::SupGenerating(dip::Image const& in, dip::Image& out, dip::Interval const& interval, dip::String const& boundaryCondition = S::ADD_ZEROS)

Sup-generating operator, also known as hit-miss operator.

The sup-generating operator is a relaxed template matching, where interval is the template. interval contains some pixels that must be foreground, and some that must be background, but also allows “don’t care” pixels, which will be ignored in the matching.

This operator is equal to the infimum of an erosion and an anti-erosion:

out = dip::Infimum( dip::Erosion( in, hit ), dip::Erosion( ~in, miss ));

where hit and miss are the two binary structuring elements in interval.

This function is specifically for binary images. Use dip::HitAndMiss for a more general operator.

void dip::InfGenerating(dip::Image const& in, dip::Image& out, dip::Interval const& interval, dip::String const& boundaryCondition = S::ADD_ZEROS)

Inf-generating operator, the dual of the hit-miss operator.

This operator is equal to the supremum of a dilation and an anti-dilation:

out = dip::Supremum( dip::Dilation( in, hit ), dip::Dilation( ~in, miss ));

where hit and miss are the two binary structuring elements in interval.

This function is specifically for binary images.

void dip::UnionSupGenerating(dip::Image const& in, dip::Image& out, dip::IntervalArray const& intervals, dip::String const& boundaryCondition = S::ADD_ZEROS)

Union of sup-generating operators.

Applies the sup-generating operator with each of the intervals in intervals, and takes the union of the results.

This function is specifically for binary images.

void dip::UnionSupGenerating2D(dip::Image const& in, dip::Image& out, dip::Interval const& interval, dip::uint rotationAngle = 45, dip::String const& rotationDirection = S::INTERLEAVED_CLOCKWISE, dip::String const& boundaryCondition = S::ADD_ZEROS)

Union of sup-generating operators.

Applies the sup-generating operator with all the rotated versions of interval, and takes the union of the results. See dip::Interval::GenerateRotatedVersions for the definition of rotationAngle and rotationDirection.

This function is specifically for 2D binary images.

void dip::IntersectionInfGenerating(dip::Image const& in, dip::Image& out, dip::IntervalArray const& intervals, dip::String const& boundaryCondition = S::ADD_ZEROS)

Intersection of inf-generating operators.

Applies the inf-generating operator with each of the intervals in intervals, and takes the intersection of the results.

This function is specifically for binary images.

void dip::IntersectionInfGenerating2D(dip::Image const& in, dip::Image& out, dip::Interval const& interval, dip::uint rotationAngle = 45, dip::String const& rotationDirection = S::INTERLEAVED_CLOCKWISE, dip::String const& boundaryCondition = S::ADD_ZEROS)

Intersection of inf-generating operators.

Applies the inf-generating operator with all the rotated versions of interval, and takes the intersection of the results. See dip::Interval::GenerateRotatedVersions for the definition of rotationAngle and rotationDirection.

This function is specifically for 2D binary images.

void dip::Thickening(dip::Image const& in, dip::Image const& mask, dip::Image& out, dip::IntervalArray const& intervals, dip::uint iterations = 0, dip::String const& boundaryCondition = S::ADD_ZEROS)

Applies the thickening operator, optionally constrained by a mask, to an image.

Thickening is defined as in + SupGenerating(in). The constrained operation is defined as in + (SupGenerating(in) & mask).

The operation is applied with each of the intervals in intervals, and repeated iterations times. If iterations is 0, the operation is repeated until convergence.

A thickening with the right set of intervals leads to a background skeleton, also called skiz. See dip::HomotopicThickeningInterval2D. The intervals returned by dip::HomotopicInverseEndPixelInterval2D prune the skiz to single points and circles.

This function is specifically for binary images.

void dip::Thickening2D(dip::Image const& in, dip::Image const& mask, dip::Image& out, dip::Interval const& interval, dip::uint iterations = 0, dip::uint rotationAngle = 45, dip::String const& rotationDirection = S::INTERLEAVED_CLOCKWISE, dip::String const& boundaryCondition = S::ADD_ZEROS)

Applies the thickening operator, optionally constrained by a mask, to an image.

The operation is applied with with all the rotated versions of interval, and repeated iterations times. See dip::Thickening for a description of the operation. See dip::Interval::GenerateRotatedVersions for the definition of rotationAngle and rotationDirection.

This function is specifically for 2D binary images.

void dip::Thinning(dip::Image const& in, dip::Image const& mask, dip::Image& out, dip::IntervalArray const& intervals, dip::uint iterations = 0, dip::String const& boundaryCondition = S::ADD_ZEROS)

Applies the thinning operator, optionally constrained by a mask, to an image.

Thinning is defined as in - SupGenerating(in). The constrained operation is defined as in - (SupGenerating(in) & mask).

The operation is applied with each of the intervals in intervals, and repeated iterations times. If iterations is 0, the operation is repeated until convergence.

A thinning with the right set of intervals leads to a skeleton. See dip::HomotopicThinningInterval2D. The intervals returned by dip::HomotopicEndPixelInterval2D prune the skeleton to single points and circles.

This function is specifically for binary images.

void dip::Thinning2D(dip::Image const& in, dip::Image const& mask, dip::Image& out, dip::Interval const& interval, dip::uint iterations = 0, dip::uint rotationAngle = 45, dip::String const& rotationDirection = S::INTERLEAVED_CLOCKWISE, dip::String const& boundaryCondition = S::ADD_ZEROS)

Applies the thinning operator, optionally constrained by a mask, to an image.

The operation is applied with with all the rotated versions of interval, and repeated iterations times. See dip::Thinning for a description of the operation. See dip::Interval::GenerateRotatedVersions for the definition of rotationAngle and rotationDirection.

This function is specifically for 2D binary images.

dip::IntervalArray dip::HomotopicThinningInterval2D(dip::uint connectivity = 2)

Returns a 2D interval array for homotopic thinning.

Use with dip::Thinning to shrink objects without changing the Euler number. Note that dip::ConditionalThinning2D is more efficient, though the two functions do not produce exactly the same output. To create a skeleton, use dip::EuclideanSkeleton.

connectivity can be 1 to produce 4-connected skeletons, or 2 for 8-connected skeletons.

dip::IntervalArray dip::HomotopicThickeningInterval2D(dip::uint connectivity = 2)

Returns a 2D interval array for homotopic thickening.

Use with dip::Thickening to grow objects without merging them. This produces a background skeleton (also known as skiz). Note that dip::ConditionalThickening2D is more efficient, though the two options do not produce exactly the same output. To create a background skeleton, use dip::EuclideanSkeleton on the inverted image.

connectivity can be 1 to produce 4-connected skeletons, or 2 for 8-connected skeletons.

dip::IntervalArray dip::EndPixelInterval2D(dip::uint connectivity = 2)

Returns an interval array for detecting end pixels. Includes isolated pixels.

Use with dip::UnionSupGenerating to detect skeleton end pixels. Note that dip::GetEndPixels is more efficient.

connectivity can be 1 to work with 4-connected skeletons, or 2 for 8-connected skeletons.

dip::IntervalArray dip::HomotopicEndPixelInterval2D(dip::uint connectivity = 2)

Returns an interval array for detecting end pixels. Excludes isolated pixels

Use with dip::Thinning to prune end points from the skeleton.

connectivity can be 1 to prune 4-connected skeletons, or 2 for 8-connected skeletons.

dip::IntervalArray dip::HomotopicInverseEndPixelInterval2D(dip::uint connectivity = 2)

Returns an interval array for detecting end background pixels. Excludes isolated pixels.

Use with dip::Thickening to prune end points from the background skeleton.

connectivity can be 1 to prune 4-connected skeletons, or 2 for 8-connected skeletons.

dip::IntervalArray dip::BranchPixelInterval2D()

Returns a 2D interval array for detecting branch pixels.

Use with dip::UnionSupGenerating to detect skeleton branch pixels. Note that dip::GetBranchPixels is more efficient.

dip::Interval dip::BoundaryPixelInterval2D()

Returns a 2D interval for detecting boundary pixels.

Use with dip::UnionSupGenerating2D to detect object boundary pixels. Set rotationAngle to 45 to detect pixels 8-connected to the background, and to 90 to detect pixels 4-connected to the background. Note that the difference between the input image and the eroded image accomplishes the same thing.

dip::IntervalArray dip::ConvexHullInterval2D()

Returns a 2D interval array to thicken to a convex hull.

Use with dip::Thickening to grow concave sections of objects until the objects are all convex. This leads to octagonal shapes.