taufactor.metrics.connectivity

Functions

extract_through_feature(array, ...[, ...])

Extract spanning features and their fractions for a phase.

find_front_labels(labelled_array, axis)

Find features that are connected to the front of given axis

find_spanning_labels(labelled_array, axis)

Find labels that span the domain along an axis.

label_periodic(field, grayscale_value, ...)

Label connected components with periodic boundary conditions.
taufactor.metrics.connectivity.extract_through_feature(array, grayscale_value, axis, periodic=[False, False, False], connectivity=1, open_end=True, debug=False)[source]

Extract spanning features and their fractions for a phase.

For the given grayscale_value, labels connected components at one or more neighbor connectivities, detects which labels span the domain along axis, and returns boolean masks plus the fraction of the phase volume that is spanning.

Parameters:

  • array (numpy.ndarray) – 3D segmented image.

  • grayscale_value (int) – Target label value whose spanning network is evaluated.

  • axis (str) – One of 'x', 'y', or 'z' along which spanning is checked.

  • periodic (Sequence[bool], optional) – Periodicity flags per axis (e.g. (True, False, False)). Defaults to [False, False, False].

  • connectivity (int | None, optional) – If 1, 2, or 3, evaluate that connectivity only. If None, evaluates all (1, 2, 3). Defaults to 1.

  • debug (bool, optional) – Print simple diagnostics. Defaults to False.

Returns:

  • If the phase is present: a list of boolean masks (one per connectivity) indicating the spanning network, and a 1D array of spanning fractions (per connectivity) relative to the phase volume.

  • If the phase volume is zero: (0, 0).

Return type:

tuple[list[numpy.ndarray], numpy.ndarray] | tuple[int, int]

Notes

Connectivity meanings in 3D: - 1: faces (6-neighborhood), - 2: faces + edges (18-neighborhood), - 3: faces + edges + corners (26-neighborhood).

taufactor.metrics.connectivity.find_front_labels(labelled_array, axis)[source]

Find features that are connected to the front of given axis

Returns:

Labels that appear in the first slice of the given axis.

Return type:

set

taufactor.metrics.connectivity.find_spanning_labels(labelled_array, axis)[source]

Find labels that span the domain along an axis.

A label is considered spanning if it appears on both opposing faces along the specified axis; background label 0 is ignored.

Parameters:

  • labelled_array (numpy.ndarray) – Labeled 3D array.

  • axis (str) – One of 'x', 'y', or 'z'.

Returns:

Set of labels that appear on both faces along axis.

Return type:

set[int]

Raises:

ValueError – If axis is not one of 'x', 'y', 'z'.

taufactor.metrics.connectivity.label_periodic(field, grayscale_value, neighbour_structure, periodic, debug=False)[source]

Label connected components with periodic boundary conditions.

Wraps the image in periodic directions, labels connected components equal to grayscale_value, then merges labels that touch across periodic boundaries. Finally, crops back to the original shape.

Parameters:

  • field (numpy.ndarray) – Input array (2D or 3D).

  • grayscale_value (int | float) – Target value to label.

  • neighbour_structure (numpy.ndarray) – Structuring element as from scipy.ndimage.generate_binary_structure.

  • periodic (Sequence[bool]) – Periodicity flags per axis (e.g. (True, False, True)).

  • debug (bool, optional) – Print simple diagnostics. Defaults to False.

Returns:

Tuple (labels, num_labels) where labels is the cropped labeled array and num_labels is the number of connected components after periodic merging.

Return type:

tuple[numpy.ndarray, int]