taufactor.metrics.particles

Functions

estimate_3d_psd_saltykov(apparent_diameters)	Estimate a 3D sphere diameter distribution from 2D section diameters.
particle_size_distribution(labelled_array[, ...])	Measure 3D particle volumes, equivalent sphere diameters, and sphericity.
particle_size_distribution_2d(labelled_array)	Measure 2D particle areas, equivalent circle diameters, and circularity.
relabel_random_order(array)	Relabel an array with shuffled consecutive integer labels.
relabel_sequential(array)	Relabel an array with consecutive integer labels.
remove_boundary_features(labelled_array[, ...])	Remove labeled features that touch the domain boundary.
split_lumped_labels(labelled_array[, ...])	Split groups of particles with one lumped label into new labels.

taufactor.metrics.particles.estimate_3d_psd_saltykov(apparent_diameters, bins='auto', bin_edges=None, clip_negative=True, normalize=True)

Estimate a 3D sphere diameter distribution from 2D section diameters.

Uses a Saltykov-style unfolding under the assumption of spherical particles cut by a random plane.

Parameters:

• apparent_diameters – 1D array of apparent 2D section diameters.

• bins – Histogram bin spec passed to numpy.histogram_bin_edges when bin_edges is not provided.

• bin_edges – Explicit histogram bin edges.

• clip_negative – If True, clip negative unfolded counts to zero.

• normalize – If True, also return normalized bin fractions.

Returns:

Bin edges, centers, 2D histogram counts, and unfolded 3D counts.

Return type:

dict

taufactor.metrics.particles.particle_size_distribution(labelled_array, spacing=(1, 1, 1), periodic=(False, False, False), compute_sphericity=False, surface_area_method='gradient', return_field=False, relabel=True, warn=True)

Measure 3D particle volumes, equivalent sphere diameters, and sphericity.

Parameters:

• labelled_array – 3D labeled particle array with background label 0.

• spacing – Voxel spacing (dx, dy, dz). Defaults to (1, 1, 1).

• periodic – Periodicity flags for (x, y, z). Periodic axes are ignored when removing boundary-touching labels.

• compute_sphericity – If True, also compute particle surface areas and sphericity values.

• surface_area_method – Surface-area method passed to specific_surface_area(). Defaults to 'gradient'.

• relabel – If True, relabel surviving particles consecutively.

• warn – If True, warn when boundary removal discards more than half of the particles or more than half of the particle mass.

Returns:

Particle analysis results with cleaned labels, per-particle volumes, equivalent diameters, and optional surface areas and sphericity.

Return type:

dict

taufactor.metrics.particles.particle_size_distribution_2d(labelled_array, spacing=(1, 1), return_field=False, relabel=True, warn=True, perimeter_method='crofton')

Measure 2D particle areas, equivalent circle diameters, and circularity.

Parameters:

• labelled_array – 2D labeled particle array with background label 0.

• spacing – Pixel spacing (dx, dy). Defaults to (1, 1).

• return_field – If True, include the filtered labeled image.

• relabel – If True, relabel surviving particles consecutively.

• warn – If True, warn when edge removal discards more than half of the particles or more than half of the particle area.

• perimeter_method – Either 'crofton' or 'standard'.

Returns:

Particle analysis results with per-particle areas, equivalent diameters, perimeters, and circularity.

Return type:

dict

taufactor.metrics.particles.relabel_random_order(array)

Relabel an array with shuffled consecutive integer labels.

Parameters:

array – Input labeled array.

Returns:

Array with labels remapped to consecutive integers in random order. If label 0 is present, it remains 0.

taufactor.metrics.particles.relabel_sequential(array)

Relabel an array with consecutive integer labels.

taufactor.metrics.particles.remove_boundary_features(labelled_array, verbose=True, periodic=(False, False, False))

Remove labeled features that touch the domain boundary.

Parameters:

• labelled_array – 3D array of connected-component labels, where 0 is background and each feature has its own positive integer label.

• verbose – If True, print how many labels remain after filtering.

• periodic – Periodicity flags for (x, y, z). Periodic axes are ignored when checking boundary contact.

Returns:

A new array where all boundary-touching labels have been set to 0.

Raises:

ValueError – If the input does not look like a labeled array with background plus at least two feature labels.

taufactor.metrics.particles.split_lumped_labels(labelled_array, connectivity=1, background=0, verbose=True, return_report=False)

Split groups of particles with one lumped label into new labels.

Parameters:

• labelled_array – 2D or 3D labeled array.

• connectivity – Connectivity passed to scipy.ndimage.label.

• background – Background label to ignore. Defaults to 0.

• verbose – If True, print a short summary.

• return_report – If True, also return a summary of the applied splits.

Returns:

A relabeled copy of the input array, optionally with a report describing the performed splits.

Return type:

numpy.ndarray | tuple[numpy.ndarray, dict]