bwpropfilt

R2026b

Extract objects from 2-D binary image using properties

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

The bwpropfilt function extracts objects from a 2-D binary image using properties.

Note

To extract objects from a 3-D volumetric image, use bwpropfilt3 instead.

Objects in Binary Images

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

BW2 = bwpropfilt(BW,prop,n) sorts the objects based on the value of the specified property, prop, returning a 2-D 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.

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.

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

Find Regions Without Holes

Read image and display it.

BW = imread('text.png');
figure
imshow(BW)
title('Original 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')

Find Which Ten Objects Have Largest Perimeters

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')

Filter on Multiple Image Properties

Read and display an image.

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

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))

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

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

Identify Polished Coins in Image

Load an image of coins into the workspace and visualize it.

I = imread("coins.png");
imageshow(I)

Threshold the image to obtain a mask of the coins in the image.

BW = imbinarize(I);
imageshow(BW)

To identify the polished coins, identify those regions which have the highest mean intensity.

BW2 = bwpropfilt(BW,I,"MeanIntensity",2);
imageshow(BW2)

Input Arguments

BW — Binary image to be filtered

logical matrix

Binary image to be filtered, specified as a logical matrix.

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: (4*pi*Area/Perimeter^2)*(1 - 0.5/r)^2 where r = Perimeter/(2*pi) + 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.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

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.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

conn — Pixel connectivity

8 (default) | 4 | 3-by-3 matrix of 0s and 1s

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.

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

BW2 — Filtered binary image

logical matrix

Filtered binary image, returned as a logical matrix 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

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

Version History

Introduced in R2014b

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).