snow2

snow2(phases, phase_alias=None, boundary_width=3, accuracy='standard', voxel_size=1, sigma=0.4, r_max=4, peaks=None, parallelization={})

Applies the SNOW algorithm to each phase indicated in phases.

This function is a combination of snow [1], snow_dual [2], snow_n [3], and snow_parallel [4] from previous versions.

Parameters:

• phases (ndarray) – An image indicating the phase(s) of interest. A watershed is produced for each integer value in phases (except 0’s). These are then combined into a single image and one network is extracted using regions_to_network.

• phase_alias (dict) – A mapping between integer values in phases and phase name used to add labels to the network. For instance, asssuming a two-phase image, {1: 'void', 2: 'solid'} will result in the labels 'pore.void' and 'pore.solid', as well as 'throat.solid_void', 'throat.solid_solid', and 'throat.void_void'. If not provided, aliases are assumed to be {1: 'phase1', 2: 'phase2, ...}. Phase labels can also be applied afterward using label_phases.

• boundary_width (depends) –

  Number of voxels to add to the beginning and end of each axis. This argument can either be a scalar or a list. If a scalar is passed, it will be applied to the beginning and end of all axes. If a list, you can specify the number of voxels for each axis individually. Here are some examples:

  • [0, 3, 0]: 3 voxels only applied to the y-axis.

  • [0, [0, 3], 0]: 3 voxels only applied to the end of y-axis.

  • [0, [3, 0], 0]: 3 voxels only applied to the beginning of y-axis.

  The default is to add 3 voxels on both ends of all axes. For each boundary width that is not 0, a label will automatically be applied indicating which end of which axis (i.e. 'xmin' and 'xmax').

• accuracy (string) –

  Controls how accurately certain properties are calculated during the analysis of regions in the regions_to_network function. Options are:

  • ’standard’ (default)

    Computes the surface areas and perimeters by simply counting voxels. This is much faster but does not properly account for the rough voxelated nature of the surfaces.

  • ’high’

    Computes surface areas using the marching cube method, and perimeters using the fast marching method. These are substantially slower but better account for the voxelated nature of the images.

• voxel_size (scalar (default = 1)) – The resolution of the image, expressed as the length of one side of a voxel, so the volume of a voxel would be voxel_size-cubed.

• r_max (int) – The radius of the spherical structuring element to use in the Maximum filter stage that is used to find peaks. The default is 4.

• sigma (float) – The standard deviation of the Gaussian filter used in step 1. The default is 0.4. If 0 is given then the filter is not applied.

• peaks (ndarray, optional) – Optionally, it is possible to supply an array containing peaks, which are used as markers in the watershed segmentation. If a boolean array is received (True indicating peaks), then scipy.ndimage.label with cubic connectivity is used to label them. If an integer array is received then it is assumed the peaks have already been labelled. This allows for comparison of peak finding algorithms for instance. If this argument is provided, then r_max and sigma are ignored since these are specfically used in the peak finding process. This array should contain peaks for all phases, and they are masked by the phases argument. If peaks are provided the parallelization is disabled.

• parallelization (dict) – The arguments for controlling the parallelization of the watershed function are rolled into this dictionary, otherwise the function signature would become too complex. Refer to the docstring of snow_partitioning_parallel for complete details. If no values are provided then the defaults for that function are used here. To disable parallelization pass parallel=None, which will invoke the standard snow_partitioning or snow_partitioning_n. If peaks are provided the parallelization is disabled.

Returns:

network – A custom object is returned with the following data added as attributes:

• ’phases’

  The original phases image with any padding applied

• ’regions’

  The watershed segmentation of the image, including boundary regions if padding was applied

• ’network’

  A dictionary containing all the extracted network properties in OpenPNM format (‘pore.coords’, ‘throat.conns’, etc).

Return type:

Results object

References

[1]

Gostick JT. Versatile and efficient pore network extraction method using marker-based watershed segmentation. Phys. Rev. E. 96, 023307 (2017)

[2]

Khan ZA, Tranter TG, Agnaou M, Elkamel A, and Gostick JT, Dual network extraction algorithm to investigate multiple transport processes in porous materials: Image-based modeling of pore and grain-scale processes. Computers and Chemical Engineering. 123(6), 64-77 (2019)

[3]

Khan ZA, García-Salaberri PA, Heenan T, Jervis R, Shearing P, Brett D, Elkamel A, Gostick JT, Probing the structure-performance relationship of lithium-ion battery cathodes using pore-networks extracted from three-phase tomograms. Journal of the Electrochemical Society. 167(4), 040528 (2020)

[4]

Khan ZA, Elkamel A, Gostick JT, Efficient extraction of pore networks from massive tomograms via geometric domain decomposition. Advances in Water Resources. 145(Nov), 103734 (2020)

Examples

Click here to view online example.