Morphology Concepts

This page defines the terms used by the public mtlearn API and the CFP layer documentation.

Morphological Trees

A morphological tree is a hierarchy of connected components derived from an image. Each node represents a component or shape, and parent-child relations encode inclusion in the hierarchy. mtlearn currently builds max-trees, min-trees, and trees of shapes through mtlearn.morphology.

Max-Tree and Min-Tree

A max-tree organizes upper level sets of a gray-scale image. It is useful when bright components are the primary structures of interest. A min-tree organizes lower level sets and is useful when dark components are the primary structures.

Both tree types are component trees. Their construction accepts an adjacency radius, exposed as radius in the native tree constructors.

Tree of Shapes

A tree of shapes is self-dual: it represents bright and dark structures in one hierarchy instead of choosing max-tree or min-tree polarity. The current API exposes interpolation choices with ToSInterpolation and string aliases such as "self-dual", "min4c-max8c", and "min8c-max4c".

Node Ids and Node Slots

NodeId values identify nodes in the morphology backend. Some arrays are indexed by live tree nodes, while attribute and CFP arrays usually use the backend node-slot domain. When allocating a node-indexed criterion, attribute vector, or CFP tensor, use numInternalNodeSlots rather than numNodes.

The distinction matters after pruning or merging: a tree can have inactive slots even when the live node count changes.

Proper Parts

Proper parts are pixel-level ownership elements used by the backend topology. For ordinary 2D image use, they can be understood as flattened image pixels owned by tree nodes. Methods such as proper_part_owner_of(pixel_id) expose this mapping for inspection and debugging.

Scalar Attributes and Groups

A scalar attribute is one node-level measurement such as AREA, GRAY_HEIGHT, COMPACTNESS, or CONTOUR_PERIMETER.

An attribute group is a named bundle of scalar attributes, such as AttributeGroup.SHAPE or AttributeGroup.TREE_TOPOLOGY. Groups are expanded before attribute computation or CFP parameter construction.

For tree-of-shapes CFP filters, the current backend omits unsupported scalar members such as explicit MAX_DIST when expanding broad groups.

See Attribute Catalog for the user-facing attribute catalog.

Dataset Statistics and Caching

The primary CFP layer can cache tree metadata and raw attributes by stable dataset index. build_dataloader_cached wraps a DataLoader so each sample carries its index, then precomputes tree payloads and dataset-level normalization statistics. Once the prepass finishes, statistics are frozen and cached normalized attributes are refreshed.