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.

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::RadiusStatistics and dip::ConvexHull::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.
class dip::Measurement
Contains measurement results, as obtained through dip::MeasurementTool::Measure.
class dip::MeasurementTool
Performs measurements on images.

Typedefs

using VertexFloat = Vertex<dfloat>
A vertex with floating-point coordinates.
using VertexInteger = Vertex<dip::sint>
A vertex with integer coordinates.
using BoundingBoxFloat = BoundingBox<dfloat>
A bounding box with floating-point coordinates.
using BoundingBoxInteger = BoundingBox<dip::sint>
A bounding box with integer coordinates.
using ChainCodeArray = std::vector<ChainCode>
A collection of object contours.
using ObjectIdToIndexMap = std::map<dip::uint, dip::uint>
Maps object IDs to object indices.

Functions

auto GetImageChainCodes(Image const& labels, UnsignedArray const& objectIDs = {}, dip::uint connectivity = 2) -> ChainCodeArray
Returns the set of chain codes sequences that encode the contours of the given objects in a labeled image.
auto GetSingleChainCode(Image const& labels, UnsignedArray const& startCoord, dip::uint connectivity = 2) -> ChainCode
Returns the chain codes sequence that encodes the contour of one object in a binary or labeled image.
void ObjectToMeasurement(Image const& label, Image& out, Measurement::IteratorFeature const& featureValues)
Paints each object with the selected measurement feature values.
void MeasurementWriteCSV(Measurement const& measurement, String const& filename, StringSet const& options = {})
Writes a dip::Measurement structure to a CSV file.
auto Minimum(Measurement::IteratorFeature const& featureValues) -> Measurement::ValueType
Returns the smallest feature value in the first column of featureValues.
auto Maximum(Measurement::IteratorFeature const& featureValues) -> Measurement::ValueType
Returns the largest feature value in the first column of featureValues.
auto Percentile(Measurement::IteratorFeature const& featureValues, dfloat percentile) -> Measurement::ValueType
Returns the percentile feature value in the first column of featureValues.
auto Median(Measurement::IteratorFeature const& featureValues) -> dfloat
Returns the median feature value in the first column of featureValues.
auto Mean(Measurement::IteratorFeature const& featureValues) -> dfloat
Returns the mean feature value in the first column of featureValues.
auto MaximumAndMinimum(Measurement::IteratorFeature const& featureValues) -> MinMaxAccumulator
Returns the maximum and minimum feature values in the first column of featureValues.
auto SampleStatistics(Measurement::IteratorFeature const& featureValues) -> StatisticsAccumulator
Returns the first four central moments of the feature values in the first column of featureValues.
template<typename T>
auto operator==(Vertex<T> v1, Vertex<T> v2) -> bool
Compare two vertices.
template<typename T>
auto operator!=(Vertex<T> v1, Vertex<T> v2) -> bool
Compare two vertices.
template<typename T>
auto Norm(Vertex<T> const& v) -> dfloat
The norm of the vector v.
template<typename T>
auto NormSquare(Vertex<T> const& v) -> dfloat
The square of the norm of the vector v.
template<typename T>
auto Distance(Vertex<T> const& v1, Vertex<T> const& v2) -> dfloat
The norm of the vector v2-v1.
template<typename T>
auto DistanceSquare(Vertex<T> const& v1, Vertex<T> const& v2) -> dfloat
The square norm of the vector v2-v1.
template<typename T>
auto Angle(Vertex<T> const& v1, Vertex<T> const& v2) -> dfloat
The angle of the vector v2-v1.
template<typename T>
auto CrossProduct(Vertex<T> const& v1, Vertex<T> const& v2) -> dfloat
Compute the z component of the cross product of vectors v1 and v2
template<typename T>
auto ParallelogramSignedArea(Vertex<T> const& v1, Vertex<T> const& v2, Vertex<T> const& v3) -> dfloat
Compute the z component of the cross product of vectors v2-v1 and v3-v1
template<typename T>
auto TriangleArea(Vertex<T> const& v1, Vertex<T> const& v2, Vertex<T> const& v3) -> dfloat
Compute the area of the triangle formed by vertices v1, v2 and v3
template<typename T>
auto TriangleHeight(Vertex<T> const& v1, Vertex<T> const& v2, Vertex<T> const& v3) -> dfloat
Compute the height of the triangle formed by vertices v1, v2 and v3, with v3 the tip.
template<typename T>
auto operator+(Vertex<T> lhs, Vertex<T> const& rhs) -> Vertex<T>
Add two vertices together, with identical types.
auto operator+(VertexFloat lhs, VertexInteger const& rhs) -> VertexFloat
Add two vertices together, where the LHS is floating-point and the RHS is integer.
auto operator+(VertexInteger const& lhs, VertexFloat rhs) -> VertexFloat
Add two vertices together, where the LHS is integer and the RHS is floating-point.
template<typename T>
auto operator-(Vertex<T> lhs, Vertex<T> const& rhs) -> Vertex<T>
Subtract two vertices from each other.
auto operator-(VertexFloat lhs, VertexInteger const& rhs) -> VertexFloat
Subtract two vertices from each other, where the LHS is floating-point and the RHS is integer.
auto operator-(VertexInteger const& lhs, VertexFloat const& rhs) -> VertexFloat
Subtract two vertices from each other, where the LHS is integer and the RHS is floating-point.
template<typename T, typename S>
auto operator+(Vertex<T> v, S n) -> Vertex<T>
Add a vertex and a constant.
template<typename T, typename S>
auto operator-(Vertex<T> v, S n) -> Vertex<T>
Subtract a vertex and a constant.
template<typename T>
auto operator*(Vertex<T> v, dfloat n) -> Vertex<T>
Multiply a vertex and a constant.
template<typename T>
auto operator/(Vertex<T> v, dfloat n) -> Vertex<T>
Divide a vertex by a constant.
auto operator<<(std::ostream& os, 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.

Typedef documentation

using VertexFloat = Vertex<dfloat>

A vertex with floating-point coordinates.

using VertexInteger = Vertex<dip::sint>

A vertex with integer coordinates.

using BoundingBoxFloat = BoundingBox<dfloat>

A bounding box with floating-point coordinates.

using BoundingBoxInteger = BoundingBox<dip::sint>

A bounding box with integer coordinates.

using ChainCodeArray = std::vector<ChainCode>

A collection of object contours.

using ObjectIdToIndexMap = std::map<dip::uint, dip::uint>

Maps object IDs to object indices.

Function documentation

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

ChainCode GetSingleChainCode(Image const& labels, 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.

void ObjectToMeasurement(Image const& label, 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 MeasurementWriteCSV(Measurement const& measurement, String const& filename, 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 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 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 Percentile(Measurement::IteratorFeature const& featureValues, 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.

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

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

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

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

template<typename T>
bool operator==(Vertex<T> v1, Vertex<T> v2)

Compare two vertices.

template<typename T>
bool operator!=(Vertex<T> v1, Vertex<T> v2)

Compare two vertices.

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

The norm of the vector v.

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

The square of the norm of the vector v.

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

The norm of the vector v2-v1.

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

The square norm of the vector v2-v1.

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

The angle of the vector v2-v1.

template<typename T>
dfloat 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>
dfloat 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>
dfloat 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>
dfloat 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.

template<typename T>
Vertex<T> operator+(Vertex<T> lhs, Vertex<T> const& rhs)

Add two vertices together, with identical types.

VertexFloat operator+(VertexFloat lhs, VertexInteger const& rhs)

Add two vertices together, where the LHS is floating-point and the RHS is integer.

VertexFloat operator+(VertexInteger const& lhs, VertexFloat rhs)

Add two vertices together, where the LHS is integer and the RHS is floating-point.

template<typename T>
Vertex<T> operator-(Vertex<T> lhs, Vertex<T> const& rhs)

Subtract two vertices from each other.

VertexFloat operator-(VertexFloat lhs, VertexInteger const& rhs)

Subtract two vertices from each other, where the LHS is floating-point and the RHS is integer.

VertexFloat operator-(VertexInteger const& lhs, VertexFloat const& rhs)

Subtract two vertices from each other, where the LHS is integer and the RHS is floating-point.

template<typename T, typename S>
Vertex<T> operator+(Vertex<T> v, S n)

Add a vertex and a constant.

template<typename T, typename S>
Vertex<T> operator-(Vertex<T> v, S n)

Subtract a vertex and a constant.

template<typename T>
Vertex<T> operator*(Vertex<T> v, dfloat n)

Multiply a vertex and a constant.

template<typename T>
Vertex<T> operator/(Vertex<T> v, dfloat n)

Divide a vertex by a constant.

std::ostream& operator<<(std::ostream& os, Measurement const& measurement)

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.