Measurement module

The measurement infrastructure and functionality.

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.

Classes

struct dip::FeretValues
Contains the various Feret diameters as returned by dip::ConvexHull::Feret and dip::ChainCode::Feret.
class dip::RadiusValues
Holds the various output values of the dip::Polygon::RadiusStatistics function.
template<typename T>
struct dip::Vertex
Encodes a location in a 2D image
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).
class dip::CovarianceMatrix
A 2D covariance matrix for computation with 2D vertices.
struct dip::Polygon
A polygon with floating-point vertices.
class dip::ConvexHull
A convex hull is a convex polygon. It can be constructed from a dip::Polygon, and a const reference to the underlying dip::Polygon object can be obtained. It is guaranteed clockwise.
struct dip::ChainCode
The contour of an object as a chain code sequence.
struct dip::Feature::Information
Information about a measurement feature
struct dip::Feature::ValueInformation
Information about a measurement value, one of the components of a feature
class dip::Feature::Base abstract
The pure virtual base class for all measurement features.
class dip::Feature::LineBased abstract
The pure virtual base class for all line-based measurement features.
class dip::Feature::ImageBased abstract
The pure virtual base class for all image-based measurement features.
class dip::Feature::ChainCodeBased abstract
The pure virtual base class for all chain-code–based measurement features.
class dip::Feature::PolygonBased abstract
The pure virtual base class for all polygon-based measurement features.
class dip::Feature::ConvexHullBased abstract
The pure virtual base class for all convex-hull–based measurement features.
class dip::Feature::Composite abstract
The pure virtual base class for all composite measurement features.
class dip::Measurement
Contains measurement results, as obtained through dip::MeasurementTool::Measure.
class dip::MeasurementTool
Performs measurements on images.

Aliases

using dip::VertexFloat = Vertex<dip::dfloat>
A vertex with floating-point coordinates
using dip::VertexInteger = Vertex<dip::sint>
A vertex with integer coordinates
using dip::BoundingBoxFloat = BoundingBox<dip::dfloat>
A bounding box with floating-point coordinates
using dip::BoundingBoxInteger = BoundingBox<dip::sint>
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 = std::unordered_map<dip::uint, dip::uint>
Maps object IDs to object indices

Enums

enum class dip::Feature::Type: int{ LINE_BASED, IMAGE_BASED, CHAINCODE_BASED, POLYGON_BASED, CONVEXHULL_BASED, COMPOSITE }
The types of measurement features

Functions

template<typename T>
auto dip::Norm(Vertex<T> const& v) -> dip::dfloat
The norm of the vector v.
template<typename T>
auto dip::NormSquare(Vertex<T> const& v) -> dip::dfloat
The square of the norm of the vector v.
template<typename T>
auto dip::Distance(Vertex<T> const& v1, Vertex<T> const& v2) -> dip::dfloat
The norm of the vector v2-v1.
template<typename T>
auto dip::DistanceSquare(Vertex<T> const& v1, Vertex<T> const& v2) -> dip::dfloat
The square norm of the vector v2-v1.
template<typename T>
auto dip::Angle(Vertex<T> const& v1, Vertex<T> const& v2) -> dip::dfloat
The angle of the vector v2-v1.
template<typename T>
auto dip::CrossProduct(Vertex<T> const& v1, Vertex<T> const& v2) -> dip::dfloat
Compute the z component of the cross product of vectors v1 and v2
template<typename T>
auto dip::ParallelogramSignedArea(Vertex<T> const& v1, Vertex<T> const& v2, Vertex<T> const& v3) -> dip::dfloat
Compute the z component of the cross product of vectors v2-v1 and v3-v1
template<typename T>
auto dip::TriangleArea(Vertex<T> const& v1, Vertex<T> const& v2, Vertex<T> const& v3) -> dip::dfloat
Compute the area of the triangle formed by vertices v1, v2 and v3
template<typename T>
auto dip::TriangleHeight(Vertex<T> const& v1, Vertex<T> const& v2, Vertex<T> const& v3) -> dip::dfloat
Compute the height of the triangle formed by vertices v1, v2 and v3, with v3 the tip
auto dip::GetImageChainCodes(dip::Image const& labels, dip::UnsignedArray 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.
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.
void dip::ObjectToMeasurement(dip::Image const& label, dip::Image& out, Measurement::IteratorFeature const& featureValues)
Paints each object with the selected measurement feature values.
void dip::MeasurementWriteCSV(dip::Measurement const& measurement, dip::String const& filename, dip::StringSet const& options = {})
Writes a dip::Measurement structure to a CSV file.
auto dip::Minimum(Measurement::IteratorFeature const& featureValues) -> Measurement::ValueType
Returns the smallest feature value in the first column of featureValues.
auto dip::Maximum(Measurement::IteratorFeature const& featureValues) -> Measurement::ValueType
Returns the largest feature value in the first column of featureValues.
auto dip::Percentile(Measurement::IteratorFeature const& featureValues, dip::dfloat percentile) -> Measurement::ValueType
Returns the percentile feature value in the first column of featureValues.
auto dip::Median(Measurement::IteratorFeature const& featureValues) -> dip::dfloat
Returns the median feature value in the first column of featureValues.
auto dip::Mean(Measurement::IteratorFeature const& featureValues) -> dip::dfloat
Returns the mean feature value in the first column of featureValues.
auto dip::MaximumAndMinimum(Measurement::IteratorFeature const& featureValues) -> dip::MinMaxAccumulator
Returns the maximum and minimum feature values in the first column of featureValues.
auto dip::SampleStatistics(Measurement::IteratorFeature const& featureValues) -> dip::StatisticsAccumulator
Returns the first four central moments of the feature values in the first column of featureValues.

Operators

template<typename T>
auto dip::operator==(Vertex<T> v1, Vertex<T> v2) -> bool
Compare two vertices
template<typename T>
auto dip::operator+(Vertex<T> lhs, Vertex<T> const& rhs) -> Vertex<T>
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>
auto dip::operator-(Vertex<T> lhs, Vertex<T> const& rhs) -> Vertex<T>
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+(Vertex<T> v, S n) -> Vertex<T>
Add a vertex and a constant
template<typename T, typename S>
auto dip::operator-(Vertex<T> v, S n) -> Vertex<T>
Subtract a vertex and a constant
template<typename T>
auto dip::operator*(Vertex<T> v, dip::dfloat n) -> Vertex<T>
Multiply a vertex and a constant
template<typename T>
auto dip::operator/(Vertex<T> v, dip::dfloat n) -> Vertex<T>
Divide a vertex by a constant
auto dip::operator+(dip::Measurement const& lhs, dip::Measurement const& rhs) -> dip::Measurement
The + operator merges two dip::Measurement objects.
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.

Class documentation

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

Alias documentation

using dip::VertexFloat = Vertex<dip::dfloat>

A vertex with floating-point coordinates

using dip::VertexInteger = Vertex<dip::sint>

A vertex with integer coordinates

using dip::BoundingBoxFloat = BoundingBox<dip::dfloat>

A bounding box with floating-point coordinates

using dip::BoundingBoxInteger = BoundingBox<dip::sint>

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 = std::unordered_map<dip::uint, dip::uint>

Maps object IDs to object indices

Enum documentation

enum class dip::Feature::Type: int

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

template<typename T>
dip::dfloat dip::Norm(Vertex<T> const& v)

The norm of the vector v.

template<typename T>
dip::dfloat dip::NormSquare(Vertex<T> const& v)

The square of the norm of the vector v.

template<typename T>
dip::dfloat dip::Distance(Vertex<T> const& v1, Vertex<T> const& v2)

The norm of the vector v2-v1.

template<typename T>
dip::dfloat dip::DistanceSquare(Vertex<T> const& v1, Vertex<T> const& v2)

The square norm of the vector v2-v1.

template<typename T>
dip::dfloat dip::Angle(Vertex<T> const& v1, Vertex<T> const& v2)

The angle of the vector v2-v1.

template<typename T>
dip::dfloat dip::CrossProduct(Vertex<T> const& v1, Vertex<T> const& v2)

Compute the z component of the cross product of vectors v1 and v2

template<typename T>
dip::dfloat dip::ParallelogramSignedArea(Vertex<T> const& v1, Vertex<T> const& v2, Vertex<T> const& v3)

Compute the z component of the cross product of vectors v2-v1 and v3-v1

template<typename T>
dip::dfloat dip::TriangleArea(Vertex<T> const& v1, Vertex<T> const& v2, Vertex<T> const& v3)

Compute the area of the triangle formed by vertices v1, v2 and v3

template<typename T>
dip::dfloat dip::TriangleHeight(Vertex<T> const& v1, Vertex<T> const& v2, Vertex<T> const& v3)

Compute the height of the triangle formed by vertices v1, v2 and v3, with v3 the tip

dip::ChainCodeArray dip::GetImageChainCodes(dip::Image const& labels, dip::UnsignedArray 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.

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.

void dip::ObjectToMeasurement(dip::Image const& label, dip::Image& out, 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 );

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.

Measurement::ValueType dip::Minimum(Measurement::IteratorFeature const& featureValues)

Returns the smallest feature value in the first column of featureValues.

The input featureValues is a view over a specific feature in a dip::Measurement object. Only the first value of the feature is used. For features with multiple values, select a value using the dip::Measurement::IteratorFeature::Subset method, or pick a column in the dip::Measurement object directly using dip::Measurement::FeatureValuesView.

Measurement::ValueType dip::Maximum(Measurement::IteratorFeature const& featureValues)

Returns the largest feature value in the first column of featureValues.

The input featureValues is a view over a specific feature in a dip::Measurement object. Only the first value of the feature is used. For features with multiple values, select a value using the dip::Measurement::IteratorFeature::Subset method, or pick a column in the dip::Measurement object directly using dip::Measurement::FeatureValuesView.

Measurement::ValueType dip::Percentile(Measurement::IteratorFeature const& featureValues, dip::dfloat percentile)

Returns the percentile feature value in the first column of featureValues.

The input featureValues is a view over a specific feature in a dip::Measurement object. Only the first value of the feature is used. For features with multiple values, select a value using the dip::Measurement::IteratorFeature::Subset method, or pick a column in the dip::Measurement object directly using dip::Measurement::FeatureValuesView.

dip::dfloat dip::Median(Measurement::IteratorFeature const& featureValues)

Returns the median feature value in the first column of featureValues.

The input featureValues is a view over a specific feature in a dip::Measurement object. Only the first value of the feature is used. For features with multiple values, select a value using the dip::Measurement::IteratorFeature::Subset method, or pick a column in the dip::Measurement object directly using dip::Measurement::FeatureValuesView.

dip::dfloat dip::Mean(Measurement::IteratorFeature const& featureValues)

Returns the mean feature value in the first column of featureValues.

The input featureValues is a view over a specific feature in a dip::Measurement object. Only the first value of the feature is used. For features with multiple values, select a value using the dip::Measurement::IteratorFeature::Subset method, or pick a column in the dip::Measurement object directly using dip::Measurement::FeatureValuesView.

dip::MinMaxAccumulator dip::MaximumAndMinimum(Measurement::IteratorFeature const& featureValues)

Returns the maximum and minimum feature values in the first column of featureValues.

The input featureValues is a view over a specific feature in a dip::Measurement object. Only the first value of the feature is used. For features with multiple values, select a value using the dip::Measurement::IteratorFeature::Subset method, or pick a column in the dip::Measurement object directly using dip::Measurement::FeatureValuesView.

dip::StatisticsAccumulator dip::SampleStatistics(Measurement::IteratorFeature const& featureValues)

Returns the first four central moments of the feature values in the first column of featureValues.

The input featureValues is a view over a specific feature in a dip::Measurement object. Only the first value of the feature is used. For features with multiple values, select a value using the dip::Measurement::IteratorFeature::Subset method, or pick a column in the dip::Measurement object directly using dip::Measurement::FeatureValuesView.