dip::MeasurementTool class

Performs measurements on images.

The MeasurementTool class knows about defined measurement features, and can apply them to an image through its dip::MeasurementTool::Measure method.

dip::MeasurementTool tool;
dip::Image img = ...
dip::Image label = Label( Threshold( img ), 2 );
dip::Measurement msr = tool.Measure( label, img, { "Size", "Perimeter" }, {}, 2 );
std::cout << "Size of object with label 1 is " << msr[ "Size" ][ 1 ][ 0 ] << '\n';

By default, the features in the following table are defined:

Measurement name Description Limitations
Size features
"Size" Number of object pixels
"CartesianBox" Cartesian box size of the object in all dimensions
"Minimum" Minimum coordinates of the object
"Maximum" Maximum coordinates of the object
"Perimeter" Length of the object perimeter 2D (CC)
"SurfaceArea" Surface area of object 3D
"Feret" Maximum and minimum object diameters 2D (CC)
"SolidArea" Area of object with any holes filled 2D (CC)
"ConvexArea" Area of the convex hull 2D (CC)
"ConvexPerimeter" Perimeter of the convex hull 2D (CC)
Shape features
"AspectRatioFeret" Feret-based aspect ratio 2D (CC)
"Radius" Statistics on radius of object 2D (CC)
"P2A" Perimeter to area ratio of the object 2D (CC) & 3D
"Roundness" Roundness of the object 2D (CC)
"Circularity" Circularity of the object 2D (CC)
"PodczeckShapes" Podczeck shape descriptors 2D (CC)
"Solidity" Area fraction of convex hull covered by object 2D (CC)
"Convexity" Ratio of perimeter of convex hull to perimeter of object 2D (CC)
"EllipseVariance" Distance to best fit ellipse 2D (CC)
"Eccentricity" Aspect ratio of best fit ellipse 2D (CC)
"BendingEnergy" Bending energy of object perimeter 2D (CC)
Intensity features
"Mass" Mass of object (sum of object intensity) Tensor grey
"Mean" Mean object intensity Tensor grey
"StandardDeviation" Standard deviation of object intensity Tensor grey
"Statistics" Mean, standard deviation, skewness and excess kurtosis of object intensity Scalar grey
"DirectionalStatistics" Directional mean and standard deviation of object intensity Scalar grey
"MaxVal" Maximum object intensity Tensor grey
"MinVal" Minimum object intensity Tensor grey
"MaxPos" Position of pixel with maximum intensity Scalar grey
"MinPos" Position of pixel with minimum intensity Scalar grey
Moments of binary object
"Center" Coordinates of the geometric mean of the object
"Mu" Elements of the inertia tensor
"Inertia" Moments of inertia of the binary object
"MajorAxes" Principal axes of the binary object
"DimensionsCube" Extent along the principal axes of a cube 2D & 3D
"DimensionsEllipsoid" Extent along the principal axes of an ellipsoid 2D & 3D
Moments of grey-value object
"Gravity" Coordinates of the center of mass of the object Scalar grey
"GreyMu" Elements of the grey-weighted inertia tensor Scalar grey
"GreyInertia" Grey-weighted moments of inertia of the object Scalar grey
"GreyMajorAxes" Grey-weighted principal axes of the object Scalar grey
"GreyDimensionsCube" Extent along the principal axes of a cube (grey-weighted) 2D & 3D, scalar grey
"GreyDimensionsEllipsoid" Extent along the principal axes of an ellipsoid (grey-weighted) 2D & 3D, scalar grey

Note that some features are derived from others, and will cause the features they depend on to be included in the output measurement object.

Some features are specific for 2D, and include “(CC)” in the limitations column above. “CC” stands for chain code. These features are computed based on the chain code of the object, and only work correctly for connected objects. That is, the object must be a single connected component. In case of the perimeter, only the external perimeter is measured, the boundaries of holes in the object are ignored.

Features that include “Scalar grey” in the limitations column require a scalar grey-value image to be passed into the dip::MeasurementTool::Measure method together with the label image. “Tensor grey” indicates that this grey-value image can be multi-valued (i.e. a tensor image); each tensor element will be reported as a channel.

See The features known by the measurement tool for more information on each of these features.

It is possible for the user to define new measurement features, and register them with the MeasurementTool through the dip::MeasurementTool::Register method. The new feature then becomes available in the dip::MeasurementTool::Measure method just like any of the default features.

Constructors, destructors, assignment and conversion operators

MeasurementTool()
Constructor.

Functions

void Register(Feature::Base* feature)
Registers a feature with this MeasurementTool.
void Configure(dip::String const& feature, dip::String const& parameter, dip::dfloat value) const
Sets a parameter of a feature registered with this MeasurementTool.
auto Measure(dip::Image const& label, dip::Image const& grey, dip::StringArray features, dip::UnsignedArray const& objectIDs = {}, dip::uint connectivity = 0) const -> dip::Measurement
Measures one or more features on one or more objects in the labeled image.
auto Features() const -> Feature::InformationArray
Returns a table with known feature names and descriptions, which can directly be shown to the user. (Note: data is copied to output array, this is not a trivial function).

Function documentation

void Register(Feature::Base* feature)

Registers a feature with this MeasurementTool.

Create an instance of the feature class on the heap using new. The feature class must be derived from one of the five classes derived from dip::Feature::Base (thus not directly from Base). The dip::MeasurementTool object takes ownership of the feature object:

class MyFeature : public dip::Feature::ChainCodeBased {
   // define constructor and override virtual functions
}
MeasurementTool measurementTool;
measurementTool.Register( new MyFeature );

See the source files for existing features for examples (and a starting point) on how to write your own feature.

dip::Measurement Measure(dip::Image const& label, dip::Image const& grey, dip::StringArray features, dip::UnsignedArray const& objectIDs = {}, dip::uint connectivity = 0) const

Measures one or more features on one or more objects in the labeled image.

label is a labeled image (any unsigned integer type, and scalar), and grey is either a raw image (not forged, without pixel data), or an real-valued image with the same dimensionality and sizes as label. If any selected features require a grey-value image, then it must be provided. Note that some features can handle multi-valued (tensor) images, and some can not.

features is an array with feature names. See the dip::MeasurementTool::Features method for information on how to obtain those names. Some features are composite features, they compute values based on other features. Thus, it is possible that the output dip::Measurement object contains features not directly requested, but needed to compute another feature.

objectIDs is an array with the IDs of objects to measure, If any of the IDs is not a label in the label image, the resulting measures will be zero or otherwise marked as invalid. If an empty array is given, all objects in the labeled image are measured. If there are no objects to be measured, a raw dip::Measurement object is returned.

connectivity should match the value used when creating the labeled image label.

The output dip::Measurement structure contains measurements that take the pixel size of the label image into account. Those of grey are ignored. Some measurements require isotropic pixel sizes, if label is not isotropic, the pixel size is ignored and these measures will return values in pixels instead.