bwpropfilt3

R2026b

Extract objects from 3-D binary image using properties

Since R2026b

collapse all in page

Syntax

BW3 = bwpropfilt3(BW,prop,range)

BW3 = bwpropfilt3(BW,prop,n)

BW3 = bwpropfilt3(BW,prop,n,keep)

BW3 = bwpropfilt3(BW,I,prop,___)

BW3 = bwpropfilt3(___,conn)

CC3 = bwpropfilt3(CC,prop,range)

CC3 = bwpropfilt3(CC,prop,n)

CC3 = bwpropfilt3(CC,prop,n,keep)

CC3 = bwpropfilt3(CC,I,prop,___)

Description

Objects in Binary Images

BW3 = bwpropfilt3(BW,prop,range) extracts all objects from a volumetric binary image, BW, whose value of the property prop is in the specified range. The function bwpropfilt3 returns a binary volume, BW3, containing only those objects that meet the criteria.

BW3 = bwpropfilt3(BW,prop,n) sorts the objects based on the value of the specified property prop, and returns a binary volume that contains only the top n largest objects. In the event of a tie for nth place, bwpropfilt3 keeps only the first n objects in BW3.

example

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

BW3 = bwpropfilt3(BW,I,prop,___) sorts objects based on the intensity values in the grayscale image I and the property prop, in addition to any combination of input arguments from previous syntaxes.

BW3 = bwpropfilt3(___,conn) specifies the pixel connectivity conn.

Objects in Connected Component Structures

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

CC3 = bwpropfilt3(CC,prop,n) returns the top n largest connected components. In the event of a tie for nth place, bwpropfilt3 keeps only the first n objects in CC3.

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

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

Examples

collapse all

Filter Objects by Surface Area

Open Live Script

Define dimensions for a Volume object.

imSize = [40 40 40];

Create a logical, volumetric image that contains seven spherical objects of radius r. Display the image.

numSeeds = 7;
rng(0);
seedIdx = randi(prod(imSize),numSeeds,1);
BWseeds = zeros(imSize,"logical");
BWseeds(seedIdx) = 1;
r = 7;
BW = imdilate(BWseeds,strel("sphere",r));
volshow(BW)

Find the two largest objects by surface area, and filter the image. Display the filtered image.

BW3 = bwpropfilt3(BW,"SurfaceArea",2);
volshow(BW3)

Input Arguments

collapse all

`BW` — Volumetric binary image to be filtered
logical array

Volumetric binary image to be filtered, specified as a logical array.

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 the property on which to filter, specified as one of these values.

Voxel Value Measurements

Property Name	Description	Code Generation Support
`"ConvexVolume"`	Number of voxels in the convex hull of volumetric binary image `BW`, returned as a scalar. The convex hull is the smallest convex polyhedron that can contain the region.	No
`"EquivDiameter"`	Diameter of a sphere with the same volume as the region, returned as a scalar. Calculated as `(6*Volume/pi)^(1/3)`.	Yes
`"Volume"`	Number of `on` voxels in the region, returned as a scalar. Volume represents the metric or measure of the number of voxels in the regions within the volumetric binary image `BW`.	Yes
`"SurfaceArea"`	Distance around the boundary of the region, returned as a scalar.	No
`"Extent"`	Ratio of voxels in the region to voxels in the total bounding box, returned as a scalar, calculated as the value of `Volume` divided by the volume of the bounding box.	Yes
`"Solidity"`	Proportion of the voxels in the convex hull that are also in the region, returned as a scalar, calculated as `Volume/ConvexVolume`.	No

You can specify a voxel value measurement property from the following table when you include a grayscale image, I, as an input argument to the function.

Voxel Value Measurements

Property Name	Description	Code Generation Support
`"MaxIntensity"`	Value of the voxel with the greatest intensity in the region, returned as a scalar.	Yes
`"MeanIntensity"`	Mean of all the intensity values in the region, returned as a scalar.	Yes
`"MinIntensity"`	Value of the voxel with the lowest intensity in the region, returned as a scalar.	Yes

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
`26` (default) | `6` | `18` | 3-by-3-by-3 array of `0`s and `1`s

Pixel connectivity, specified as one of these values.

Value	Meaning
`6`	Pixels are connected if their faces touch. Two adjoining pixels are part of the same object if they are both `on` and are connected in: One of these directions: in, out, left, right, up, or down	Current pixel is the center of the cube.
`18`	Pixels are connected if their faces or edges touch. Two adjoining pixels are part of the same object if they are both `on` and are connected in: One of these directions: in, out, left, right, up, and down A combination of two directions, such as right-down or in-up	Current pixel is the center of the cube.
`26`	Pixels are connected if their faces, edges, or corners touch. Two adjoining pixels are part of the same object if they are both `on` and are connected in: One of these directions: in, out, left, right, up, and down A combination of two directions, such as right-down or in-up A combination of three directions, such as in-right-up or in-left-down	Current pixel is the center of the cube.

Value

Meaning

6

Pixels are connected if their faces touch. Two adjoining pixels are part of the same object if they are both on and are connected in:

One of these directions: in, out, left, right, up, or down

Center pixel connected to the faces of six pixels

Current pixel is the center of the cube.

18

Pixels are connected if their faces or edges touch. Two adjoining pixels are part of the same object if they are both on and are connected in:

One of these directions: in, out, left, right, up, and down
A combination of two directions, such as right-down or in-up

Center pixel connected to the faces of 6 pixels and the edges of 12 pixels

Current pixel is the center of the cube.

26

Pixels are connected if their faces, edges, or corners touch. Two adjoining pixels are part of the same object if they are both on and are connected in:

One of these directions: in, out, left, right, up, and down
A combination of two directions, such as right-down or in-up
A combination of three directions, such as in-right-up or in-left-down

Center pixel connected to the faces of 6 pixels, the edges of 12 pixels, and the corners of 8 pixels

Current pixel is the center of the cube.

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

Data Types: double | logical

Output Arguments

collapse all

`BW3` — Filtered volumetric binary image
logical array

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

`CC3` — Filtered connected components
structure

Filtered connected components, returned as a structure.

Extended Capabilities

expand all

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

Usage notes and limitations:

bwpropfilt3 supports the generation of C code (requires MATLAB^® Coder™). Note that if you choose the generic MATLAB Host Computer target platform, bwpropfilt3 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.
Supports only binary images or numeric label images. Input label images of data type categorical are not supported.
Passing a cell array of properties is not supported. Use a comma-separated list instead.
All properties are supported except "ConvexVolume", "Solidity", and "SurfaceArea".

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 R2026b

bwpropfilt3

Syntax

Description

Objects in Binary Images

Objects in Connected Component Structures

Examples

Filter Objects by Surface Area

Input Arguments

BW — Volumetric binary image to be filtered logical array

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 26 (default) | 6 | 18 | 3-by-3-by-3 array of 0s and 1s

Output Arguments

BW3 — Filtered volumetric binary image logical array

CC3 — Filtered connected components structure

Extended Capabilities

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

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

Version History

See Also

`BW` — Volumetric binary image to be filtered
logical array

`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
`26` (default) | `6` | `18` | 3-by-3-by-3 array of `0`s and `1`s

`BW3` — Filtered volumetric binary image
logical array

`CC3` — Filtered connected components
structure

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

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