# 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

Computes the number of object pixels. If the image has a known pixel size, the number of pixels is multiplied by the area of each pixel to give an unbiased estimate of the object’s area (2D), volume (3D), or hyper-volume (nD).

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

### 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`

.

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.

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: , where is the perimeter and is the area.
- 3D: , where is the surface area and 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 , where is the solid area and 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, . - 1:
`Circle`

, similarity to a circle, . - 2:
`Triangle`

, similarity to a triangle, . - 3:
`Ellipse`

, similarity to an ellipse, . - 4:
`Elongation`

, object elongation, .

where is the object area, the perimeter, the largest Feret diameter, the
smallest Feret diameter, and 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.

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
, with the largest eigenvalue
and the smallest eigenvalue of the covariance matrix of the boundary
pixels of the object.

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.

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 dimensions,
there are 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 dimensions, there are values. The first 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.

## 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 dimensions, there are 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.

### GreyMajorAxes

Principal axes of the grey-weighted object, the eigenvectors of the tensor computed by feature GreyMu. For an image with dimensions, there are values. The first 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.

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

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