|
mmcfilters
Public API documentation
|
The distance-transform subsystem is topology-only and requires a non-empty regular 2D tree domain. It measures every node support against its foreground A4 contour in the original image grid. Tree-construction adjacency and node altitudes do not change this metric.
Two coordinated families are public:
MAX_DIST, select the adaptive-A8 DIFT approximation;_EXACT, such as MAX_DIST_EXACT, select the exact Euclidean distance transform, whose internal cost field is squared.AttributeGroup::DistTransf in C++ and Attribute.Group.DIST_TRANSF in Python contain the 29 approximate scalars. AttributeGroup::DistTransfExact and Attribute.Group.DIST_TRANSF_EXACT contain the 29 matching exact scalars. Request both groups to obtain all 58 attributes. Results follow canonical scalar-ordinal order; see Attributes for result layouts.
For a node support X, write z(x) = d(x)^2, where d(x) is the Euclidean distance in pixels from x to the foreground A4 contour of X. In the approximate family, z denotes the corresponding adaptive-A8 DIFT cost. Let n = |X|.
The maximum and squared-distance summaries are:
MAX_DIST = sqrt(max z) = max d;MAX_SQUARED_DIST = max z;DIST_SQUARED_SUM = sum z;DIST_SQUARED_MEAN = (sum z) / n;DIST_RMS = sqrt(DIST_SQUARED_MEAN);DIST_SQUARED_VARIANCE = mean(z^2) - mean(z)^2.The real-distance summaries use d = sqrt(z):
DIST_SUM = sum d;DIST_MEAN = (sum d) / n;DIST_VARIANCE = mean(d^2) - mean(d)^2.The maximum center is the smallest row-major support pixel among tied maximizers. Maximum-plateau area counts every maximizer, and plateau centroid coordinates are arithmetic means, so they may be fractional.
The sparse histogram stores (z, count) bins in increasing squared-distance order. DIST_MEDIAN, DIST_Q25, DIST_Q75, and DIST_Q90 are lower empirical quantiles of d: the smallest distance whose cumulative count reaches ceil(p*n). DIST_MODE chooses the smallest distance when frequencies tie. DIST_ENTROPY is Shannon entropy in bits. DIST_POSITIVE_AREA counts samples with z > 0, and DIST_LEVEL_COUNT counts represented squared-distance levels, including zero.
Spatial descriptors use weight w(x) = d(x). The row and column centroids are sum(w*coordinate) / sum(w). If every distance is zero, the centroid falls back to the ordinary support centroid and all weighted central moments are zero.
DIST_WEIGHTED_CENTRAL_MOMENT_20 is the unnormalized weighted column spread, DIST_WEIGHTED_CENTRAL_MOMENT_02 is the unnormalized weighted row spread, and DIST_WEIGHTED_CENTRAL_MOMENT_11 is the unnormalized row-column mixed moment. Axis orientation is reported in degrees. Eccentricity is the major/minor second-moment eigenvalue ratio: isotropic or point-degenerate fields return 1, and line-degenerate fields saturate at 1e6.
Every name above has an exact counterpart obtained by appending _EXACT.
| Quantity | Unit |
|---|---|
| maximum distance | pixels |
| maximum squared distance, squared mean | pixel² |
| squared sum | pixel² accumulated over support samples |
| squared-distance variance | pixel⁴ |
| real-distance sum, mean, quantiles, mode, RMS | pixels |
| real-distance variance | pixel² |
| entropy | bits |
| areas and level counts | counts |
| centroids | zero-based pixel coordinates |
| weighted central moments | pixel³ |
| orientation | degrees |
| eccentricity | dimensionless |
The scalar attribute pipeline returns one value per node. When an application needs the underlying transform, the C++ API also exposes topology-only owning results:
NodeDistanceField contains the support pixels of one live node and their aligned squared distances z. denseSquaredDistances materializes the original 2D domain and uses the caller-provided value outside the node support.
DistanceTransformProfiles contains a sorted sparse histogram for every live node. A histogram bin is (z, count). A survival bin is (z, countAtOrAbove) and therefore gives the support area whose squared distance is at least z.
Both results accept exact and approximate accuracy. Exact single-node field computation transforms only the requested support after constructing the shared topology indexes. Approximate single-node field computation follows the hierarchy-wide DIFT and retains only the requested result. Profile computation materializes all-node histograms. These APIs accept any supported hierarchy with a committed, non-empty regular 2D domain; node altitudes are not read.
The equivalent Python entry points accept either "exact", "approximate", or DistanceTransformAccuracy:
1.9.8