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

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.

stats = regionprops3(L,properties) measures a set of properties for each labeled region in the 3-D label matrix 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

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

   17.8564
    8.7869

radii = diameters/2

radii = 2×1

    8.9282
    4.3935

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]    [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

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, specified as a structure returned by bwconncomp. 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.

Data Types: struct

L — Label matrix

3-D numeric array

Label matrix, specified as a 3-D numeric 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

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'. Property names are case-insensitive and can be abbreviated.

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

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

V — Volumetric grayscale image

3-D numeric array

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

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, 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, https://hdl.handle.net/10380/3342

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