MeasurementTool class
Performs measurements on images.
Contents
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 | |
"SolidArea" |
Area of object with any holes filled | 2D (CC) |
"Perimeter" |
Length of the object perimeter | 2D (CC) |
"SurfaceArea" |
Surface area of object | 3D |
"Minimum" |
Minimum coordinates of the object | |
"Maximum" |
Maximum coordinates of the object | |
"CartesianBox" |
Cartesian box size of the object in all dimensions | |
"Feret" |
Maximum and minimum object diameters | 2D (CC) |
"Radius" |
Statistics on radius of object | 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) |
"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(dip::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 -> dip::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(dip::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.