Measurements and relationships

Measurement coverage is much broader than basic region properties. The Measurements builder selects feature families, checks image/frame contracts and assembles the required passes. Exact, approximate and resident computations have different memory behavior; name that choice alongside the output column.

Available operations

measure

Source.

Entry points: Measurements, ShapeSet, IntensitySet, MeasurementSourceFacts.

Per-label size, centroid, moments/principal axes, boundaries, contacts, topology and components; intensity/distribution summaries; granularity; GLCM/Haralick texture; Hu/Zernike and 3D moments; projected convex features. Relationships include overlap/assignment, centroid neighbors, boundary distances and expansion. Colocalization includes Pearson, Manders, Costes and rank-weighted variants.

Execution: Builder-generated block/reduction routes with source dtype/extent/physical-frame facts. Some exact distributions and object-local geometry retain values/support; inspect each selected family.

A feature selection is also an execution plan. Size and first moments can be accumulated in small per-label states. Texture requires specified offsets and neighboring intensity/label samples. Exact quantiles, convex support and some object-local descriptors retain more evidence. Selecting a broad feature set can therefore change both source footprints and reduction memory, even though the final output is only one row per label.

Use MeasurementSourceFacts to state the actual dtype, extent and physical frame of attached images. A distance between mismatched origins is wrong even when both have the same voxel pitch. Start with the few measurements needed for an example, inspect coverage/count fields, then add richer features whose state limits fit the object population. The builder’s validation is intended to expose unsupported combinations before execution.

tabulate

Source.

Entry points: TabulateValuesOp, TabulateLabelsOp, append_tabulate_phases, RegionShape.

Aggregate keyed counts, intensity totals and region moments into mergeable tables. Fixed-point accumulation and explicit signed-column encodings avoid silently treating typed words as ordinary floating-point values.

Execution: Planned block partials and merge phases; state scales with labels/keys.

What can be merged without raw voxels. Counts, sums and moment partials summarize each label’s intersection with a block. After merging by the exact key, the global mean or centroid follows from combined totals rather than an unweighted average of each block’s mean. Unequal block/object sizes make those two procedures differ.

The typed encoding distinguishes identifiers, fixed-point sums and ordinary floating scalars. Preserve that schema when composing row operations. A tabulation can be bounded by the number of distinct labels in each active block while the final keyed state still grows with the global label population. Use streaming/publication routes when the result table itself is too large to collect.

adjacency

Source.

Entry points: AdjacentPairsOp, adjacent_pairs, collect_pairs.

Enumerate touching label pairs with a defined forward-offset neighborhood. Merge per-block contact facts before interpreting global adjacency.

Execution: Planned local boundary reads and sparse pair reduction; contact population can grow with label count.

The halo covers contacts, not whole objects. A forward-offset neighborhood inspects each eligible voxel pair once, including pairs crossing a core face. The selected offsets determine the image margin, while the ownership rule prevents duplicate contacts from two overlapping read windows. No operation needs to load all voxels of both touching objects merely to record that contact.

Merge contacts for the same canonical label pair before deriving graph degree or boundary area. Excluding background and treating diagonal touching are separate choices. For physical area, use the appropriate face geometry; a count of arbitrary diagonal neighbor pairs is not automatically a physical interface area.

boundaries

Source.

Entry points: FindBoundariesOp, boundary_points, labelled_boundary_points.

Derive boundary masks or boundary-point records from labels using explicit connectivity and boundary mode. Boundary conventions should match the downstream distance or score definition.

Execution: Planned bounded-neighborhood mask and resident point helpers.

Boundary modes define different images. A voxel can be marked because it touches another label, because it belongs to the interior side of a transition, or according to the selected thick/thin convention. Connectivity specifies the offsets examined and therefore the finite margin needed around each output core.

Use the same convention when comparing predicted and reference boundaries or feeding boundary points into distance calculations. Otherwise a one-voxel convention difference can dominate a supposedly precise error measure. The resident point helpers materialize the chosen boundary population; for a huge dense boundary, that population can be substantially larger than a sparse object table.

point_distance

Source.

Entry points: MaskBoundaryOp, PointDistanceOp, append_point_distance_phases.

Measure signed point-to-mask boundary distances without producing a dense distance field. Supply physical pitch, inside test and distance cap; results distinguish exact, capped and missing boundaries.

Execution: Planned boundary fragments and bounded-radius neighboring fragment queries. A capped result is not an uncapped exact distance.

A distance cap changes what must be queried. With a physical cap d, no boundary farther than d can improve an exact result already inside that radius. reach_for converts the cap and anisotropic pitches into neighboring block counts. PointDistanceOp reads local mask support for sign and nearby boundary fragments for distance; a barrier separates that fragment dependence from a needlessly widened pixel read.

Report exact, capped and missing cases distinctly. A capped value certifies a lower bound or limited search outcome under the contract; it must not be averaged as if it were the true uncapped distance. This is useful for sparse bead-to-sheet measurements where computing and storing a dense distance field would be unnecessary.

Important limits

The direct Costes operation requests whole-volume sources; a pair-and-merge route still retains intensity pairs. Neither should be described as a constant-memory threshold estimator. Similarly, an exact per-object convex hull or distribution may need memory proportional to object support even when its image reads are blockwise.

Keep label IDs as integer columns. Some measurement scalar outputs have explicit representability/tolerance contracts because large integers cannot all be stored exactly in f64. Physical distances additionally require compatible source-frame facts; spacing alone is insufficient to establish alignment.