bwpropfilt

Extract objects from binary image using properties

collapse all in page

Syntax

BW2 = bwpropfilt(BW,prop,range)

BW2 = bwpropfilt(BW,prop,n)

BW2 = bwpropfilt(BW,prop,n,keep)

BW2 = bwpropfilt(BW,I,prop,___)

BW2 = bwpropfilt(___,conn)

CC2 = bwpropfilt(CC,prop,range)

CC2 = bwpropfilt(CC,prop,n)

CC2 = bwpropfilt(CC,prop,n,keep)

CC2 = bwpropfilt(CC,I,prop,___)

Description

Objects in Binary Images

BW2 = bwpropfilt(BW,prop,range) extracts all objects from a binary image BW whose value of property prop is in the specified range. bwpropfilt returns a binary image BW2 containing only those objects that meet the criteria.

example

BW2 = bwpropfilt(BW,prop,n) sorts the objects based on the value of the specified property, prop, returning a binary image that contains only the top n largest objects. In the event of a tie for n-th place, bwpropfilt keeps only the first n objects in BW2.

example

BW2 = bwpropfilt(BW,prop,n,keep) specifies whether to keep the n largest objects or the n smallest objects when sorted by property prop.

BW2 = bwpropfilt(BW,I,prop,___) sorts objects based on the intensity values in the grayscale image I and the property prop.

BW2 = bwpropfilt(___,conn) specifies the pixel connectivity, conn.

Objects in Connected Component Structures

CC2 = bwpropfilt(CC,prop,range) returns the connected components in CC whose value of property prop is in the specified range.

example

CC2 = bwpropfilt(CC,prop,n) returns the top n largest connected components. In the event of a tie for n-th place, bwpropfilt keeps only the first n objects in CC2.

CC2 = bwpropfilt(CC,prop,n,keep) specifies whether to keep the n largest connected components or the n smallest connected components when sorted by property prop.

CC2 = bwpropfilt(CC,I,prop,___) sorts connected components based on the intensity values in the grayscale image I and the property prop.

Examples

collapse all

Find Regions Without Holes

Open Live Script

Read image and display it.

BW = imread('text.png');
figure
imshow(BW)
title('Original Image')

Figure contains an axes object. The hidden axes object with title Original Image contains an object of type image.

Use filtering to create a second image that contains only those regions in the original image that do not have holes. For these regions, the Euler number property is equal to 1. Display filtered image.

BW2 = bwpropfilt(BW,'EulerNumber',[1 1]);
figure
imshow(BW2)
title('Regions with Euler Number == 1')

Figure contains an axes object. The hidden axes object with title Regions with Euler Number == 1 contains an object of type image.

Find Which Ten Objects Have Largest Perimeters

Open Live Script

Read image.

BW = imread('text.png');

Find the ten objects in the image with the largest perimeters and display filtered image.

BW2 = bwpropfilt(BW,'perimeter',10);
figure;
imshow(BW2)
title('Objects with the Largest Perimeters')

Figure contains an axes object. The hidden axes object with title Objects with the Largest Perimeters contains an object of type image.

Filter on Multiple Image Properties

Open Live Script

Read and display an image.

I = imread("blobs.png");
imshow(I)

Figure contains an axes object. The hidden axes object contains an object of type image.

Create a connected components structure.

CC = bwconncomp(I);

Filter the structure and keep round objects. Display the filtered image.

CC = bwpropfilt(CC,"Circularity",[0.7 1]);
imshow(cc2bw(CC))

Figure contains an axes object. The hidden axes object contains an object of type image.

Filter the structure again and keep large objects. Display the filtered image.

CC = bwpropfilt(CC,"Area",[20 Inf]);
imshow(cc2bw(CC))

Figure contains an axes object. The hidden axes object contains an object of type image.

Input Arguments

collapse all

`BW` — Image to be filtered
binary image

Image to be filtered, specified as a binary image.

bwpropfilt finds the connected components within the image by using the bwconncomp function.

Data Types: logical

`CC` — Connected components to be filtered
structure

Connected components to be filtered, specified as a structure. You can get a connected component structure from a binary image using the bwconncomp function.

Data Types: struct

`prop` — Name of property on which to filter
character vector | string scalar

Name of property on which to filter, specified as one of these values.

Pixel Value Measurements

Property Name	Description
`"Area"`	Number of pixels in the region.
`"Circularity"`	Roundness of object. The circularity value is computed as: `(4piArea/Perimeter^2)(1 - 0.5/r)^2` where `r = Perimeter/(2pi) + 0.5` The maximum circularity value is 1.
`"ConvexArea"`	Number of pixels in the convex hull. The convex hull is the smallest convex polygon that can contain the region. For more information about classifying pixels on the boundary of the hull, see Classify Pixels That Are Partially Enclosed by ROI.
`"Eccentricity"`	Eccentricity of the ellipse that has the same second-moments as the region. The eccentricity is the ratio of the distance between the foci of the ellipse and its major axis length. Values are numbers in the range [0, 1]. (0 and 1 are degenerate cases. An ellipse whose eccentricity is 0 is actually a circle, while an ellipse whose eccentricity is 1 is a line segment.)
`"EquivDiameter"`	Diameter (in pixels) of a circle with the same area as the region, calculated as `sqrt(4*Area/pi)`.
`"EulerNumber"`	Euler number (also known as the Euler characteristic), calculated as 1 minus the number of holes in the region.
`"Extent"`	Ratio of pixels in the region to pixels in the total bounding box, calculated as `Area` divided by the area of the bounding box.
`"FilledArea"`	Number of pixels in the region after filling all holes in the region.
`"MajorAxisLength"`	Length (in pixels) of the major axis of the ellipse that has the same normalized second central moments as the region.
`"MinorAxisLength"`	Length (in pixels) of the minor axis of the ellipse that has the same normalized second central moments as the region.
`"Orientation"`	Angle (in degrees) between the x-axis and the major axis of the ellipse that has the same second-moments as the region. The value is in the range (–90, 90]. This figure illustrates the axes and orientation of the ellipse. The left side of the figure shows an image region and its corresponding ellipse. The right side shows the same ellipse with the solid blue lines representing the axes. The red dots are the foci. The orientation is the angle between the horizontal dotted line and the major axis.
`"Perimeter"`	Distance (in pixels) around the boundary of the region, calculated by adding the distance between each adjoining pair of pixels around the border of the region. This figure illustrates the pixels included in the perimeter calculation for a sample region.
`"Solidity"`	Proportion of the pixels in the convex hull that are also in the region, calculated as `Area/ConvexArea`.

You can specify a pixel value measurement property from this table when you include a marker image, I, as an input argument to the function.

Pixel Value Measurements

Property Name	Description
`"MaxIntensity"`	Value of the pixel with the greatest intensity in the region.
`"MeanIntensity"`	Mean of all the intensity values in the region.
`"MinIntensity"`	Value of the pixel with the lowest intensity in the region.

Data Types: char | string

`range` — Minimum and maximum property values
2-element numeric vector

Minimum and maximum property values, specified as a 2-element numeric vector of the form [low high]. Values must be nondecreasing.

`n` — Number of objects to return
positive integer

Number of objects to return, specified as a positive integer.

Data Types: double

`keep` — Objects to retain
`"largest"` (default) | `"smallest"`

Objects to retain, specified as "largest" or "smallest".

Data Types: char | string

`I` — Marker image
grayscale image

Marker image, specified as a grayscale image. Intensity values in the grayscale image define regions in the input binary image. The marker image must be the same size as the binary image BW or match the ImageSize field of the connected component structure.

`conn` — Pixel connectivity
`8` (default) | `4` | 3-by-3 matrix of `0`s and `1`s

Pixel connectivity, specified as one of these values.

Value	Meaning
Two-Dimensional Connectivities
`4`	Pixels are connected if their edges touch. Two adjoining pixels are part of the same object if they are both on and are connected along the horizontal or vertical direction.	Current pixel is shown in gray.
`8`	Pixels are connected if their edges or corners touch. Two adjoining pixels are part of the same object if they are both on and are connected along the horizontal, vertical, or diagonal direction.	Current pixel is shown in gray.

Value

Meaning

Two-Dimensional Connectivities

4

Pixels are connected if their edges touch. Two adjoining pixels are part of the same object if they are both on and are connected along the horizontal or vertical direction.

Center pixel connected to four pixels

Current pixel is shown in gray.

8

Pixels are connected if their edges or corners touch. Two adjoining pixels are part of the same object if they are both on and are connected along the horizontal, vertical, or diagonal direction.

Center pixel connected to eight pixels

Current pixel is shown in gray.

Connectivity can also be defined in a more general way by specifying a 3-by-3 matrix of 0s and 1s. The 1-valued elements define neighborhood locations relative to the center element of conn. The matrix must be symmetric about its center element.

Data Types: double | logical

Output Arguments

collapse all

`BW2` — Filtered image
binary image

Filtered image, returned as a binary image of the same size as BW.

`CC2` — Filtered connected components
structure

Filtered connected components, returned as a structure.

Tips

bwpropfilt calculates the properties of connected components using the regionprops function.
To filter on multiple image properties in an efficient way, call bwpropfilt multiple times using the same connected components structure.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

bwpropfilt supports the generation of C code (requires MATLAB^® Coder™). Note that if you choose the generic MATLAB Host Computer target platform, bwpropfilt generates code that uses a precompiled, platform-specific shared library. Use of a shared library preserves performance optimizations but limits the target platforms for which code can be generated. For more information, see Types of Code Generation Support in Image Processing Toolbox.
The prop and keep arguments must be compile-time constants.
If you specify conn as a 3-by-3 matrix, then the matrix must be [0 1 0;1 1 1;0 1 0] or ones(3).
If you generate code for the bwpropfilt function with CC as an argument, then CC.PixelIdxList must be homogeneous. This code shows how to make CC.PixelIdxList homogeneous by using the makeHomogeneous (MATLAB Coder) function.
```
CC = bwconncomp(BW);
typeCC = coder.typeof(CC);
typeCC.Fields.PixelIdxList = makeHomogeneous(typeCC.Fields.PixelIdxList);

codegen bwpropfilt -args {typeCC,coder.Constant("Area"),10}
```
If you generate code for a wrapper function, then you do not need to make CC.PixelIdxList homogeneous. For example, this command generates code for a wrapper function named myFunction.
```
codegen myFunction -args {BW}
```
Here is a sample definition for the wrapper function myFunction that includes a call to the bwpropfilt function.
```
function out = myFunction(BW) %#codegen
    CC = bwconncomp(BW);
    CC2 = bwpropfilt(CC,"Area",10);
    out = cc2bw(CC2);
end
```

Version History

Introduced in R2014b

expand all

R2024a: Filter properties of connected components

You can now specify objects as a connected components structure, CC.

R2024a: Measure circularity

bwpropfilt now measures the circularity of regions in a binary image. To measure the circularity, include "Circularity" when specifying the properties argument.

R2022b: Generate C code using MATLAB Coder

bwpropfilt now supports the generation of C code (requires MATLAB Coder).

bwpropfilt

Syntax

Description

Objects in Binary Images

Objects in Connected Component Structures

Examples

Find Regions Without Holes

Find Which Ten Objects Have Largest Perimeters

Filter on Multiple Image Properties

Input Arguments

`BW` — Image to be filtered
binary image

`CC` — Connected components to be filtered
structure

`prop` — Name of property on which to filter
character vector | string scalar

`range` — Minimum and maximum property values
2-element numeric vector

`n` — Number of objects to return
positive integer

`keep` — Objects to retain
`"largest"` (default) | `"smallest"`

`I` — Marker image
grayscale image

`conn` — Pixel connectivity
`8` (default) | `4` | 3-by-3 matrix of `0`s and `1`s

Output Arguments

`BW2` — Filtered image
binary image

`CC2` — Filtered connected components
structure

Tips

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

R2024a: Filter properties of connected components

R2024a: Measure circularity

R2022b: Generate C code using MATLAB Coder

See Also

Topics

bwpropfilt

Syntax

Description

Objects in Binary Images

Objects in Connected Component Structures

Examples

Find Regions Without Holes

Find Which Ten Objects Have Largest Perimeters

Filter on Multiple Image Properties

Input Arguments

BW — Image to be filtered binary image

CC — Connected components to be filtered structure

prop — Name of property on which to filter character vector | string scalar

range — Minimum and maximum property values 2-element numeric vector

n — Number of objects to return positive integer

keep — Objects to retain "largest" (default) | "smallest"

I — Marker image grayscale image

conn — Pixel connectivity 8 (default) | 4 | 3-by-3 matrix of 0s and 1s

Output Arguments

BW2 — Filtered image binary image

CC2 — Filtered connected components structure

Tips

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

Version History

R2024a: Filter properties of connected components

R2024a: Measure circularity

R2022b: Generate C code using MATLAB Coder

See Also

Topics

`BW` — Image to be filtered
binary image

`CC` — Connected components to be filtered
structure

`prop` — Name of property on which to filter
character vector | string scalar

`range` — Minimum and maximum property values
2-element numeric vector

`n` — Number of objects to return
positive integer

`keep` — Objects to retain
`"largest"` (default) | `"smallest"`

`I` — Marker image
grayscale image

`conn` — Pixel connectivity
`8` (default) | `4` | 3-by-3 matrix of `0`s and `1`s

`BW2` — Filtered image
binary image

`CC2` — Filtered connected components
structure

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.