Attribute Catalog¶

This catalog lists the scalar attributes exposed through mtlearn.morphology.AttributeType and the groups exposed through mtlearn.morphology.AttributeGroup.

Attributes are computed per morphology-tree node slot. They are not image arrays. The usual result layout is:

attribute_index, values = morphology.compute_attributes(tree, attributes)
column = attribute_index["AREA"]
area_by_node_slot = values[:, column]

Attribute buffers default to np.float32. Pass dtype=np.float64 to compute_attributes or compute_single_attribute when double-precision attribute values are needed. Deterministic attribute filters accept both float32 and float64 attribute vectors.

Use tree.numInternalNodeSlots when allocating criteria, scores, or any node-indexed array that will be passed back to filtering code.

Terminology¶

A morphology tree has two kinds of elements:

Proper parts are the image-domain elements. For 2D images, each proper part is one pixel identified by its row-major linear index.
Internal tree nodes represent connected components or shapes built from those proper parts. These are the rows addressed by attribute vectors.

A node slot is the dense integer row used internally for one internal tree node. Attribute arrays keep one row per slot so the same id can be reused by filters, scores, CFP parameters, and reconstruction code. In ordinary trees these slots correspond to live internal nodes; after advanced topology edits, some slots may be kept for stable indexing.

The support of a node is the set of image pixels represented by that node: the pixels directly owned by the node plus the pixels represented by its descendant nodes. In a max-tree or min-tree, this support is the connected component associated with that tree node at its altitude.

Attribute Groups¶

Groups are convenience requests. They expand to canonical scalar attributes before computation or CFP parameter construction. Aliases such as ALTITUDE resolve to their canonical attribute, LEVEL, and do not create an additional column.

Group	Meaning
`GRAY_LEVEL`	Altitude and gray-level statistics.
`SHAPE`	Size, bounding box, moment, bitquad, contour, and selected shape descriptors.
`MOMENTS`	Central moments, Hu invariants, and moment-derived descriptors.
`BOUNDARY`	Bitquad and contour descriptors.
`TREE_TOPOLOGY`	Parent/child hierarchy descriptors.
`ALL`	Every public scalar attribute.

shape_attrs = morphology.expand_attribute_group(
    morphology.AttributeGroup.SHAPE,
)

Contracts¶

The catalog uses three contracts:

Contract	Meaning
Altitude-aware	Reads node altitude or gray-level values from a weighted tree.
Support/geometry	Reads the pixel support of each node, coordinates, contour, or adjacency information.
Tree topology	Reads only parent/child relations in the hierarchy.

Some support/geometry attributes require metadata that is not meaningful for every tree type. For example, MAX_DIST is currently intended for max-trees and min-trees with adjacency metadata, not generic tree-of-shapes CFP filters.

Gray-Level Attributes¶

Attribute	Groups	Contract	Use
`LEVEL`	`GRAY_LEVEL`	Altitude-aware	Node altitude. In component trees, this is the gray level at which the component appears.
`ALTITUDE`	`GRAY_LEVEL`	Altitude-aware	Python alias for `LEVEL` when exposed by the native enum.
`VOLUME`	`GRAY_LEVEL`	Altitude-aware	Gray-level mass accumulated over the node support. Useful for contrast weighted by size.
`RELATIVE_VOLUME`	`GRAY_LEVEL`	Altitude-aware	Contrast-like volume relative to parent/child altitude jumps.
`GRAY_HEIGHT`	`GRAY_LEVEL`	Altitude-aware	Gray-level span from the node to its most extreme descendant.
`MEAN_LEVEL`	`GRAY_LEVEL`	Altitude-aware	Mean gray level over the full support represented by the node.
`VARIANCE_LEVEL`	`GRAY_LEVEL`	Altitude-aware	Gray-level variance over the node support.

Gray-level attributes are good choices when the filter should depend on contrast, intensity, or altitude differences rather than pure geometry.

Size and Bounding-Box Attributes¶

Attribute	Groups	Contract	Use
`AREA`	`SHAPE`	Support/geometry	Number of pixels in the full node support, including descendant supports. For image trees, this is the connected-component size.
`BOX_WIDTH`	`SHAPE`	Support/geometry	Width of the smallest axis-aligned bounding box around the support.
`BOX_HEIGHT`	`SHAPE`	Support/geometry	Height of the smallest axis-aligned bounding box around the support.
`DIAGONAL_LENGTH`	`SHAPE`	Support/geometry	Bounding-box diagonal length.
`RECTANGULARITY`	`SHAPE`	Support/geometry	How densely the support fills its bounding box.
`RATIO_WH`	`SHAPE`	Support/geometry	Bounding-box aspect ratio.
`BOX_COL_MIN`	`SHAPE`	Support/geometry	Minimum image column covered by the support.
`BOX_COL_MAX`	`SHAPE`	Support/geometry	Maximum image column covered by the support.
`BOX_ROW_MIN`	`SHAPE`	Support/geometry	Minimum image row covered by the support.
`BOX_ROW_MAX`	`SHAPE`	Support/geometry	Maximum image row covered by the support.
`MAX_DIST`	`SHAPE`	Support/geometry	Maximum distance-transform style descriptor from contour information. Prefer max-tree/min-tree use.

AREA is the usual attribute for size filtering. A high AREA value means that the component represented by the node covers many pixels in the original image domain; it is not the number of children in the tree.

These attributes are the most direct tools for area openings, size priors, and filters that should keep or remove elongated connected components.

Moment Attributes¶

Attribute	Groups	Contract	Use
`CENTRAL_MOMENT_20`	`MOMENTS`, `SHAPE`	Support/geometry	Horizontal second-order spread around the support centroid.
`CENTRAL_MOMENT_02`	`MOMENTS`, `SHAPE`	Support/geometry	Vertical second-order spread around the support centroid.
`CENTRAL_MOMENT_11`	`MOMENTS`, `SHAPE`	Support/geometry	Mixed second-order moment, similar to covariance.
`CENTRAL_MOMENT_30`	`MOMENTS`, `SHAPE`	Support/geometry	Horizontal third-order asymmetry.
`CENTRAL_MOMENT_03`	`MOMENTS`, `SHAPE`	Support/geometry	Vertical third-order asymmetry.
`CENTRAL_MOMENT_21`	`MOMENTS`, `SHAPE`	Support/geometry	Combined horizontal spread and vertical asymmetry.
`CENTRAL_MOMENT_12`	`MOMENTS`, `SHAPE`	Support/geometry	Combined vertical spread and horizontal asymmetry.
`HU_MOMENT_1`	`MOMENTS`, `SHAPE`	Support/geometry	First Hu invariant. Useful as a compactness-like invariant descriptor.
`HU_MOMENT_2`	`MOMENTS`, `SHAPE`	Support/geometry	Second Hu invariant, sensitive to anisotropy.
`HU_MOMENT_3`	`MOMENTS`, `SHAPE`	Support/geometry	Third Hu invariant, sensitive to skewness patterns.
`HU_MOMENT_4`	`MOMENTS`, `SHAPE`	Support/geometry	Fourth Hu invariant, sensitive to off-axis symmetry.
`HU_MOMENT_5`	`MOMENTS`, `SHAPE`	Support/geometry	Fifth Hu invariant, sensitive to complex asymmetry.
`HU_MOMENT_6`	`MOMENTS`, `SHAPE`	Support/geometry	Sixth Hu invariant, combining second- and third-order moments.
`HU_MOMENT_7`	`MOMENTS`, `SHAPE`	Support/geometry	Seventh Hu invariant, often sensitive to fine asymmetries and reflection.
`INERTIA`	`MOMENTS`, `SHAPE`	Support/geometry	Moment-derived dispersion descriptor.
`COMPACTNESS`	`MOMENTS`, `SHAPE`	Support/geometry	Compactness of the support relative to its second-order dispersion.
`ECCENTRICITY`	`MOMENTS`, `SHAPE`	Support/geometry	Elongation from the second-moment matrix.
`LENGTH_MAJOR_AXIS`	`MOMENTS`, `SHAPE`	Support/geometry	Major-axis length proxy from the equivalent ellipse.
`LENGTH_MINOR_AXIS`	`MOMENTS`, `SHAPE`	Support/geometry	Minor-axis length proxy from the equivalent ellipse.
`AXIS_ORIENTATION`	`MOMENTS`, `SHAPE`	Support/geometry	Principal-axis orientation.
`CIRCULARITY`	`MOMENTS`, `SHAPE`	Support/geometry	Isotropy ratio. Values closer to one indicate rounder supports.

Moment descriptors are useful when area alone is too coarse and the filter should react to shape geometry.

Boundary and Bitquad Attributes¶

Attribute	Groups	Contract	Use
`BITQUADS_AREA`	`BOUNDARY`, `SHAPE`	Support/geometry	Sub-pixel area estimator derived from local 2x2 bitquad patterns.
`BITQUADS_NUMBER_EULER`	`BOUNDARY`, `SHAPE`	Support/geometry	Euler-characteristic estimate from bitquad counts.
`BITQUADS_NUMBER_HOLES`	`BOUNDARY`, `SHAPE`	Support/geometry	Hole-count estimate derived from the bitquad Euler descriptor.
`BITQUADS_PERIMETER`	`BOUNDARY`, `SHAPE`	Support/geometry	Discrete perimeter estimate from bitquad patterns.
`BITQUADS_PERIMETER_CONTINUOUS`	`BOUNDARY`, `SHAPE`	Support/geometry	Smoothed perimeter estimate from bitquad counts.
`BITQUADS_CIRCULARITY`	`BOUNDARY`, `SHAPE`	Support/geometry	Roundness descriptor based on bitquad area and perimeter.
`BITQUADS_PERIMETER_AVERAGE`	`BOUNDARY`, `SHAPE`	Support/geometry	Average perimeter proxy.
`BITQUADS_LENGTH_AVERAGE`	`BOUNDARY`, `SHAPE`	Support/geometry	Average longitudinal extent proxy.
`BITQUADS_WIDTH_AVERAGE`	`BOUNDARY`, `SHAPE`	Support/geometry	Average transverse extent proxy.
`CONTOUR_PIXELS`	`BOUNDARY`, `SHAPE`	Support/geometry	Number of support pixels touching the 4-neighbour complement.
`CONTOUR_PERIMETER`	`BOUNDARY`, `SHAPE`	Support/geometry	Number of exposed 4-neighbour sides over the support.
`CONTOUR_SIDE_NORTH`	`BOUNDARY`, `SHAPE`	Support/geometry	Exposed north-facing sides.
`CONTOUR_SIDE_WEST`	`BOUNDARY`, `SHAPE`	Support/geometry	Exposed west-facing sides.
`CONTOUR_SIDE_EAST`	`BOUNDARY`, `SHAPE`	Support/geometry	Exposed east-facing sides.
`CONTOUR_SIDE_SOUTH`	`BOUNDARY`, `SHAPE`	Support/geometry	Exposed south-facing sides.

Boundary attributes are useful when perimeter, holes, or contour exposure are more informative than raw area.

Tree-Topology Attributes¶

Attribute	Groups	Contract	Use
`HEIGHT_NODE`	`TREE_TOPOLOGY`	Tree topology	Longest child-edge path from the node to any leaf in its subtree.
`DEPTH_NODE`	`TREE_TOPOLOGY`	Tree topology	Number of parent-edge steps from the node to the root.
`IS_LEAF_NODE`	`TREE_TOPOLOGY`	Tree topology	Boolean scalar encoded as one for leaves and zero otherwise.
`IS_ROOT_NODE`	`TREE_TOPOLOGY`	Tree topology	Boolean scalar encoded as one for the root and zero otherwise.
`NUM_CHILDREN_NODE`	`TREE_TOPOLOGY`	Tree topology	Number of direct children.
`NUM_SIBLINGS_NODE`	`TREE_TOPOLOGY`	Tree topology	Number of other nodes with the same parent.
`NUM_DESCENDANTS_NODE`	`TREE_TOPOLOGY`	Tree topology	Number of internal tree nodes below this node.
`NUM_LEAF_DESCENDANTS_NODE`	`TREE_TOPOLOGY`	Tree topology	Number of leaf nodes in the node subtree.
`LEAF_RATIO_NODE`	`TREE_TOPOLOGY`	Tree topology	Ratio of leaf descendants to subtree size.
`BALANCE_NODE`	`TREE_TOPOLOGY`	Tree topology	Difference between deepest and shallowest child-subtree heights.
`AVG_CHILD_HEIGHT_NODE`	`TREE_TOPOLOGY`	Tree topology	Average height of direct child subtrees.

Tree-topology attributes ignore image coordinates and gray levels. They are useful when the hierarchy shape itself carries the signal.

Choosing Attributes¶

Start small:

use AREA for size filtering;
add GRAY_HEIGHT or VOLUME when contrast matters;
add COMPACTNESS, ECCENTRICITY, or RATIO_WH when component shape matters;
add TREE_TOPOLOGY attributes when hierarchy position matters;
use BOUNDARY attributes for contour- or hole-sensitive filters.

For CFP layers, each scalar attribute adds one trainable weight to the filter spec after group expansion.

filter_spec = {
    "name": "area_contrast_shape",
    "tree_type": "max-tree",
    "attributes": [
        morphology.AttributeType.AREA,
        morphology.AttributeType.GRAY_HEIGHT,
        morphology.AttributeType.COMPACTNESS,
    ],
}