# regionprops

Measure properties of image regions

## Syntax

## Description

The `regionprops`

function measures properties such as area,
centroid, and bounding box, for each object (connected component) in an image.
`regionprops`

supports both contiguous regions
and discontiguous regions.

**Note**

To measure properties of objects in a 3-D volumetric image, consider using `regionprops3`

instead. Although `regionprops`

can accept 3-D images,
`regionprops3`

supports more statistics for 3-D images.

When you call the `regionprops`

function, you can omit the
`properties`

argument, in which case the function returns the
`"Area"`

, `"Centroid"`

, and
`"BoundingBox"`

measurements.

measures properties for each object in the binary image `stats`

= regionprops(`BW`

,`properties`

)`BW`

.

`regionprops`

finds unique objects in binary images using 8-connected
neighborhoods for 2-D images and maximal connectivity for higher dimension images. For more
information, see Pixel Connectivity. To find objects using other
types of connectivity, use `bwconncomp`

to create the connected
components, and then pass the result to `regionprops`

using the
`CC`

argument instead.

measures properties for each connected component in `stats`

= regionprops(`CC`

,`properties`

)`CC`

, which is a
structure returned by `bwconncomp`

.

measures properties for each labeled region in label image `stats`

= regionprops(`L`

,`properties`

)`L`

.

also specifies the format of the returned measurements as an array of structures or a table,
using the `stats`

= regionprops(`outputFormat`

,___)`outputFormat`

argument.

## Examples

### Calculate Centroids and Superimpose Locations on Image

Read a binary image into workspace.

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

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

. The `regionprops`

function returns the centroids in a structure array.

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

Store the *x*- and *y*-coordinates of the centroids into a two-column matrix.

centroids = cat(1,s.Centroid);

Display the binary image with the centroid locations superimposed.

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

### Estimate Center and Radii of Circular Objects and Plot Circles

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 measured region properties in a table.

Read an image into workspace.

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

Turn the input image into a binary image.

```
bw = a < 50;
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=`*3×3 table*
Centroid MajorAxisLength MinorAxisLength
________________ _______________ _______________
300 120 79.517 79.517
330.29 369.92 109.49 108.6
450 240 99.465 99.465

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

ans = Group with properties: Children: [2x1 Line] Visible: on HitTest: on Show all properties

`hold off`

## Input Arguments

`BW`

— Binary image

logical array

Binary image, specified as a logical array of any dimension.

**Data Types: **`logical`

`CC`

— Connected components

structure

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

.

**Data Types: **`struct`

`L`

— Label image

numeric array | categorical array

Label image, specified as one of the following.

A numeric array of any dimension. Pixels labeled

`0`

are the background. Pixels labeled`1`

make up one object; pixels labeled`2`

make up a second object; and so on.`regionprops`

treats negative-valued pixels as background and rounds down input pixels that are not integers. You can get a numeric label image from labeling functions such as`watershed`

or`labelmatrix`

.A categorical array. Each category corresponds to a different region.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `uint8`

| `uint16`

| `uint32`

| `categorical`

`properties`

— Type of measurement

`"basic"`

(default) | comma-separated list of string scalars or character vectors | array of string scalars | cell array of character vectors | `"all"`

Type of measurement, specified as a comma-separated list of string scalars or character
vectors, an array of string scalars, a cell array of character vectors, or as
`"all"`

or `"basic"`

.

If you specify

`"all"`

, then`regionprops`

computes all the shape measurements and, for grayscale images, the pixel value measurements as well.If you specify

`"basic"`

, then`regionprops`

computes only the`"Area"`

,`"Centroid"`

, and`"BoundingBox"`

measurements.

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

**Shape Measurements**

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

`"Area"` | Actual number of pixels in the region, returned as a scalar. This value might differ
slightly from the value returned by To find the equivalent
to the area of a 3-D volume, use the | Yes | Yes | Yes | ||||||||

`"BoundingBox"` | Position and size of the smallest box containing the region, returned as a
1-by-(2* | Yes | Yes | Yes | ||||||||

`"Centroid"` | Center of mass of the region, returned as a 1-by- 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 | ||||||||

`"Circularity"` | Roundness of objects, returned as a structure with field
The maximum circularity value is 1. The input
must be a label matrix or binary image with contiguous regions. If the image
contains discontiguous regions, | 2-D only | No | Yes | ||||||||

`"ConvexArea"` | Number of pixels in `ConvexImage` , returned as a scalar. | 2-D only | No | No | ||||||||

`"ConvexHull"` | Smallest convex polygon that can contain the region, returned as a p-by-2
matrix. Each row of the matrix contains the x- and
y-coordinates of one vertex of the polygon. | 2-D only | No | No | ||||||||

`"ConvexImage"` | Image that specifies the convex hull, with all pixels within the hull filled in (set to
`on` ), returned as a binary image. 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 algorithm described by Classify Pixels That Are Partially Enclosed by ROI. | 2-D only | No | No | ||||||||

`"Eccentricity"` | Eccentricity of the ellipse that has the same second-moments as the region, returned as a scalar. 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"` | Diameter of a circle with the same area as the region, returned as a scalar. Computed as
`sqrt(4*Area/pi)` . | 2-D only | Yes | Yes | ||||||||

`"EulerNumber"` | Number of objects in the region minus the number of holes in those objects, returned as a
scalar. This property is supported only for 2-D label matrices.
`regionprops` uses 8-connectivity to compute the Euler
number (also known as the Euler characteristic). To learn more about
connectivity, see Pixel Connectivity. | 2-D only | No | Yes | ||||||||

`"Extent"` | Ratio of pixels in the region to pixels in the total bounding box, returned as a scalar.
Computed as the `Area` divided by the area of the bounding
box. | 2-D only | Yes | Yes | ||||||||

`"Extrema"` | Extrema points in the region, returned as an 8-by-2 matrix. Each row of the matrix
contains the This figure illustrates the extrema of two
different regions. In the region on the left, each extrema point is distinct.
For the region on the right, certain extrema points (such as
| 2-D only | Yes | Yes | ||||||||

`"FilledArea"` | Number of `on` pixels in `FilledImage` , returned as a
scalar. | Yes | No | Yes | ||||||||

`"FilledImage"` | Image the same size as the bounding box of the region, returned as a binary array. The
| Yes | No | Yes | ||||||||

`"Image"` | Image the same size as the bounding box of the region, returned as a binary array. The
`on` pixels correspond to the region, and all other pixels
are `off` . | Yes | Yes | Yes | ||||||||

`"MajorAxisLength"` | Length (in pixels) of the major axis of the ellipse that has the same normalized second central moments as the region, returned as a scalar. | 2-D only | Yes | Yes | ||||||||

`"MaxFeretProperties"` | Feret properties that include maximum Feret diameter, its relative angle, and coordinate values, returned as a structure with fields:
The input can be a binary image, connected component, or a label matrix. | 2-D only | No | No | ||||||||

`"MinFeretProperties"` | Feret properties that include minimum Feret diameter, its relative angle, and coordinate values, returned as a structure with fields:
The input can be a binary image, a connected component, or a label matrix. | 2-D only | No | No | ||||||||

`"MinorAxisLength"` | Length (in pixels) of the minor axis of the ellipse that has the same normalized second central moments as the region, returned as a scalar. | 2-D only | Yes | Yes | ||||||||

`"Orientation"` | Angle between the
| 2-D only | Yes | Yes | ||||||||

`"Perimeter"` | Distance around the boundary of the region returned as a scalar.
| 2-D only | No | Yes | ||||||||

`"PixelIdxList"` | Linear indices of the pixels in the region, returned as a p-element
vector. | Yes | Yes | Yes | ||||||||

`"PixelList"` | Locations of pixels in the region, returned as a p-by-`Q`
matrix. 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"` | Proportion of the pixels in the convex hull that are also in the region, returned as a
scalar. The solidity is calculated as
| 2-D only | No | No | ||||||||

`"SubarrayIdx"` | Elements of `L` inside the object bounding box, returned as a cell array
that contains indices such that `L(idx{:})` extracts the
elements. | 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 | Description | N-D Support | GPU Support | Code Generation |
---|---|---|---|---|

`"MaxIntensity"` | Value of the pixel with the greatest intensity in the region, returned as a scalar. | Yes | Yes | Yes |

`"MeanIntensity"` | Mean of all the intensity values in the region, returned as a scalar. | Yes | Yes | Yes |

`"MinIntensity"` | Value of the pixel with the lowest intensity in the region, returned as a scalar. | Yes | Yes | Yes |

`"PixelValues"` | Number of pixels in the region, returned as 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. | Yes | Yes | Yes |

`"WeightedCentroid"` | Center of the region based on location and intensity value, returned as a
p-by-`Q` vector of coordinates. 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. | Yes | Yes | Yes |

**Data Types: **`char`

| `string`

| `cell`

`outputFormat`

— Output format

`"struct"`

(default) | `"table"`

Output format of the measurement values `stats`

, specified as
either of the following values.

Value | Description |
---|---|

`"struct"` | Returns an array of structures with length equal to the number of objects
in `BW` ,
, or
`max(` . The fields of the
structure array denote different properties for each region, as specified by
`properties` . |

`"table"` | Returns a |

**Data Types: **`char`

| `string`

## Output Arguments

`stats`

— Measurement values

`struct`

array (default) | table

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

, `CC.NumObjects`

, or
`max(L(:))`

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

. If the input image is a categorical label image
`L`

, then `stats`

includes an additional field
or variable with the property `"LabelName"`

.

## More About

### Contiguous Regions and Discontiguous Regions

Contiguous regions are also called *objects*,
*connected components*, or *blobs*. A label
image `L`

containing contiguous regions might look like
this:

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

Elements of `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 can contain multiple connected components. A label image 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. ## Tips

The

`ismember`

function is useful 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);

`regionprops`

takes advantage of intermediate results when computing related measurements. Therefore, it is fastest to compute all the desired measurements in a single call to`regionprops`

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

`L`

:`"ConvexHull"`

`"ConvexImage"`

`"ConvexArea"`

`"FilledImage"`

## Extended Capabilities

### C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

`regionprops`

supports the generation of C code (requires MATLAB^{®}Coder™). Note that if you choose the generic`MATLAB Host Computer`

target platform,`regionprops`

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.

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"`

,`"MaxFeretProperties"`

,`"MinFeretProperties"`

,`"Solidity"`

, and`"SubarrayIdx"`

.

### GPU Code Generation

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

Usage notes and limitations:

GPU Coder™ generates optimized CUDA

^{®}code for only binary images. Code generated for input label images is not optimized. Input label images of data type categorical are not supported.Specifying the output type

`"table"`

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

Only

`"Area"`

,`"BoundingBox"`

,`"Centroid"`

,`"Eccentricity"`

,`"EquivDiameter"`

,`"Extent"`

,`"MajorAxisLength"`

,`"MinorAxisLength"`

,`"Orientation"`

,`"PixelIdxList"`

`"PixelList"`

,`"MaxIntensity"`

,`"MeanIntensity"`

,`"MinIntensity"`

,`"PixelValues"`

, and`"WeightedCentroid"`

properties are supported.

### Thread-Based Environment

Run code in the background using MATLAB® `backgroundPool`

or accelerate code with Parallel Computing Toolbox™ `ThreadPool`

.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

### GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Usage notes and limitations:

`gpuArray`

input must be a 2-D logical matrix or a 2-D label matrix.The connected component structure (

`CC`

) input is not supported.The following properties are not supported:

`"ConvexArea"`

,`"ConvexHull"`

,`"ConvexImage"`

,`"Circularity"`

,`"EulerNumber"`

,`"FilledArea"`

,`"FilledImage"`

,`"MaxFeretProperties"`

,`"MinFeretProperties"`

, and`"Solidity"`

.`"struct"`

is the only return type supported.

For more information, see Image Processing on a GPU.

## Version History

**Introduced before R2006a**

### R2023a: New circularity equation

The `regionprops`

function uses a new equation to calculate
circularity. The new equation removes a bias that caused the computed circularity to be too
high for relatively small objects.

If you wants to reproduce circularity measurements using the old equation, then you can use these commands:

props = regionprops(I,["Area" "Perimeter"]); oldCircularity = 4*pi*props.Area ./ props.Perimeter.^2;

### R2022b: Support for thread-based environments

`regionprops`

now supports thread-based
environments.

### R2022a: `regionprops`

stores the `Image`

, `ConvexImage`

, and `FilledImage`

properties as cell
arrays in the output table for all inputs

Starting in R2022a, when a table output format is specified, the
`regionprops`

function stores the `Image`

,
`ConvexImage`

, and `FilledImage`

property values as cell
arrays, regardless of the size of the image objects. In previous releases, if the size of
the bounding box of an object was 1-by-1 or 1-by-*n*, these properties
were stored in the output table as a numeric scalar or row vector.

To update your code, access the value of the `Image`

,
`ConvexImage`

, and `FilledImage`

properties by using dot
notation with curly braces, `{}`

. For example, use the below code to access
the `Image`

property for the first object in the input image
`BW`

. In previous releases, curly braces were not required to access
values stored as a numeric scalar or row vector.

stats = regionprops("table",BW,"Image"); imdata = stats.Image{1};

### R2020a: Support for categorical data

`regionprops`

now supports
categorical image data.

### R2019a: New circularity and Feret properties

`regionprops`

now measures the circularity and Feret properties of
regions in a binary image. To measure the circularity, minimum Feret properties, or maximum
Feret properties, include `"Circularity"`

,
`"MinFeretProperties"`

, or `"MaxFeretProperties"`

,
respectively, when specifying the `properties`

argument.

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

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.

# Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

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