Documentation

This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English version of the page.

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` is a table with height (number of rows) equal to the number of objects in `BW`. The variables (columns) of the table denote different properties for each region, as specified by `properties`.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`. The output `stats` is a MATLAB table with height (number of rows) equal to `CC.NumObjects`. The CC structure must represent a 3-D image, that is, `CC.ImageSize` must be a 1-by-3 vector. The CC structure must also have been created using a 3-D connectivity value, such as 6, 18, or 26. For more information, see `bwconncomp`.```
````stats = regionprops3(L,properties)` measures a set of properties for each labeled region in the 3-D label matrix `L`. Positive integer elements of `L` correspond to different regions. For example, the set of elements of `L` equal to 1 corresponds to region 1, the set of elements of `L` equal to 2 corresponds to region 2, and so on. The output `stats` is a MATLAB table with height (number of rows) equal to `max(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`. The sizes must match: `size(V)` must equal `size(BW)`, `CC.ImageSize`, or `size(L)`.```

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 diameters = mean(s.PrincipalAxisLength,2) radii = diameters/2 ```
```centers = 20 30 15 10 15 35 diameters = 17.8564 8.7869 radii = 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 = 1x18 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`

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

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. If you specify `'all'`, `regionprops3` computes all the shape measurements and, if you specified a grayscale image, all the pixel value measurements. If you specify `'basic'` or do not specify the `properties` argument, then `regionprops3` computes only the `'Volume'`, `'Centroid'`, and `'BoundingBox'` measurements. Property names are case-insensitive and can be abbreviated.

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. For more information, see References.

`'PrincipalAxesLength'`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. For more information, see References.
`'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`

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

Data Types: `struct`

Label matrix, specified as a real, nonsparse, numeric 3-D array. `regionprops3` treats negative-valued pixels as background and rounds down input pixels that are not integers. Positive integer elements of `L` correspond to different regions. For example, the set of elements of `L` equal to 1 corresponds to region `1`; the set of elements of `L` equal to 2 corresponds to region `2`; and so on.

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

Volumetric grayscale image, specified as a 3-D numeric array.

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

References

[1] Lehmann, Gaetan and David Legland, Efficient N-Dimensional surface estimation using Crofton formula and run-length encoding, http://hdl.handle.net/10380/3342

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