# regionprops3

Measure properties of 3-D volumetric image regions

## Syntax

``stats = regionprops3(BW,properties)``
``stats = regionprops3(CC,properties)``
``stats = regionprops3(L,properties)``
``stats = regionprops3(___,V,properties)``

## Description

example

````stats = regionprops3(BW,properties)` measures a set of properties for each connected component (object) in the 3-D volumetric binary image `BW`. The output `stats` denote different properties for each object.For all syntaxes, if you do not specify the `properties` argument, `regionprops3` returns the `'Volume'`, `'Centroid'`, and `'BoundingBox'` measurements.```
````stats = regionprops3(CC,properties)` measures a set of properties for each connected component (object) in `CC`, which is a structure returned by `bwconncomp`.```
````stats = regionprops3(L,properties)` measures a set of properties for each labeled region in the 3-D label image `L`.```
````stats = regionprops3(___,V,properties)` measures a set of properties for each labeled region in the 3-D volumetric grayscale image `V`. The first input (`BW`, `CC`, or `L`) identifies the regions in `V`.```

## Examples

collapse all

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 17.8564 8.7869 ```
`radii = diameters/2`
```radii = 2×1 8.9282 4.3935 ```

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] {1x3 double} {1x3 double} {1x3 double} {3x3x3 logical} 3.7221 1 {27x1 double} {27x3 double} 3.4641 3.4641 3.4641 0 0 0 {3x3 double} {3x1 double} {24x3 double} {3x3x3 logical} 27 1 41.07 ```

## Input Arguments

collapse all

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

Data Types: `logical`

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`

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`

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 NameDescription
`'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 of the form ```[centroid_x centroid_y and centroid_z]```. The first element, `centroid_x`, is the horizontal coordinate (or x-coordinate) of the center of mass. The second element, `centroid_y`, is the vertical coordinate (or y-coordinate). The third element, `centroid_z`, is the planar coordinate (or z-coordinate).

`'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 (`logical`) 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 (`logical`) 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 , returned as a 1-by-3 vector. The angles are based on the right-hand rule. `regionprops3` interprets the angles by looking at the origin along the x-, y-, and z-axis representing roll, pitch, and yaw respectively. A positive angle represents a rotation in the counterclockwise direction. Rotation operations are not commutative so they must be applied in the correct order to have the intended effect.

`'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 , 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 `p`-by-3 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). The third element is the planar coordinate (or z-coordinate).

Data Types: `char` | `string` | `cell`

Volumetric grayscale image, specified as a 3-D numeric array. The size of the image must match the size of the binary image `BW`, connected component structure `CC`, or label matrix `L`.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32`

## Output Arguments

collapse all

Measurement values, returned as a table. The number of rows in the table corresponds to the number of objects in `BW`, `CC.NumObjects`, or `max(L(:))`. The variables (columns) in each table 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 variable with the property `'LabelName'`.

 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)

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