Measure properties of image regions

returns
measurements for the set of properties specified by `stats`

= regionprops(`BW`

,`properties`

)`properties`

for
each connected component (object) in the binary image, `BW`

. `stats`

is
struct array containing a struct for each object in the image. You
can use `regionprops`

on contiguous regions and discontiguous
regions (see Algorithms).

returns
measurements for the set of properties specified by `stats`

= regionprops(`CC`

,`properties`

)`properties`

for
each connected component (object) in `CC`

. `CC`

is
a structure returned by `bwconncomp`

.

returns
measurements for the set of properties specified by `stats`

= regionprops(`L`

,`properties`

)`properties`

for
each labeled region in the label matrix `L`

.

returns
measurements for the set of properties specified by `stats`

= regionprops(___,`I`

,`properties`

)`properties`

for
each labeled region in the image `I`

. The first input
to `regionprops`

(`BW`

, `CC`

,
or `L`

) identifies the regions in `I`

.
The size of the first input must match the size of the image, that
is, `size(I)`

must equal `size(BW)`

, `CC.ImageSize`

,
or `size(L)`

.

performs
the measurements on a GPU. `stats`

= regionprops(`gpuarrayImg`

,___)`gpuarrayImg`

can be
a 2-D binary image (`logical`

gpuArray) or a gpuArray
label matrix. The connected component structure (`CC`

)
returned by `bwconncomp`

is not supported on the
GPU.

When run on a GPU, `regionprops`

does not support
the following properties: `'ConvexArea'`

, `'ConvexHull'`

, `'ConvexImage'`

, `'EulerNumber'`

, `'FilledArea'`

, `'FilledImage'`

,
and`'Solidity'`

.

Code Generation support: Yes.

MATLAB^{®} Function Block support: No.

Read binary image into workspace.

```
BW = imread('text.png');
```

Calculate centroids for connected components in the image using `regionprops`

.

```
s = regionprops(BW,'centroid');
```

Concatenate structure array containing centroids into a single matrix.

centroids = cat(1, s.Centroid);

Display binary image with centroid locations superimposed.

imshow(BW) hold on plot(centroids(:,1),centroids(:,2), 'b*') hold off

Read binary image into a gpuArray.

```
BW = gpuArray(imread('text.png'));
```

Calculate the centroids of objects in the image.

```
s = regionprops(BW,'centroid');
```

Plot the centroids on the image.

centroids = cat(1, s.Centroid); imshow(BW) hold on plot(centroids(:,1), centroids(:,2), 'b*') hold off

Estimate the center and radii of circular objects in an image and use this information to plot circles on the image. In this example, `regionprops`

returns the information it calculates in a table.

Read an image into workspace.

```
a = imread('circlesBrightDark.png');
```

Turn the input image into a binary image.

```
bw = a < 100;
imshow(bw)
title('Image with Circles')
```

Calculate properties of regions in the image and return the data in a table.

stats = regionprops('table',bw,'Centroid',... 'MajorAxisLength','MinorAxisLength')

stats = Centroid MajorAxisLength MinorAxisLength ________________ _______________ _______________ 256.5 256.5 834.46 834.46 300 120 81.759 81.759 330.47 369.83 111.78 110.36 450 240 101.72 101.72

Get centers and radii of the circles.

centers = stats.Centroid; diameters = mean([stats.MajorAxisLength stats.MinorAxisLength],2); radii = diameters/2;

Plot the circles.

hold on viscircles(centers,radii); hold off

`BW`

— Input binary imagelogical array of any dimensionInput binary image, specified as a logical array of any dimension.

**Example: **`BW = imread('text.png'); s = regionprops(BW,'basic');`

**Data Types: **`logical`

`properties`

— Type of measurementstring | comma-separated list of strings | cell array of strings | `'all'`

| `'basic'`

Type of measurement, specified as a string, comma-separated
list of strings, cell array of strings, or the string `'all'`

or `'basic'`

.
Property name strings are case-insensitive and can be abbreviated.
When used with code generation, `regionprops`

does
not support cell arrays of strings.

The following tables list all the properties that provide shape
measurements. The properties listed in the Pixel Value Measurements table are only valid when you specify
a grayscale image. If you specify `'all'`

, `regionprops`

computes
all the shape measurements and, if you specified a grayscale image,
the pixel value measurements. If you specify the string `'basic'`

,
or do not specify the `properties`

argument, `regionprops`

computes
only the `'Area'`

, `'Centroid'`

,
and `'BoundingBox'`

measurements. You can calculate
the following properties on N-D inputs: `'Area'`

, `'BoundingBox'`

, `'Centroid'`

, `'FilledArea'`

, `'FilledImage'`

, `'Image'`

, `'PixelIdxList'`

, `'PixelList'`

,
and `'SubarrayIdx'`

.

**Shape Measurements**

Property Name String | Description | N-D Support | GPU Support | Code Generation |
---|---|---|---|---|

`'Area'` | Returns a scalar that specifies the actual number of pixels
in the region. (This value might differ slightly from the value returned
by `bwarea` , which weights different patterns of
pixels differently.) | Yes | Yes | Yes |

`'BoundingBox'` | Returns the smallest rectangle containing the region, specified
as a 1-by-`Q*2` vector, where `Q` is
the number of image dimensions, for example, `[ul_corner width]` . `ul_corner` specifies
the upper-left corner of the bounding box in the form ```
[x
y z ...]
``` . `width` specifies the width
of the bounding box along each dimension in the form ```
[x_width
y_width ...]
``` . `regionprops` uses `ndims` to
get the dimensions of label matrix or binary image, `ndims(L)` ,
and `numel` to get the dimensions of connected components, `numel(CC.ImageSize)` . | Yes | Yes | Yes |

`'Centroid'` | Returns a 1-by- vector
that specifies the center of mass of the region. The first element
of `Centroid` is the horizontal coordinate (or x-coordinate)
of the center of mass, and the second element is the vertical coordinate
(or y-coordinate). All other elements of `Centroid` are
in order of dimension. This figure illustrates the centroid and bounding
box for a discontiguous region. The region consists of the white pixels;
the green box is the bounding box, and the red dot is the centroid.
| Yes | Yes | Yes |

`'ConvexArea'` | Returns a scalar that specifies the number of pixels in `'ConvexImage'` . | 2-D only | No | No |

`'ConvexHull'` | Returns a p-by-2 matrix that specifies the
smallest convex polygon that can contain the region. Each row of the
matrix contains the x- and y-coordinates
of one vertex of the polygon. | 2-D only | No | No |

`'ConvexImage'` | Returns a binary image (`logical` ) that specifies
the convex hull, with all pixels within the hull filled in (set to `on` ).
The image is the size of the bounding box of the region. (For pixels
that the boundary of the hull passes through, `regionprops` uses
the same logic as `roipoly` to determine whether
the pixel is inside or outside the hull.) | 2-D only | No | No |

`'Eccentricity'` | Returns a scalar that specifies the 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. The value is between 0 and 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.) | 2-D only | Yes | Yes |

`'EquivDiameter'` | Returns a scalar that specifies the diameter of a circle with
the same area as the region. Computed as `sqrt(4*Area/pi)` . | 2-D only | Yes | Yes |

`'EulerNumber'` | Returns a scalar that specifies the number of objects in the
region minus the number of holes in those objects. This property is
supported only for 2-D label matrices. `regionprops` uses
8-connectivity to compute the Euler number measurement. To learn more
about connectivity, see Pixel Connectivity. | Yes | No | Yes |

`'Extent'` | Returns a scalar that specifies the ratio of pixels in the
region to pixels in the total bounding box. Computed as the `Area` divided
by the area of the bounding box. | 2-D only | Yes | Yes |

`'Extrema'` | Returns an 8-by-2 matrix that specifies the extrema points
in the region. Each row of the matrix contains the x-
and y-coordinates of one of the points. The format
of the vector is ```
[top-left top-right right-top right-bottom
bottom-right bottom-left left-bottom left-top]
``` . This figure
illustrates the extrema of two different regions. In the region on
the left, each extrema point is distinct. In the region on the right,
certain extrema points (e.g., `top-left` and `left-top` )
are identical.
| 2-D only | Yes | Yes |

`'FilledArea'` | Returns a scalar that specifies the number of `on` pixels
in `FilledImage` . | Yes | No | Yes |

`'FilledImage'` | Returns a binary image (`logical` ) of the
same size as the bounding box of the region. The `on` pixels
correspond to the region, with all holes filled in, as shown in this
figure.
| Yes | No | Yes |

`'Image'` | Returns a binary image (`logical` ) of the
same size as the bounding box of the region. The `on` pixels
correspond to the region, and all other pixels are `off` . | Yes | Yes | Yes |

`'MajorAxisLength'` | Returns a scalar that specifies the length (in pixels) of the major axis of the ellipse that has the same normalized second central moments as the region. | 2-D only | Yes | Yes |

`'MinorAxisLength'` | Returns a scalar that specifies the length (in pixels) of the minor axis of the ellipse that has the same normalized second central moments as the region. | 2-D only | Yes | Yes |

`'Orientation'` | Returns a scalar that specifies the angle between the x-axis
and the major axis of the ellipse that has the same second-moments
as the region. The value is in degrees, ranging from -90 to 90 degrees.
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, and the orientation
is the angle between the horizontal dotted line and the major axis.
| 2-D only | Yes | Yes |

`'Perimeter'` | Returns a scalar that specifies the distance around the boundary
of the region. `regionprops` computes the perimeter
by calculating the distance between each adjoining pair of pixels
around the border of the region. If the image contains discontiguous
regions, `regionprops` returns unexpected results.
This figure illustrates the pixels included in the perimeter calculation
for this object.
| 2-D only | Yes | v |

`'PixelIdxList'` | Returns a p-element vector that contains
the linear indices of the pixels in the region. | Yes | Yes | Yes |

`'PixelList'` | Returns a p-by-`Q` matrix
that specifies the locations of pixels in the region. Each row of
the matrix has the form `[x y z ...]` and specifies
the coordinates of one pixel in the region. | Yes | Yes | Yes |

`'Solidity'` | Returns a scalar specifying the proportion of the pixels in
the convex hull that are also in the region. Computed as `Area/ConvexArea` . | 2-D only | No | No |

`'SubarrayIdx'` | Returns a cell array that contains indices such that `L(idx{:})` extracts
the elements of `L` inside the object bounding box. | Yes | Yes | No |

The pixel value measurement properties in the following table
are valid only when you specify a grayscale image, `I`

.

**Pixel Value Measurements**

Property Name String | Description | N-D Support | GPU Support | Code Generation |
---|---|---|---|---|

`'MaxIntensity'` | Returns a scalar that specifies the value of the pixel with the greatest intensity in the region. | No | Yes | Yes |

`'MeanIntensity'` | Returns a scalar that specifies the mean of all the intensity values in the region. | No | Yes | Yes |

`'MinIntensity'` | Returns a scalar that specifies the value of the pixel with the lowest intensity in the region. | No | Yes | Yes |

`'PixelValues'` | Returns a p-by-1 vector, where p is
the number of pixels in the region. Each element in the vector contains
the value of a pixel in the region. | No | Yes | Yes |

`'WeightedCentroid'` | Returns a -by-`p` `Q` vector
of coordinates specifying the center of the region based on location
and intensity value. The first element of `WeightedCentroid` is
the horizontal coordinate (or x-coordinate) of
the weighted centroid. The second element is the vertical coordinate
(or y-coordinate). All other elements of `WeightedCentroid` are
in order of dimension. | No | Yes | Yes |

**Data Types: **`char`

`CC`

— Connected componentsstructureConnected components, specified as a structure returned by `bwconncomp`

.

**Example: **```
BW = imread('text.png'); CC = bwconncomp(BW);
s = regionprops(CC,'basic');
```

**Data Types: **`struct`

`L`

— Labeled regionslabel matrixLabeled regions, specified as a label matrix. `L`

can
have any numeric class and any dimension. `regionprops`

treats
negative-valued pixels as background and rounds down input pixels
that are not integers. Positive integer elements of `L`

correspond
to different regions. For example, the set of elements of `L`

equal
to 1 corresponds to region `1`

; the set of elements
of `L`

equal to 2 corresponds to region `2`

;
and so on.

**Example: **```
BW = imread('text.png'); L = bwlabel(BW);
s = regionprops(L,'basic');
```

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `uint8`

| `uint16`

| `uint32`

`I`

— Image to be measuredgrayscale imageImage to be measured, specified as a grayscale image.

**Example: **`I = imread('cameraman.tif'); s = regionprops(L,I,'basic');`

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

`output`

— Return type`'struct'`

(default) | `'table'`

Return type, specified as either of these strings.

String | Description |
---|---|

`'struct'` | Returns an array of structures with length equal to the number
of objects in `BW` , `CC.NumObjects` ,
or `max(L(:))` . The fields of the structure array
denote different properties for each region, as specified by `properties` .
If you do not specify this argument, `regionprops` returns
a struct by default. |

`'table'` | Returns a MATLAB table with height (number of rows) equal to
the number of objects in `BW` , `CC.NumObjects` ,
or `max(L(:))` . The variables (columns) denote different
properties for each region, as specified by `properties` .
To learn more about MATLAB tables, see `table` . Not supported on a GPU. |

**Example: **`s = regionprops('table',BW,'basic');`

**Data Types: **`char`

`gpuarrayImg`

— Input image2D `logical gpuArray`

| label matrix `gpuArray`

Input image, specified as a 2-D `logical gpuArray`

or
label matrix gpuArray.

**Example: **```
gpuarrayBW = gpuArray(imread('text.png'));
s = regionprops(gpuarrayBW,'basic');
```

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `uint8`

| `uint16`

| `uint32`

`stats`

— Measurement values`struct`

array (default) | `table`

Measurement values, returned as an array of structs or a table.
The number of structs in the array, or the number of rows in the table,
corresponds to the number of objects in `BW`

, `CC.NumObjects`

,
or `max(L(:))`

. The fields of each struct, or the
variables in each row, denote the properties calculated for each region,
as specified by `properties`

.

When run on a GPU, `regionprops`

can only return
struct arrays.

This function supports the generation of C code using MATLAB Coder™.
Note that if you choose the generic `MATLAB Host Computer`

target
platform, the function 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 Understanding Code Generation with Image Processing Toolbox.

When generating code, `regionprops`

has the
following limitations.

Supports only 2-D input images or label matrices.

Specifying the output type

`'table'`

is not supported.Passing a cell array of properties is not supported. Use a comma-separated list instead.

All properties are supported except

`‘ConvexArea'`

,`‘ConvexHull'`

,`'ConvexImage'`

,`'Solidity'`

, and`'SubarrayIdx'`

.

The function

`ismember`

is useful in conjunction with`regionprops`

,`bwconncomp`

, and`labelmatrix`

for creating a binary image containing only objects or regions that meet certain criteria. For example, these commands create a binary image containing only the regions whose area is greater than 80 and whose eccentricity is less than 0.8.cc = bwconncomp(BW); stats = regionprops(cc, 'Area','Eccentricity'); idx = find([stats.Area] > 80 & [stats.Eccentricity] < 0.8); BW2 = ismember(labelmatrix(cc), idx);

The comma-separated list syntax for structure arrays is very useful when you work with the output of

`regionprops`

. For example, for a field that contains a scalar, you can use this syntax to create a vector containing the value of this field for each region in the image. For instance, if`stats`

is a structure array with field`Area`

, then the following expression:stats(1).Area, stats(2).Area, ..., stats(end).Area

is equivalent to:

stats.Area

Therefore, you can use these calls to create a vector containing the area of each region in the image.

`allArea`

is a vector of the same length as the structure array`stats`

.stats = regionprops(L, 'Area'); allArea = [stats.Area];

The functions

`bwlabel`

,`bwlabeln`

, and`bwconncomp`

all compute connected components for binary images.`bwconncomp`

replaces the use of`bwlabel`

and`bwlabeln`

. It uses significantly less memory and is sometimes faster than the other functions.Function Input Dimension Output Form Memory Use Connectivity `bwlabel`

2-D Label matrix with double-precision High 4 or 8 `bwlabeln`

N-D Double-precision label matrix High Any `bwconncomp`

N-D `CC`

structLow Any The output of

`bwlabel`

and`bwlabeln`

is a double-precision label matrix. To compute a label matrix using a more memory-efficient data type, use the`labelmatrix`

function on the output of`bwconncomp`

:CC = bwconncomp(BW); L = labelmatrix(CC);

If you are measuring components in a binary image with default connectivity, it is no longer necessary to call

`bwlabel`

or`bwlabeln`

first. You can pass the binary image directly to`regionprops`

, which then uses the memory-efficient`bwconncomp`

function to compute the connected components automatically. If you need to specify nondefault connectivity, call`bwconncomp`

and then pass the result to`regionprops`

.CC = bwconncomp(BW, CONN); S = regionprops(CC);

Most of the measurements take very little time to compute. However, these measurements can take significantly longer, depending on the number of regions in

`L`

:`'ConvexHull'`

`'ConvexImage'`

`'ConvexArea'`

`'FilledImage'`

Computing certain groups of measurements takes about the same amount of time as computing just one of them because

`regionprops`

takes advantage of intermediate computations used in both computations. Therefore, it is fastest to compute all the desired measurements in a single call to`regionprops`

.

Contiguous regions are also called "objects," "connected components," or "blobs." A label matrix containing contiguous regions might look like this:

1 1 0 2 2 0 3 3 1 1 0 2 2 0 3 3

`L`

equal
to 1 belong to the first contiguous region or connected component;
elements of `L`

equal to 2 belong to the second connected
component; and so on.Discontiguous regions are regions that might contain multiple connected components. A label matrix containing discontiguous regions might look like this:

1 1 0 1 1 0 2 2 1 1 0 1 1 0 2 2

`L`

equal
to 1 belong to the first region, which is discontiguous and contains
two connected components. Elements of `L`

equal to
2 belong to the second region, which is a single connected component. `bwconncomp`

| `bwlabel`

| `bwlabeln`

| `ismember`

| `labelmatrix`

| `watershed`

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Was this topic helpful?

You can also select a location from the following list:

- Canada (English)
- United States (English)

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)