Measurement module

The measurement infrastructure and functionality.

Contents

The dip::MeasurementTool class provides the main interface to the functionality in this module. Quantification results are encapsulated in an object of the dip::Measurement class.

Namespaces

namespace dip::Feature
Contains classes that implement the measurement features. more...

Classes

template<typename T>
struct dip::BoundingBox
Encodes a bounding box in a 2D image by the top left and bottom right corners (both coordinates included in the box). more...
struct dip::ChainCode
The contour of an object as a chain code sequence. more...
struct dip::CircleParameters
Represents a circle, returned by dip::Polygon::FitCircle. more...
struct dip::ConvexHull
A convex hull is a convex polygon. It can be constructed from a simple dip::Polygon, and is guaranteed clockwise. more...
class dip::CovarianceMatrix
A 2D covariance matrix for computation with 2D vertices. more...
struct dip::EllipseParameters
Represents an ellipse, returned by dip::CovarianceMatrix::Ellipse and dip::Polygon::FitEllipse. more...
class dip::Feature::Base abstract
The abstract base class for all measurement features. more...
class dip::Feature::ChainCodeBased abstract
The abstract base class for all chain-code–based measurement features. more...
class dip::Feature::Composite abstract
The abstract base class for all composite measurement features. more...
class dip::Feature::ConvexHullBased abstract
The abstract base class for all convex-hull–based measurement features. more...
class dip::Feature::ImageBased abstract
The abstract base class for all image-based measurement features. more...
struct dip::Feature::Information
Information about a measurement feature more...
class dip::Feature::LineBased abstract
The abstract base class for all line-based measurement features. more...
class dip::Feature::PolygonBased abstract
The abstract base class for all polygon-based measurement features. more...
struct dip::Feature::ValueInformation
Information about a measurement value, one of the components of a feature more...
struct dip::FeretValues
Contains the various Feret diameters as returned by dip::ConvexHull::Feret and dip::ChainCode::Feret. more...
class dip::Measurement
Contains measurement results, as obtained through dip::MeasurementTool::Measure. more...
class dip::MeasurementTool
Performs measurements on images. more...
struct dip::Polygon
A polygon with floating-point vertices. more...
class dip::RadiusValues
Holds the various output values of the dip::Polygon::RadiusStatistics function. more...
template<typename T>
struct dip::Vertex
Encodes a location in a 2D image. more...

Aliases

using dip::BoundingBoxFloat = dip::BoundingBox
A bounding box with floating-point coordinates.
using dip::BoundingBoxInteger = dip::BoundingBox
A bounding box with integer coordinates.
using dip::ChainCodeArray = std::vector<ChainCode>
A collection of object contours.
using dip::Feature::InformationArray = std::vector<Information>
Information about the known measurement features
using dip::Feature::ValueInformationArray = std::vector<ValueInformation>
Information about the values of a measurement feature, or all values of all measurement features in a dip::Measurement object.
using dip::ObjectIdToIndexMap = tsl::robin_map<dip::uint, dip::uint>
Maps object IDs to object indices
using dip::VertexFloat = dip::Vertex
A vertex with floating-point coordinates.
using dip::VertexInteger = dip::Vertex
A vertex with integer coordinates

Enums

enum class dip::Feature::Type: uint8
The types of measurement features more...

Functions

template<typename T>
auto dip::Angle(dip::Vertex const& v1, dip::Vertex const& v2) -> dip::dfloat
The angle of the vector v2-v1.
template<typename T>
auto dip::CrossProduct(dip::Vertex const& v1, dip::Vertex const& v2) -> dip::dfloat
Compute the z component of the cross product of vectors v1 and v2.
template<typename T>
auto dip::Distance(dip::Vertex const& v1, dip::Vertex const& v2) -> dip::dfloat
The norm of the vector v2-v1.
template<typename T>
auto dip::DistanceSquare(dip::Vertex const& v1, dip::Vertex const& v2) -> dip::dfloat
The square norm of the vector v2-v1.
auto dip::GetImageChainCodes(dip::Image const& labels, std::vector<LabelType> const& objectIDs = {}, dip::uint connectivity = 2) -> dip::ChainCodeArray
Returns the set of chain codes sequences that encode the contours of the given objects in a labeled image. more...
auto dip::GetSingleChainCode(dip::Image const& labels, dip::UnsignedArray const& startCoord, dip::uint connectivity = 2) -> dip::ChainCode
Returns the chain codes sequence that encodes the contour of one object in a binary or labeled image. more...
auto dip::Maximum(dip::Measurement::IteratorFeature const& featureValues) -> dip::Measurement::ValueType
Returns the largest feature value in the first column of featureValues. more...
auto dip::MaximumAndMinimum(dip::Measurement::IteratorFeature const& featureValues) -> dip::MinMaxAccumulator
Returns the maximum and minimum feature values in the first column of featureValues. more...
auto dip::Mean(dip::Measurement::IteratorFeature const& featureValues) -> dip::dfloat
Returns the mean feature value in the first column of featureValues. more...
void dip::MeasurementWriteCSV(dip::Measurement const& measurement, dip::String const& filename, dip::StringSet const& options = {})
Writes a dip::Measurement structure to a CSV file. more...
auto dip::Median(dip::Measurement::IteratorFeature const& featureValues) -> dip::dfloat
Returns the median feature value in the first column of featureValues. more...
auto dip::Minimum(dip::Measurement::IteratorFeature const& featureValues) -> dip::Measurement::ValueType
Returns the smallest feature value in the first column of featureValues. more...
template<typename T>
auto dip::Norm(dip::Vertex const& v) -> dip::dfloat
The norm of the vector v.
template<typename T>
auto dip::NormSquare(dip::Vertex const& v) -> dip::dfloat
The square of the norm of the vector v.
auto dip::ObjectMaximum(dip::Measurement::IteratorFeature const& featureValues) -> dip::uint
Returns the object ID with the largest feature value in the first column of featureValues. more...
auto dip::ObjectMinimum(dip::Measurement::IteratorFeature const& featureValues) -> dip::uint
Returns the object ID with the smallest feature value in the first column of featureValues. more...
void dip::ObjectToMeasurement(dip::Image const& label, dip::Image& out, dip::Measurement::IteratorFeature const& featureValues)
Paints each object with the selected measurement feature values. more...
template<typename T>
auto dip::ParallelogramSignedArea(dip::Vertex const& v1, dip::Vertex const& v2, dip::Vertex const& v3) -> dip::dfloat
Compute the z component of the cross product of vectors v2-v1 and v3-v1.
auto dip::Percentile(dip::Measurement::IteratorFeature const& featureValues, dip::dfloat percentile) -> dip::Measurement::ValueType
Returns the percentile feature value in the first column of featureValues. more...
auto dip::Quartiles(dip::Measurement::IteratorFeature const& featu) -> dip::QuartilesResult
Computes the minimum, lower quartile (25th percentile), median (50th percentile), upper quartile (75th percentile), and maximum. more...
auto dip::SampleStatistics(dip::Measurement::IteratorFeature const& featureValues) -> dip::StatisticsAccumulator
Returns the first four central moments of the feature values in the first column of featureValues. more...
template<typename T>
auto dip::TriangleArea(dip::Vertex const& v1, dip::Vertex const& v2, dip::Vertex const& v3) -> dip::dfloat
Compute the area of the triangle formed by vertices v1, v2 and v3.
template<typename T>
auto dip::TriangleHeight(dip::Vertex const& v1, dip::Vertex const& v2, dip::Vertex const& v3) -> dip::dfloat
Compute the height of the triangle formed by vertices v1, v2 and v3, with v3 the tip.

Operators

auto dip::operator!=(dip::Measurement::IteratorFeature const& featureValues, dip::Measurement::ValueType value) -> dip::LabelMap
Selects objects where the first element of featureValues is unequal to value.
template<typename T>
auto dip::operator*(dip::Vertex v, dip::dfloat s) -> dip::Vertex
Multiply a vertex and a constant, scaling isotropically.
template<typename T>
auto dip::operator*(dip::Vertex lhs, dip::Vertex const& rhs) -> dip::Vertex
Multiply a vertex by another vertex, scaling anisotropically.
auto dip::operator*(dip::VertexFloat lhs, dip::VertexInteger const& rhs) -> dip::VertexFloat
Multiply a vertex by another vertex, scaling anisotropically, where the LHS is floating-point and the RHS is integer.
auto dip::operator*(dip::VertexInteger const& lhs, dip::VertexFloat const& rhs) -> dip::VertexFloat
Multiply a vertex by another vertex, scaling anisotropically, where the LHS is integer and the RHS is floating-point.
auto dip::operator+(dip::Measurement const& lhs, dip::Measurement const& rhs) -> dip::Measurement
The + operator merges two dip::Measurement objects. more...
template<typename T>
auto dip::operator+(dip::Vertex lhs, dip::Vertex const& rhs) -> dip::Vertex
Add two vertices together, with identical types.
auto dip::operator+(dip::VertexFloat lhs, dip::VertexInteger const& rhs) -> dip::VertexFloat
Add two vertices together, where the LHS is floating-point and the RHS is integer.
auto dip::operator+(dip::VertexInteger const& lhs, dip::VertexFloat rhs) -> dip::VertexFloat
Add two vertices together, where the LHS is integer and the RHS is floating-point.
template<typename T, typename S>
auto dip::operator+(dip::Vertex v, S t) -> dip::Vertex
Add a vertex and a constant.
template<typename T>
auto dip::operator-(dip::Vertex lhs, dip::Vertex const& rhs) -> dip::Vertex
Subtract two vertices from each other.
auto dip::operator-(dip::VertexFloat lhs, dip::VertexInteger const& rhs) -> dip::VertexFloat
Subtract two vertices from each other, where the LHS is floating-point and the RHS is integer.
auto dip::operator-(dip::VertexInteger const& lhs, dip::VertexFloat const& rhs) -> dip::VertexFloat
Subtract two vertices from each other, where the LHS is integer and the RHS is floating-point.
template<typename T, typename S>
auto dip::operator-(dip::Vertex v, S t) -> dip::Vertex
Subtract a vertex and a constant.
template<typename T>
auto dip::operator/(dip::Vertex v, dip::dfloat s) -> dip::Vertex
Divide a vertex by a constant, scaling isotropically.
template<typename T>
auto dip::operator/(dip::Vertex lhs, dip::Vertex const& rhs) -> dip::Vertex
Divide a vertex by another vertex, scaling anisotropically.
auto dip::operator/(dip::VertexFloat lhs, dip::VertexInteger const& rhs) -> dip::VertexFloat
Divide a vertex by another vertex, scaling anisotropically, where the LHS is floating-point and the RHS is integer.
auto dip::operator/(dip::VertexInteger const& lhs, dip::VertexFloat const& rhs) -> dip::VertexFloat
Divide a vertex by another vertex, scaling anisotropically, where the LHS is integer and the RHS is floating-point.
auto dip::operator<(dip::Measurement::IteratorFeature const& featureValues, dip::Measurement::ValueType value) -> dip::LabelMap
Selects objects where the first element of featureValues is smaller than value.
auto dip::operator<<(std::ostream& os, dip::Measurement const& measurement) -> std::ostream&
You can output a dip::Measurement to std::cout or any other stream to produce a human-readable representation of the tabular data in it.
auto dip::operator<=(dip::Measurement::IteratorFeature const& featureValues, dip::Measurement::ValueType value) -> dip::LabelMap
Selects objects where the first element of featureValues is not greater than value.
auto dip::operator==(dip::Measurement::IteratorFeature const& featureValues, dip::Measurement::ValueType value) -> dip::LabelMap
Selects objects where the first element of featureValues is equal to value.
template<typename T>
auto dip::operator==(dip::Vertex v1, dip::Vertex v2) -> bool
Compare two vertices.
auto dip::operator>(dip::Measurement::IteratorFeature const& featureValues, dip::Measurement::ValueType value) -> dip::LabelMap
Selects objects where the first element of featureValues is greater than value.
auto dip::operator>=(dip::Measurement::IteratorFeature const& featureValues, dip::Measurement::ValueType value) -> dip::LabelMap
Selects objects where the first element of featureValues is not smaller than value.

Class documentation

#include "diplib/polygon.h"
struct dip::FeretValues

Contains the various Feret diameters as returned by dip::ConvexHull::Feret and dip::ChainCode::Feret.

Variables
dip::dfloat maxDiameter The maximum Feret diameter
dip::dfloat minDiameter The minimum Feret diameter
dip::dfloat maxPerpendicular The Feret diameter perpendicular to minDiameter
dip::dfloat maxAngle The angle at which maxDiameter was measured
dip::dfloat minAngle The angle at which minDiameter was measured

#include "diplib/polygon.h"
struct dip::CircleParameters

Represents a circle, returned by dip::Polygon::FitCircle.

Variables
dip::VertexFloat center The center coordinates
dip::dfloat diameter The diameter

#include "diplib/polygon.h"
struct dip::EllipseParameters

Represents an ellipse, returned by dip::CovarianceMatrix::Ellipse and dip::Polygon::FitEllipse.

Variables
dip::VertexFloat center The center coordinates
dip::dfloat majorAxis Length of the major axis (longest diameter)
dip::dfloat minorAxis Length of the minor axis (shortest diameter)
dip::dfloat orientation Orientation of the major axis (in radian)
dip::dfloat eccentricity Ellipse eccentricity, defined as \(\sqrt{1 - b^2 / a^2}\) , with \(a\) equal to majorAxis and \(b\) equal to minorAxis.

Alias documentation

#include "diplib/measurement.h"
using dip::ObjectIdToIndexMap = tsl::robin_map<dip::uint, dip::uint>

Maps object IDs to object indices

Enum documentation

#include "diplib/measurement.h"
enum class dip::Feature::Type: uint8

The types of measurement features

Enumerators
LINE_BASED = 0 The feature is derived from dip::Feature::LineBased
IMAGE_BASED = 1 The feature is derived from dip::Feature::ImageBased
CHAINCODE_BASED = 2 The feature is derived from dip::Feature::ChainCodeBased
POLYGON_BASED = 3 The feature is derived from dip::Feature::PolygonBased
CONVEXHULL_BASED = 4 The feature is derived from dip::Feature::ConvexHullBased
COMPOSITE = 5 The feature is derived from dip::Feature::Composite

Function documentation

#include "diplib/chain_code.h"
dip::ChainCodeArray dip::GetImageChainCodes( dip::Image const& labels, std::vector<LabelType> const& objectIDs = {}, dip::uint connectivity = 2)

Returns the set of chain codes sequences that encode the contours of the given objects in a labeled image.

Note that only the first closed contour for each label is found; if an object has multiple connected components, only part of it is found. The chain code traces the outer perimeter of the object, holes are ignored.

objectIDs is a list with object IDs present in the labeled image. If an empty array is given, all objects in the image are used. For the meaning of connectivity, see Connectivity.

labels is a labeled image, and must be scalar and of an unsigned integer type.

#include "diplib/chain_code.h"
dip::ChainCode dip::GetSingleChainCode( dip::Image const& labels, dip::UnsignedArray const& startCoord, dip::uint connectivity = 2)

Returns the chain codes sequence that encodes the contour of one object in a binary or labeled image.

Note that only one closed contour is found; if the object has multiple connected components, only part of it is found. The chain code traces the outer perimeter of the object, holes are ignored.

startCoord is the 2D coordinates of a boundary pixel. If it points to a zero-valued pixel or a pixel not on the boundary of an object, an exception will be thrown.

For the meaning of connectivity, see Connectivity.

labels is a labeled or binary image, and must be scalar and of a binary or unsigned integer type.

#include "diplib/measurement.h"
void dip::ObjectToMeasurement( dip::Image const& label, dip::Image& out, dip::Measurement::IteratorFeature const& featureValues)

Paints each object with the selected measurement feature values.

The input featureValues is a view over a specific feature in a dip::Measurement object. It is assumed that that measurement object was obtained through measurement of the input label image. To obtain such a view, use the measurement’s [] indexing with a feature name. Alternatively, use the dip::Measurement::FeatureValuesView method to select an arbitrary subset of feature value columns. The dip::Measurement::IteratorFeature::Subset method can be used for the same purpose.

If the selected feature has more than one value, then out will be a vector image with as many tensor elements as values are in the feature.

out will be of type DT_SFLOAT. To change the data type, set the data type of out and set its protect flag before calling this function:

dip::Image out;
out.SetDataType( dip::DT_UINT32 );
out.Protect();
ObjectToMeasurement( label, out, featureValues );

#include "diplib/measurement.h"
void dip::MeasurementWriteCSV( dip::Measurement const& measurement, dip::String const& filename, dip::StringSet const& options = {})

Writes a dip::Measurement structure to a CSV file.

The CSV (comma separated values) file is a generic container for tabular data, and can be read in just about any graphing and statistics software package.

The file written contains three header rows, followed by one row per object. The three header rows contain the feature names, the value names, and the value units. The feature names, of which there typically are fewer than columns, are interspersed with empty cells to line them up with the first column for the feature. For example:

ObjectID, Size,  Center, ,      Feret, ,      ,        ,
,         ,      dim0,   dim1,  Max,   Min,   PerpMin, MaxAng, MinAng
,         um^2,  um,     um,    um,    um,    um,      rad,    rad
1,        397.0, 20.06,  12.98, 34.99, 16.43, 34.83,   2.111,  3.588
2,        171.0, 63.13,  4.123, 20.22, 11.00, 20.00,   2.993,  4.712
3,        628.0, 108.4,  12.47, 32.20, 26.00, 28.00,   2.202,  0.000
4,        412.0, 154.5,  9.561, 26.40, 22.00, 23.00,   2.222,  4.712

options is one or more of the following values:

  • "unicode": The units will be written using unicode strings. By default, only ASCII characters are used.
  • "simple": There will only be a single header line, combining the three strings as follows: "Feature value (units)". For example: "Size (um^2)", "Feret Max (um)", etc.

#include "diplib/measurement.h"
dip::Measurement dip::operator+( dip::Measurement const& lhs, dip::Measurement const& rhs)

The + operator merges two dip::Measurement objects.

The resulting object has, as feature set, the union of the two input feature sets, and as object IDs, the union of the two object ID lists. That is, the output might have more columns or more rows (i.e. more objects) than the two input objects, depending on the overlaps between the two. If both features and cells differ between the two, then cells with unknown data are filled with NaN. If both objects contain the same feature for the same measurement, and the value is NaN for one, the other value is picked. If both have a non-NaN value, the one of the lhs argument is picked (values are never actually added together!). This process insures that it is possible to add multiple sets of measurements (across different objects and different features) together, without worrying about the order that they are added together:

dip::Image label1 = ... // one image with objects 1-10
dip::Image label2 = ... // one image with objects 11-20
auto set1 = measurementTool.Measure( label1, {}, {'Size','Center'} );
auto set2 = measurementTool.Measure( label2, {}, {'Size','Center'} );
auto set3 = measurementTool.Measure( label1, {}, {'Feret','Radius'} );
auto set4 = measurementTool.Measure( label2, {}, {'Feret','Radius'} );
auto sum1 = set1 + set2; // Size and Center features for objects 1-20
auto sum2 = set1 + set3; // Size, Center, Feret and Radius features for objects 1-10
auto sumA = (set1 + set2) + (set3 + set4); // All features for all objects
auto sumB = (set1 + set3) + (set2 + set4); // Idem
auto sumC = set1 + set2 + set3 + set4;     // Idem
auto sumD = set1 + set4 + set3 + set2;     // Idem