taufactor.metrics

Functions

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

Extract spanning features and their fractions for a phase.

find_spanning_labels(labelled_array, axis)

Find labels that span the domain along an axis.

interfacial_areas(img[, spacing, method, ...])

label_periodic(field, grayscale_value, ...)

Label connected components with periodic boundary conditions.

specific_surface_area(img[, spacing, ...])

Compute specific surface area per phase.

triple_phase_boundary(img)

Compute triple-phase boundary (TPB) density.

volume_fraction(img[, phases])

Compute volume fractions for labels in a segmented image.
taufactor.metrics.extract_through_feature(array, grayscale_value, axis, periodic=[False, False, False], connectivity=1, 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.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.interfacial_areas(img, spacing=(1, 1, 1), method='face_counting', periodic=[False, False, False], normalize=True, device='cuda', smoothing=True, verbose=False)[source]
taufactor.metrics.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]

taufactor.metrics.specific_surface_area(img, spacing=(1, 1, 1), phases={}, method='gradient', periodic=[False, False, False], device='cuda', smoothing=True, verbose=False)[source]

Compute specific surface area per phase.

Supports three methods: - 'gradient' (default): Smooth binary masks and integrate gradient magnitude. - 'face_counting': Count voxel face changes between neighboring cells. - 'marching_cubes': Extract surfaces and compute mesh area (CPU-only; assumes

dx == dy == dz).

Parameters:

  • img (torch.Tensor | numpy.ndarray) – Labeled microstructure; integer values represent phases.

  • spacing (tuple[float, float, float], optional) – Voxel spacing (dx, dy, dz). Defaults to (1, 1, 1).

  • phases (dict[str, int], optional) – Mapping from phase name to the integer label in img. If empty, all labels are processed. Defaults to {}.

  • method (str, optional) – One of 'gradient', 'face_counting', or 'marching_cubes'. Defaults to 'gradient'.

  • device (str | torch.device, optional) – Device for GPU-accelerated methods. Only used for 'gradient'/'face_counting'. Defaults to 'cuda'.

  • smoothing (bool, optional) – Apply light Gaussian smoothing to the binary mask prior to measurement (used in 'gradient' and 'marching_cubes'). Defaults to True.

  • verbose (bool, optional) – Print simple memory usage diagnostics. Defaults to False.

Returns:

Mapping from phase name to specific surface area (surface per unit volume).

Return type:

dict[str, float]

Raises:

  • ImportError – If PyTorch is not available for 'gradient' or 'face_counting' methods.

  • ValueError – If method is invalid, or if 'marching_cubes' is used with anisotropic spacing (requires dx == dy == dz).

taufactor.metrics.triple_phase_boundary(img)[source]

Compute triple-phase boundary (TPB) density.

Calculates the fraction of voxel vertices/edges that are shared by at least three distinct phases. The input image must contain exactly three unique labels.

Parameters:

img (numpy.ndarray | torch.Tensor) – Segmented 2D or 3D image with exactly three phase labels.

Returns:

Triple-phase boundary density (normalized by the number of candidate vertices/edges).

Return type:

float

Raises:

  • ImportError – If PyTorch is not available.

  • ValueError – If the image does not contain exactly three phases.

taufactor.metrics.volume_fraction(img, phases={})[source]

Compute volume fractions for labels in a segmented image.

Calculates the fraction of voxels belonging to each phase. If phases is empty, all unique labels in img are measured. Otherwise, uses the provided mapping of phase names to label values.

Parameters:

  • img (torch.Tensor | numpy.ndarray) – Segmented image. If not a torch.Tensor, it will be converted to one.

  • phases (dict[str, int], optional) – Mapping from phase name to the integer label in img. If empty (default), all labels in the image are measured and names are derived from the label values.

Returns:

Mapping from phase name to volume fraction in the range [0, 1].

Return type:

dict[str, float]

Raises:

ImportError – If PyTorch is not available.