The features known by the measurement tool

Contents

This page describes all the features known to dip::MeasurementTool by default. They are sorted into sections in the same way as the table in the documentation to dip::MeasurementTool.

Use dip::MeasurementTool::Configure to modify the behavior of features. Currently only the Perimeter feature can be configured.

Most features take the pixel sizes into account, and report measurements in physical units. If the pixel size for one dimension is not physical (i.e. it is unitless or given in pixels), then that value is ignored and assumed to be 1 px. Thus, for non-square pixels (anisotropic pixels), you must use physical units to indicate the pixel size (e.g. “1.0 µm x 1.2 µm”), it is not possible to use pixel units (e.g. “1.0 px x 1.2 px”).

Size features

Size

Counts the number of object pixels to give an unbiased estimate of the object’s area (2D), volume (3D), or hyper-volume (nD). If the image has a known pixel size, the number of pixels is multiplied by the size of each pixel to convert the estimate into physical units. This works correctly for anisotropic pixels.

SolidArea

Computes the area of the object ignoring any holes. It uses the object’s chain code and the dip::ChainCode::Area method.

Note that the chain code measures work only for 2D images, and expect objects to be a single connected component. If multiple connected components have the same label, only the first connected component found for that label will be measured.

This value is reported in physical units, anisotropic pixels are taken into account.

Perimeter

Computes the length of the object perimeter using the object’s chain code, using dip::ChainCode::Length. By default, if the object touches the image edge, only the portion of the perimeter that does not coincide with the image edge is measured. The "include boundary pixels" parameter of this feature can be set to a non-zero value to include those portions of the perimeter.

Note that the chain code measures work only for 2D images, and expect objects to be a single connected component. If multiple connected components have the same label, only the first connected component found for that label will be measured. Any holes in the object are not included in the perimeter either.

This value is reported in physical units, but only for isotropic (square) pixels. For anisotropic pixels, the length is reported in pixels, ignoring pixel sizes.

SurfaceArea

The 3D equivalent to the Perimeter feature. It does not assume a single connected component, and will include all surfaces in the measurement, including those of holes.

This value is reported in physical units, but only for isotropic (square) pixels.

Minimum

The smallest index along each dimension to a pixel within the object. This corresponds to the top-left corner of the cartesian bounding box. There is one value per image dimension. If the image has a known pixel size, the values represent the distances to the lower image edge along each dimension.

Maximum

The largest index along each dimension to a pixel within the object. This corresponds to the bottom-right corner of the cartesian bounding box. There is one value per image dimension. If the image has a known pixel size, the values represent the distances to the lower image edge along each dimension.

CartesianBox

The sizes of the smallest box around the object that is aligned with the grid axes. There is one value per image dimension. The size is in pixels or in physical units if known.

Feret

Computes the maximum and minimum object diameters from the object’s convex hull, using dip::ConvexHull::Feret. The convex hull is computed from the chain code using dip::ChainCode::ConvexHull.

Note that the chain code measures work only for 2D images, and expect objects to be a single connected component. If multiple connected components have the same label, only the first connected component found for that label will be measured.

Five values are returned:

  • 0: Max, the maximum Feret diameter, the length of the object.
  • 1: Min, the minimum Feret diameter, the width of the object.
  • 2: PerpMin, the Feret diameter perpendicular to Min, which is not necessarily equal to Max. Min and PerpMin are (usually, but not necessarily) the sizes of the minimum bounding box.
  • 3: MaxAng, the angle at which Max was obtained.
  • 4: MinAng, the angle at which Min was obtained.

The first three values are reported in physical units, but only for isotropic (square) pixels (otherwise the pixel sizes are ignored). The last two values are reported in radian, assuming isotropic pixels.

Radius

Statistics on the radius of the object, computed from the chain code using dip::ChainCode::Polygon and dip::Polygon::RadiusStatistics.

Note that the chain code measures work only for 2D images, and expect objects to be a single connected component. If multiple connected components have the same label, only the first connected component found for that label will be measured.

This feature takes the distances from the object’s centroid (as determined from the chain code, not influenced by any holes in the object) to each of the border pixels. From these distances it computes four values:

  • 0: Max, the largest distance.
  • 1: Mean, the average distance.
  • 2: Min, the shortest distance.
  • 3: StD, the standard deviation.

Note that the centroid does not necessarily lie within the object.

These values are reported in physical units, but only for isotropic (square) pixels. For anisotropic pixels, lengths are reported in pixels, ignoring pixel sizes.

ConvexArea

The area of the convex hull of the object. The convex hull is computed from the chain code using dip::ChainCode::ConvexHull.

Note that the chain code measures work only for 2D images, and expect objects to be a single connected component. If multiple connected components have the same label, only the first connected component found for that label will be measured.

This value is reported in physical units, anisotropic pixels are taken into account.

ConvexPerimeter

The perimeter of the convex hull. The convex hull is computed from the chain code.

Note that the chain code measures work only for 2D images, and expect objects to be a single connected component. If multiple connected components have the same label, only the first connected component found for that label will be measured.

This value is reported in physical units, but only for isotropic (square) pixels. For anisotropic pixels, the length is reported in pixels, ignoring pixel sizes.

Shape features

AspectRatioFeret

The ratio PerpMin/Min, two of the values returned by the Feret feature.

This feature ignores pixel sizes, isotropic pixels are assumed.

P2A

Computes:

  • 2D: \(\frac{p^2}{4 \pi a}\) , where \(p\) is the perimeter and \(a\) is the area.
  • 3D: \(\frac{\sqrt{a^3}}{6v\sqrt{\pi}}\) , where \(a\) is the surface area and \(v\) is the volume.

See Perimeter, SurfaceArea and Size. For solid objects, this measure is the reciprocal of Roundness.

This feature ignores pixel sizes, isotropic pixels are assumed.

Roundness

Computes \(\frac{4\pi a}{p^2}\) , where \(a\) is the solid area and \(p\) is the perimeter, using the features SolidArea and Perimeter. This measure is in the range (0,1], with 1 for a perfect circle. For solid objects, it is the reciprocal of P2A, but for objects with holes, this measure takes only the outer boundary into account.

This feature ignores pixel sizes, isotropic pixels are assumed.

Circularity

Circularity is a measure of similarity to a circle, and is given by coefficient of variation of the radii of the object. It is computed by the ratio StD/Mean of the Radius feature, and is 0 for a perfect circle. See dip::RadiusValues::Circularity.

This feature ignores pixel sizes, isotropic pixels are assumed.

PodczeckShapes

Computes the 5 Podczeck shape descriptors using the results of features Size, Feret and Perimeter. The shape descriptors are:

  • 0: Square, similarity to a square, \(\frac{a}{wh}\) .
  • 1: Circle, similarity to a circle, \(\frac{4a}{\pi h^2}\) .
  • 2: Triangle, similarity to a triangle, \(\frac{2a}{wh}\) .
  • 3: Ellipse, similarity to an ellipse, \(\frac{4a}{\pi wh}\) .
  • 4: Elongation, object elongation, \(\frac{p}{l}\) .

where \(a\) is the object area, \(p\) the perimeter, \(l\) the largest Feret diameter, \(w\) the smallest Feret diameter, and \(h\) the diameter perpendicular to the smallest diameter (PerpMin value of the Feret feature).

This feature ignores pixel sizes, isotropic pixels are assumed.

Solidity

The ratio Size/ConvexArea of the features Size and ConvexArea. It is in the range (0,1], with 1 for a convex object.

Convexity

The ratio ConvexPerimeter/Perimeter of the features Perimeter and ConvexPerimeter. It is in the range (0,1], with 1 for a convex object. This feature ignores pixel sizes, isotropic pixels are assumed.

EllipseVariance

A measure for deviation from an elliptic shape, computed using dip::ChainCode::Polygon and dip::Polygon::EllipseVariance from the chain code.

Note that the chain code measures work only for 2D images, and expect objects to be a single connected component. If multiple connected components have the same label, only the first connected component found for that label will be measured.

This feature ignores pixel sizes, isotropic pixels are assumed.

Eccentricity

Aspect ratio of the best fit ellipse, computed using dip::CovarianceMatrix::Eigenvalues::Eccentricity from the covariance matrix of the chain code. Eccentricity is defined as \(\sqrt{1-\frac{\lambda_2}{\lambda_1}}\) , with \(\lambda_1\) the largest eigenvalue and \(\lambda_2\) the smallest eigenvalue of the covariance matrix of the boundary pixels of the object.

Note that the chain code measures work only for 2D images, and expect objects to be a single connected component. If multiple connected components have the same label, only the first connected component found for that label will be measured.

This feature ignores pixel sizes, isotropic pixels are assumed.

BendingEnergy

Bending energy of object perimeter, computed using dip::ChainCode::BendingEnergy from the object’s chain code.

Note that the chain code measures work only for 2D images, and expect objects to be a single connected component. If multiple connected components have the same label, only the first connected component found for that label will be measured.

This value is reported in physical units, but only for isotropic (square) pixels (otherwise pixel sizes are ignored).

Intensity features

Mass

The sum of the grey-value image intensities across the object. The grey image can be a tensor image, one value per tensor element (channel) is produced.

Mean

The mean of the grey-value image intensities across the object. The grey image can be a tensor image, one value per tensor element (channel) is produced.

StandardDeviation

The standard deviation of the grey-value image intensities across the object. The grey image can be a tensor image, one value per tensor element (channel) is produced.

A fast algorithm is used that could result in catastrophic cancellation if the mean is much larger than the variance, see dip::FastVarianceAccumulator. If there is a potential for this to happen, choose the Statistics feature instead.

Statistics

The mean, standard deviation, skewness and excess kurtosis of the grey-value image intensities across the object. This feature has 4 values, grey must be scalar.

A stable algorithm is used that prevents catastrophic cancellation, see dip::StatisticsAccumulator.

DirectionalStatistics

The directional mean and standard deviation of the grey-value image intensities across the object. Directional statistics assume the input values are angles. This feature has 2 values, grey must be scalar.

MaxVal

The maximum grey-value image intensity within the object. The grey image can be a tensor image, one value per tensor element (channel) is produced.

MinVal

The minimum grey-value image intensity within the object. The grey image can be a tensor image, one value per tensor element (channel) is produced.

MaxPos

The position of the pixel with maximum intensity within the object. There is one value per image dimension. If the image has a known pixel size, the values represent the distances to the lower image edge along each dimension.

If multiple pixels have the same minimum value, the position of the first one encountered is returned. Note that the order in which pixels are examined depends on the image sizes and strides, and is not given by the linear index.

The grey image must be a scalar image.

MinPos

The position of the pixel with minimum intensity within the object. There is one value per image dimension. If the image has a known pixel size, the values represent the distances to the lower image edge along each dimension.

If multiple pixels have the same minimum value, the position of the first one encountered is returned. Note that the order in which pixels are examined depends on the image sizes and strides, and is not given by the linear index.

The grey image must be a scalar image.

Moments of binary object

Size

The Size feature is the zero order moment of the binary object.

Center

Coordinates of the geometric mean (centroid) of the object (with sub-pixel precision), which is the first order normalized moment of the binary shape. There is one value per image dimension. If the image has a known pixel size, the values represent the distances to the lower image edge along each dimension.

Mu

Elements of the inertia tensor of the object, which is composed of second order normalized central moments of the binary shape. For an image with \(n\) dimensions, there are \(\frac{1}{2}n(n+1)\) values. These are stored in the same order as symmetric tensors are stored in an image (see dip::Tensor::Shape).

For more information, see dip::MomentAccumulator::SecondOrder.

These values are reported in physical units, anisotropic pixels are taken into account, but they must have the same units, else pixel sizes are ignored. Note that we don’t handle different units along different axes here because none of the uses of the tensor would make sense.

Inertia

Moments of inertia of the binary object, the eigenvalues of the tensor computed by feature Mu. There is one value per image dimension. The eigenvectors are sorted largest to smallest.

These values are reported in physical units, anisotropic pixels are taken into account, but they must have the same units, else pixel sizes are ignored.

MajorAxes

Principal axes of the binary object, the eigenvectors of the tensor computed by feature Mu. For an image with \(n\) dimensions, there are \(n^2\) values. The first \(n\) values are the eigenvector associated to the largest eigenvalue, etc.

These values are reported in physical units, anisotropic pixels are taken into account, but they must have the same units, else pixel sizes are ignored.

DimensionsCube

Lengths of the sides of a rectangle (2D) or box (3D) with the same moments of inertia as the binary object. Derived from feature Inertia.

Currently defined only for 2D and 3D images.

These values are reported in physical units, anisotropic pixels are taken into account, but they must have the same units, else pixel sizes are ignored.

DimensionsEllipsoid

Diameters of an ellipse (2D) or ellipsoid (3D) with the same moments of inertia as the binary object. Derived from feature Inertia.

Currently defined only for 2D and 3D images.

These values are reported in physical units, anisotropic pixels are taken into account, but they must have the same units, else pixel sizes are ignored.

Moments of grey-value object

GreySize

The zero order moment of the object. Same as the Mass feature, but multiplied by the physical size of a pixel. If object pixels have a value of 1, and background pixels have a value of 0, then this feature is the size of the grey-value object.

This value is reported in physical units, anisotropic pixels are taken into account.

Gravity

Coordinates of the center of mass of the object, which is the first order normalized moment of the binary shape weighted by the grey-value image’s intensities. There is one value per image dimension. If the image has a known pixel size, the values represent the distances of the center of mass to the lower image edge along each dimension.

Identical to feature Center but using the grey-value image as weighting. grey must be scalar.

GreyMu

Elements of the inertia tensor of the grey-weighted object, which is composed of second order normalized central moments of the binary shape weighted by the grey-value image’s intensities. For an image with \(n\) dimensions, there are \(\frac{1}{2}n(n+1)\) values. These are stored in the same order as symmetric tensors are stored in an image (see dip::Tensor::Shape).

For more information, see dip::MomentAccumulator::SecondOrder.

Identical to feature Mu but using the grey-value image as weighting. grey must be scalar.

These values are reported in physical units, anisotropic pixels are taken into account, but they must have the same units, else pixel sizes are ignored. Note that we don’t handle different units along different axes here because none of the uses of the tensor would make sense.

GreyInertia

Moments of inertia of the grey-weighted object, the eigenvalues of the tensor computed by feature GreyMu. There is one value per image dimension. The eigenvectors are sorted largest to smallest.

Identical to feature Inertia but using the grey-value image as weighting. grey must be scalar.

These values are reported in physical units, anisotropic pixels are taken into account, but they must have the same units, else pixel sizes are ignored.

GreyMajorAxes

Principal axes of the grey-weighted object, the eigenvectors of the tensor computed by feature GreyMu. For an image with \(n\) dimensions, there are \(n^2\) values. The first \(n\) values are the eigenvector associated to the largest eigenvalue, etc.

Identical to feature MajorAxes but using the grey-value image as weighting. grey must be scalar.

These values are reported in physical units, anisotropic pixels are taken into account, but they must have the same units, else pixel sizes are ignored.

GreyDimensionsCube

Lengths of the sides of a rectangle (2D) or box (3D) with the same moments of inertia as the grey-weighted object. Derived from feature GreyInertia.

Currently defined only for 2D and 3D images.

Identical to feature DimensionsCube but using the grey-value image as weighting. grey must be scalar.

These values are reported in physical units, anisotropic pixels are taken into account, but they must have the same units, else pixel sizes are ignored.

GreyDimensionsEllipsoid

Diameters of an ellipse (2D) or ellipsoid (3D) with the same moments of inertia as the grey-weighted object. Derived from feature GreyInertia.

Currently defined only for 2D and 3D images.

Identical to feature DimensionsEllipsoid but using the grey-value image as weighting. grey must be scalar.

These values are reported in physical units, anisotropic pixels are taken into account, but they must have the same units, else pixel sizes are ignored.