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

denotes different properties for each object.

`regionprops3`

finds unique objects in volumetric binary images
using 26-connected neighborhoods. For more information, see Pixel Connectivity. To find objects
using other types of connectivity, instead use `bwconncomp`

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

using the
`CC`

argument.

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.

`regionprops3`

sorts the objects in the volumetric
binary image from left to right based on the `top-left`

extremum of each component. When multiple objects have the same horizontal
position, the function then sorts those objects from top to bottom, and
again along the third dimension. `regionprop3`

returns
the measured properties, `stats`

, in the same order as
the sorted objects.

**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 | Code Generation |
---|---|---|

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

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

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

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

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

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

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

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

`"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)]
``` | Yes |

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

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

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

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

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

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

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

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

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

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 | Code Generation |
---|---|---|

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

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

`"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). | Yes |

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

.

The order of the measurement values in `stats`

is the
same as the sorted objects in binary image `BW`

, or the
ordered objects specified by `CC`

or
`L`

.

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

### C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™. (since R2023a)

Usage notes and limitations:

`regionprops3`

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

target platform,`regionprops3`

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

,`"ConvexHull"`

,`"ConvexImage"`

,`"Solidity"`

, and`"SurfaceArea"`

.

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

### R2023a: Support for C code generation

`regionprops3`

now supports the generation of
C code (requires MATLAB
Coder).

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