dip::Polygon struct

A polygon with floating-point vertices.

Derived classes

struct dip::ConvexHull
A convex hull is a convex polygon. It can be constructed from a simple dip::Polygon, and is guaranteed clockwise.

Aliases

using Vertices = std::vector<VertexFloat>
Type used to store the vertices.

Functions

auto BoundingBox() const -> dip::BoundingBoxFloat
Returns the bounding box of the polygon.
auto IsClockWise() const -> bool
Determine the orientation of the polygon.
auto Area() const -> dip::dfloat
Computes the (signed) area of the polygon. The default, clockwise polygons have a positive area.
auto Centroid() const -> dip::VertexFloat
Computes the centroid of the polygon.
auto CovarianceMatrix(dip::VertexFloat const& g) const -> dip::CovarianceMatrix
Returns the covariance matrix for the vertices of the polygon, using centroid g.
auto CovarianceMatrix() const -> dip::CovarianceMatrix
Returns the covariance matrix for the vertices of the polygon.
auto Length() const -> dip::dfloat
Computes the length of the polygon (i.e. perimeter). If the polygon represents a pixelated object, this function will overestimate the object’s perimeter. In this case, use dip::ChainCode::Length instead.
auto Perimeter() const -> dip::dfloat
An alias for dip::Polygon::Length.
auto RadiusStatistics() const -> dip::RadiusValues
Returns statistics on the radii of the polygon. The radii are the distances between the centroid and each of the vertices.
auto RadiusStatistics(dip::VertexFloat const& g) const -> dip::RadiusValues
Returns statistics on the radii of the polygon. The radii are the distances between the given centroid and each of the vertices.
auto EllipseVariance() const -> dip::dfloat
Compares a polygon to the ellipse with the same covariance matrix, returning the coefficient of variation of the distance of vertices to the ellipse.
auto EllipseVariance(dip::VertexFloat const& g, dip::CovarianceMatrix const& C) const -> dip::dfloat
Compares a polygon to the ellipse described by the given centroid and covariance matrix, returning the coefficient of variation of the distance of vertices to the ellipse.
auto FractalDimension(dip::dfloat length = 0) const -> dip::dfloat
Computes the fractal dimension of a polygon.
auto BendingEnergy() const -> dip::dfloat
Computes the bending energy of a polygon.
auto Simplify(dip::dfloat tolerance = 0.5) -> dip::Polygon&
Simplifies the polygon using the Douglas-Peucker algorithm.
auto Augment(dip::dfloat distance = 1.0) -> dip::Polygon&
Adds vertices along each edge of the polygon such that the distance between two consecutive vertices is never more than distance.
auto Smooth(dip::dfloat sigma = 1.0) -> dip::Polygon&
Locally averages the location of vertices of a polygon so it becomes smoother.
auto Reverse() -> dip::Polygon&
Reverses the orientation of the polygon, converting a clockwise polygon into a counter-clockwise one and vice versa.
auto Rotate(dip::dfloat angle) -> dip::Polygon&
Rotates the polygon around the origin by angle, which is positive for clockwise rotation.
auto Scale(dip::dfloat scale) -> dip::Polygon&
Scales the polygon isotropically by multiplying each vertex coordinate by scale.
auto Scale(dip::dfloat scaleX, dip::dfloat scaleY) -> dip::Polygon&
Scales the polygon anisotropically by multiplying each vertex coordinate by scaleX and scaleY.
auto Translate(dip::VertexFloat shift) -> dip::Polygon&
Translates the polygon by shift.
auto ConvexHull() const -> dip::ConvexHull
Returns the convex hull of the polygon. The polygon must be simple.

Variables

dip::Polygon::Vertices vertices
The vertices.

Function documentation

bool IsClockWise() const

Determine the orientation of the polygon.

This is a fast algorithm that assumes that the polygon is simple. Non-simple polygons do not have a single orientation anyway.

If the polygon is constructed from a chain code, this function should always return true.

dip::dfloat EllipseVariance() const

Compares a polygon to the ellipse with the same covariance matrix, returning the coefficient of variation of the distance of vertices to the ellipse.

dip::dfloat FractalDimension(dip::dfloat length = 0) const

Computes the fractal dimension of a polygon.

Fractal dimension is defined as the slope of the polygon length as a function of scale, in a log-log plot. Scale is obtained by smoothing the polygon using dip::Polygon::Smooth. Therefore, it is important that the polygon be densely sampled, use dip::Polygon::Augment if necessary.

length is the length of the polygon (see dip::Polygon::Length). It determines the range of scales used to compute the fractal dimension, so a rough estimate is sufficient. If zero is given as length (the default value), then it is computed.

dip::dfloat BendingEnergy() const

Computes the bending energy of a polygon.

The bending energy is the integral along the contour of the square of the curvature. We approximate curvature by, at each vertex, taking the difference in angle between the two edges, and dividing by half the length of the two edges (this is the portion of the boundary associated to the edge).

Note that this approximation is poor when the points are far apart. dip::Polygon::Augment should be used to obtain a densely sampled polygon. It is also beneficial to sufficiently smooth the polygon so it better approximates a smooth curve around the object being measured, see dip::Polygon::Smooth.

dip::Polygon& Simplify(dip::dfloat tolerance = 0.5)

Simplifies the polygon using the Douglas-Peucker algorithm.

For a polygon derived from a chain code, setting tolerance to 0.5 leads to a maximum-length digital straight segment representation of the object.

dip::Polygon& Smooth(dip::dfloat sigma = 1.0)

Locally averages the location of vertices of a polygon so it becomes smoother.

Uses a Gaussian filter with parameter sigma, which is not interpreted as a physical distance between vertices, but as a distance in number of vertices. That is, the neighboring vertex is at a distance of 1, the next one over at a distance of 2, etc. Therefore, it is important that vertices are approximately equally spaced. dip::Polygon::Augment modifies any polygon to satisfy that requirement.

A polygon derived from the chain code of an object without high curvature, when smoothed with a sigma of 2, will fairly well approximate the original smooth boundary. For objects with higher curvature (including very small objects), choose a smaller sigma.