# regionprops3

Measure properties of 3-D volumetric image regions

## Syntax

## Description

measures a set of properties for each connected component (object) in the 3-D
volumetric binary image `stats`

= regionprops3(`BW`

,`properties`

)`BW`

. The output
`stats`

denote different properties for each object.

For all syntaxes, you can omit the `properties`

argument. In
this case, `regionprops3`

returns the
`"Volume"`

, `"Centroid"`

, and
`"BoundingBox"`

measurements.

measures a set of properties for each connected component (object) in
`stats`

= regionprops3(`CC`

,`properties`

)`CC`

, which is a structure returned by `bwconncomp`

.

measures a set of properties for each labeled region in the 3-D label image
`stats`

= regionprops3(`L`

,`properties`

)`L`

.

## Examples

### Estimate Centers and Radii of Objects in 3-D Volumetric Image

Create a binary image with two spheres.

[x,y,z] = meshgrid(1:50,1:50,1:50); bw1 = sqrt((x-10).^2 + (y-15).^2 + (z-35).^2) < 5; bw2 = sqrt((x-20).^2 + (y-30).^2 + (z-15).^2) < 10; bw = bw1 | bw2;

Get the centers and radii of the two spheres.

s = regionprops3(bw,"Centroid","PrincipalAxisLength"); centers = s.Centroid

`centers = `*2×3*
20 30 15
10 15 35

diameters = mean(s.PrincipalAxisLength,2)

`diameters = `*2×1*
19.9641
9.8241

radii = diameters/2

`radii = `*2×1*
9.9820
4.9120

### Get All Statistics for Cube Within a Cube

Make a 9-by-9 cube of 0s that contains a 3-by-3 cube of 1s at its center.

```
innercube = ones(3,3,3);
cube_in_cube = padarray(innercube,[3 3],0,'both');
```

Get all statistics on the cube within the cube.

`stats = regionprops3(cube_in_cube,'all')`

`stats=`*1×18 table*
Volume Centroid BoundingBox SubarrayIdx Image EquivDiameter Extent VoxelIdxList VoxelList PrincipalAxisLength Orientation EigenVectors EigenValues ConvexHull ConvexImage ConvexVolume Solidity SurfaceArea
______ ___________ ___________ ___________________________________ _______________ _____________ ______ _____________ _____________ _______________________ ___________ ____________ ____________ _____________ _______________ ____________ ________ ___________
27 5 5 2 1x6 double {[4 5 6]} {[4 5 6]} {[1 2 3]} {3x3x3 logical} 3.7221 1 {27x1 double} {27x3 double} 3.873 3.873 3.873 0 0 0 {3x3 double} {3x1 double} {24x3 double} {3x3x3 logical} 27 1 41.07

## Input Arguments

`BW`

— Volumetric binary image

3-D logical array

Volumetric binary image, specified as a 3-D logical array.

**Data Types: **`logical`

`CC`

— Connected components

structure

Connected components of a 3-D volumetric image, specified as a structure
returned by `bwconncomp`

using a 3-D
connectivity value, such as 6, 18, or 26. `CC.ImageSize`

must be a 1-by-3 vector.

**Data Types: **`struct`

`L`

— Label image

3-D numeric array | 3-D categorical array

Label image, specified as one of the following.

A 3-D numeric array. Voxels labeled

`0`

are the background. Voxels labeled`1`

make up one object; voxels labeled`2`

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

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

or`labelmatrix`

.A 3-D 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 strings or character vectors | cell array of strings or character vectors | `"all"`

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

or `"basic"`

.

If you specify

`"all"`

, then`regionprops3`

computes all the shape measurements. If you also specify a grayscale image, then`regionprops3`

returns all of the voxel value measurements.If you specify

`"basic"`

or do not specify the`properties`

argument, then`regionprops3`

computes only the`"Volume"`

,`"Centroid"`

, and`"BoundingBox"`

measurements.

The following table lists all the properties that provide shape measurements. The Voxel Value Measurements table lists additional properties that are valid only when you specify a grayscale image.

**Shape Measurements**

Property Name | Description |
---|---|

`"BoundingBox"` | Smallest cuboid containing the region, returned as a
1-by-6 vector of the form ```
[ulf_x ulf_y ulf_z
width_x width_y width_z]
``` .
`ulf_x` , `ulf_y` , and
`ulf_z` specify the upper-left front
corner of the cuboid. `width_x` ,
`width_y` , and
`width_z` specify the width of the
cuboid along each dimension. |

`"Centroid"` | Center of mass of the region, returned as a 1-by-3
vector. The three elements specify the
( |

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

`"ConvexImage"` | Image of the convex hull, returned as a volumetric binary
image with all voxels within the hull filled in (set to
`on` ). The image is the size of the
bounding box of the region. |

`"ConvexVolume"` | Number of voxels in `ConvexImage` ,
returned as a scalar. |

`"EigenValues"` | Eigenvalues of the voxels representing a region, returned
as a 3-by-1 vector. `regionprops3` uses
the eigenvalues to calculate the principal axes
lengths. |

`"EigenVectors"` | Eigenvectors of the voxels representing a region,
returned as a 3-by-3 vector.
`regionprops3` uses the eigenvectors
to calculate the orientation of the ellipsoid that has the
same normalized second central moments as the
region. |

`"EquivDiameter"` | Diameter of a sphere with the same volume as the region,
returned as a scalar. Computed as
`(6*Volume/pi)^(1/3)` . |

`"Extent"` | Ratio of voxels in the region to voxels in the total
bounding box, returned as a scalar. Computed as the value of
`Volume` divided by the volume of the
bounding box. ```
[Volume/(bounding box width *
bounding box height * bounding box
depth)]
``` |

`"Image"` | Bounding box of the region, returned as a volumetric
binary image that is the same size as the bounding box of
the region. The `on` voxels correspond to
the region, and all other voxels are
`off` . |

`"Orientation"` | Euler angles [2], returned as a 1-by-3 vector. The angles are based on
the right-hand rule. |

`"PrincipalAxisLength"` | Length (in voxels) of the major axes of the ellipsoid
that have the same normalized second central moments as the
region, returned as 1-by-3 vector.
`regionprops3` sorts the values from
highest to lowest. |

`"Solidity"` | Proportion of the voxels in the convex hull that are also
in the region, returned as a scalar. Computed as
`Volume/ConvexVolume` . |

`"SubarrayIdx"` | Indices used to extract elements inside the object
bounding box, returned as a cell array such that
`L(idx{:})` extracts the elements of
`L` inside the object bounding
box. |

`"SurfaceArea"` | Distance around the boundary of the region [1], returned as a scalar. |

`"Volume"` | Count of the actual 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` . |

`"VoxelIdxList"` | Linear indices of the voxels in the region, returned as a
p-element vector. |

`"VoxelList"` | Locations of voxels in the region, returned as a
p-by-3 matrix. Each row of the matrix
has the form `[x y z]` and specifies the
coordinates of one voxel in the region. |

The voxel value measurement properties in the following table are valid
only when you specify a grayscale volumetric image,
`V`

.

**Voxel Value Measurements**

Property Name | Description |
---|---|

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

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

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

`"VoxelValues"` | Value of the voxels in the region, returned as a
p-by-1 vector, where
p is the number of voxels in the
region. Each element in the vector contains the value of a
voxel in the region. |

`"WeightedCentroid"` | Center of the region based on location and intensity
value, returned as a -by-3
vector of coordinates. The first element of
`p` `WeightedCentroid` is the horizontal
coordinate (or x-coordinate) of the
weighted centroid. The second element is the vertical
coordinate (or y-coordinate). The third
element is the planar coordinate (or
z-coordinate). |

**Data Types: **`char`

| `string`

| `cell`

`V`

— Volumetric grayscale image

3-D numeric array

## Output Arguments

`stats`

— Measurement values

table

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

,

, or
`CC`

.NumObjects`max(`

. The variables
(columns) in each table row denote the properties calculated for each
region, as specified by `L`

(:))`properties`

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

, then
`stats`

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

.

## References

[1] Lehmann, Gaetan and David
Legland. *Efficient N-Dimensional surface estimation using Crofton formula and
run-length encoding*, The Insight Journal, 2012. https://insight-journal.org/browse/publication/852.

[2] Shoemake, Ken,
*Graphics Gems IV*. Edited by Paul S. Heckbert, Morgan
Kaufmann, 1994, pp. 222–229.

## Extended Capabilities

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

## Version History

**Introduced in R2017b**

### R2022b: Support for thread-based environments

`regionprops3`

now supports thread-based
environments.

## See Also

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