pmmoto.filters package

Filters and morphological operations for PMMoTo.

Subpackages

• pmmoto.filters.distance package
  • edt()
  • edt2d()
  • edt3d()
  • Submodules
  • pmmoto.filters.distance.edt module
    • edt()
    • edt2d()
    • edt3d()

Submodules

pmmoto.filters.connected_components module

Connected components labeling and inlet/outlet connectivity utilities for PMMoTo.

Provides functions for labeling connected regions, mapping labels to phases, and extracting inlet/outlet-connected regions in distributed or periodic domains.

pmmoto.filters.connected_components.connect_components(img: NDArray[np.uint8], subdomain: Subdomain | PaddedSubdomain | VerletSubdomain) → tuple[NDArray[np.uint64], int]

Label connected components (sets) for all phases in img.

Note

Zero is background and will not join to any other voxel.

Parameters:

• img (np.ndarray) – Input binary image.

• subdomain – Subdomain object.

Returns:

(label_img, label_count) or label_img.

Return type:

tuple or np.ndarray

pmmoto.filters.connected_components.gen_img_to_label_map(img: ndarray[Any, dtype[uint8]], labeled_img: ndarray[Any, dtype[uint64]]) → dict[uint64, uint64]

Generate a mapping from label to phase for all labels.

Parameters:

• img (np.ndarray) – Input image.

• labeled_img (np.ndarray) – Labeled image.

Returns:

Mapping from label to phase.

Return type:

dict

pmmoto.filters.connected_components.inlet_connected_img(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, img: NDArray[np.uint8], phase: None | int = None) → NDArray[np.uint8]

Return an image where all voxels are connected to the inlet.

If phase is specified, all other phases are set to zero, leaving only connected voxels of the specified phase.

Parameters:

• subdomain – Subdomain object.

• img (np.ndarray) – Input image.

• phase (optional) – Phase to filter for.

Returns:

Image with only inlet-connected voxels.

Return type:

np.ndarray

pmmoto.filters.connected_components.inlet_outlet_connected_img(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, img: NDArray[np.uint8], phase: None | int = None) → NDArray[np.uint8]

Return an image where all voxels are connected to the inlet and outlet.

If phase is specified, all other phases are set to zero, leaving only connected voxels of the specified phase.

Parameters:

• subdomain – Subdomain object.

• img (np.ndarray) – Input image.

• phase (optional) – Phase to filter for.

Returns:

Image with inlet and outlet connected voxels.

Return type:

np.ndarray

pmmoto.filters.connected_components.isolated_img(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, img: NDArray[np.uint8], phase: None | int = None) → NDArray[np.uint8]

Return an image where all voxels are NOT connected to the inlet and outlet.

If phase is specified, all other phases are set to zero, leaving only NOT connected voxels of the specified phase.

Parameters:

• subdomain – Subdomain object.

• img (np.ndarray) – Input image.

• phase (optional) – Phase to filter for.

Returns:

Image with isolated voxels.

Return type:

np.ndarray

pmmoto.filters.connected_components.outlet_connected_img(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, img: NDArray[np.uint8], phase: None | int = None) → NDArray[np.uint8]

Return an image where all voxels are connected to the outlet.

If phase is specified, all other phases are set to zero, leaving only connected voxels of the specified phase.

Parameters:

• subdomain – Subdomain object.

• img (np.ndarray) – Input image.

• phase (optional) – Phase to filter for.

Returns:

Image with only outlet-connected voxels.

Return type:

np.ndarray

pmmoto.filters.connected_components.phase_count(phase_map: dict[int, int]) → dict[int, int]

Count the number of labels for each phase.

Parameters:

phase_map (dict) – Mapping from label to phase.

Returns:

Mapping from phase to count.

Return type:

dict

pmmoto.filters.equilibrium_distribution module

equilibrium_distribution.py

Morphological approaches for equilibrium fluid distributions in multiphase systems. Implements drainage simulation methods for various capillary pressure models.

pmmoto.filters.equilibrium_distribution.drainage(multiphase: Multiphase[np.uint8], capillary_pressures: int | float | list[float] | NDArray[np.floating[Any]], gamma: float = 1, contact_angle: float = 0, method: Literal['standard', 'contact_angle', 'extended_contact_angle'] = 'standard', mode: Literal['morph', 'hybrid', 'distance'] = 'hybrid', save: bool = False) → NDArray[np.float64]

Simulate morphological drainage for a multiphase system.

This function determines the equilibrium fluid distribution for a multiphase system using a morphological approach. The updated image is stored in multiphase.img.

Parameters:

• multiphase – Multiphase object with .img, .subdomain, .porous_media, etc.

• capillary_pressures (list or float) – List of capillary pressures Must be in increasing order.

• gamma (float, optional) – Surface tension parameter.

• contact_angle (float, optional) – Contact angle in degrees.

• method (str, optional) – Drainage method.

• mode (str, optional) – Morphological approach mode.

• save (bool, optional) – If True, save intermediate results.

Returns:

Wetting phase saturation at each capillary pressure.

Return type:

np.ndarray

pmmoto.filters.morphological_operators module

morphological_operators.py

Morphological operations for binary images, including dilation, erosion, opening, and closing, with support for parallel subdomains and FFT-based methods.

pmmoto.filters.morphological_operators.addition(subdomain: PaddedSubdomain | VerletSubdomain, img: NDArray[np.uint8], radius: float, fft: bool = False) → NDArray[np.uint8]

Perform a morphological dilation on a binary domain.

Parameters:

• subdomain – Subdomain object.

• img (np.ndarray) – Binary image.

• radius (float) – Dilation radius.

• fft (bool, optional) – Use FFT-based method if True.

Returns:

Dilated binary image.

Return type:

np.ndarray

pmmoto.filters.morphological_operators.closing(subdomain: PaddedSubdomain | VerletSubdomain, img: NDArray[np.uint8], radius: float, fft: bool = False) → NDArray[np.uint8]

Morphological closing (dilation followed by erosion).

Parameters:

• subdomain – Subdomain object.

• img (np.ndarray) – Binary image.

• radius (float) – Structuring element radius.

• fft (bool, optional) – Use FFT-based method if True.

Returns:

Closed binary image.

Return type:

np.ndarray

pmmoto.filters.morphological_operators.dilate(subdomain: PaddedSubdomain | VerletSubdomain, img: NDArray[np.uint8], radius: float, fft: bool = False) → NDArray[np.uint8]

Morphological dilation (addition).

Parameters:

• subdomain – Subdomain object.

• img (np.ndarray) – Binary image.

• radius (float) – Dilation radius.

• fft (bool, optional) – Use FFT-based method if True.

Returns:

Dilated binary image.

Return type:

np.ndarray

pmmoto.filters.morphological_operators.erode(subdomain: PaddedSubdomain | VerletSubdomain, img: NDArray[np.uint8], radius: float, fft: bool = False) → NDArray[np.uint8]

Morphological erosion (subtraction).

Parameters:

• subdomain – Subdomain object.

• img (np.ndarray) – Binary image.

• radius (float) – Erosion radius.

• fft (bool, optional) – Use FFT-based method if True.

Returns:

Eroded binary image.

Return type:

np.ndarray

pmmoto.filters.morphological_operators.gen_struct_element(resolution: tuple[float, ...], radius: float) → tuple[tuple[int, ...], ndarray[Any, dtype[uint8]]]

Generate the structuring element for FFT morphology approach.

Parameters:

• resolution (list or tuple) – Resolution in each dimension (2D or 3D).

• radius (float) – Radius of the structuring element.

Returns:

(struct_ratio, struct_element)

• struct_ratio: Array of structuring ratios.

• struct_element: 2D or 3D array representing the structuring element.

Return type:

tuple

Raises:

ValueError – If resolution is not isotropic or not length 2/3.

pmmoto.filters.morphological_operators.gen_struct_ratio(resolution: tuple[float, ...], radius: float) → tuple[int, ...]

Generate the structuring element dimensions for halo communication.

Parameters:

• resolution (list or tuple) – Resolution in each dimension (2D or 3D).

• radius (float) – Radius of the structuring element.

Returns:

Array of structuring ratios for each dimension.

Return type:

np.ndarray

Raises:

ValueError – If resolution is not length 2 or 3, or radius is too small.

pmmoto.filters.morphological_operators.opening(subdomain: PaddedSubdomain | VerletSubdomain, img: NDArray[np.uint8], radius: float, fft: bool = False) → NDArray[np.uint8]

Morphological opening (erosion followed by dilation).

Parameters:

• subdomain – Subdomain object.

• img (np.ndarray) – Binary image.

• radius (float) – Structuring element radius.

• fft (bool, optional) – Use FFT-based method if True.

Returns:

Opened binary image.

Return type:

np.ndarray

pmmoto.filters.morphological_operators.subtraction(subdomain: PaddedSubdomain | VerletSubdomain, img: NDArray[np.uint8], radius: float, fft: bool = False) → NDArray[np.uint8]

Perform a morphological subtraction (erosion) on a binary domain.

Parameters:

• subdomain – Subdomain object.

• img (np.ndarray) – Binary image.

• radius (float) – Erosion radius.

• fft (bool, optional) – Use FFT-based method if True.

Returns:

Eroded binary image.

Return type:

np.ndarray

pmmoto.filters.porosimetry module

porosimetry.py

Functions for pore size analysis and morphological porosimetry in PMMoTo.

pmmoto.filters.porosimetry.get_sizes(min_value: float, max_value: float, num_values: int, spacing: Literal['linear', 'log'] = 'linear') → ndarray[Any, dtype[floating[Any]]]

Generate a list of pore sizes based on input parameters.

Parameters:

• min_value (float) – Minimum pore size.

• max_value (float) – Maximum pore size.

• num_values (int) – Number of values to generate.

• spacing (str, optional) – “linear” or “log” spacing. Defaults to “linear”.

Returns:

Array of pore sizes in non-increasing order.

Return type:

np.ndarray

Raises:

ValueError – If input parameters are invalid.

pmmoto.filters.porosimetry.plot_pore_size_distribution(file_name: str, subdomain: PaddedSubdomain | VerletSubdomain, pore_size_image: NDArray[np.double], plot_type: Literal['cdf', 'pdf'] = 'pdf') → None

Plot and save the pore size distribution as a PNG.

Parameters:

• file_name – Output file base name.

• subdomain – Subdomain object.

• pore_size_image – Output from pore_size_distribution

• plot_type – cdf for cumulative or pdf for probability density.

Returns:

The matplotlib figure object if return_fig is True, otherwise None.

Return type:

Optional

pmmoto.filters.porosimetry.pore_size_distribution(subdomain: PaddedSubdomain | VerletSubdomain, porous_media: PorousMedia, radii: None | list[float] | NDArray[np.floating[Any]] = None, num_radii: int = 25, inlet: bool = False, mode: Literal['hybrid', 'distance', 'morph'] = 'hybrid') → NDArray[np.double]

Generate image where values are the radius of the largest sphere centered there.

Parameters:

• subdomain – Subdomain object.

• porous_media – Porous media object with .img and .distance attributes.

• radii (list or np.ndarray, optional) – List of radii to use. If None, computed from the distance.

• num_radii – If no radii are provided, the number to select based on distance.

• inlet (bool, optional) – If True, require connectivity to inlet.

• mode (str, optional) – “hybrid”, “distance”, or “morph”.

Returns:

Image with pore size values.

Return type:

np.ndarray

pmmoto.filters.porosimetry.porosimetry(subdomain: PaddedSubdomain | VerletSubdomain, porous_media: PorousMedia, radius: float | list[float], inlet: bool = False, multiphase: None | Multiphase[np.uint8] = None, mode: Literal['hybrid', 'distance', 'morph'] = 'hybrid') → NDArray[np.uint8]

Perform morphological porosimetry (erosion/dilation) on a porous medium.

Parameters:

• subdomain – Subdomain object.

• porous_media – Porous media object with .img and .distance attributes.

• radius (float or list) – Erosion/dilation radius or [erosion, dilation].

• inlet (bool, optional) – If True, require connectivity to inlet.

• multiphase (optional) – Optional multiphase constraint.

• mode (str, optional) – “hybrid”, “distance”, or “morph”.

Returns:

Resulting binary image after porosimetry.

Return type:

np.ndarray