# 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` 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.```
````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 19.9641 9.8241 ```
`radii = diameters/2`
```radii = 2×1 9.9820 4.9120 ```

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

collapse all

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`

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 NameDescriptionCode 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 (x, y, z) coordinates of the center of mass.

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

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

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

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

 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.