networks

Obtain Network Representations

Contains functions for analysing images as pore networks

porespy.networks.add_boundary_regions([…]) Given an image partitioned into regions, pads specified faces with new regions
porespy.networks.snow(im[, voxel_size, …]) Analyzes an image that has been partitioned into void and solid regions and extracts the void and solid phase geometry as well as network connectivity.
porespy.networks.snow_dual(im[, voxel_size, …]) Analyzes an image that has been partitioned into void and solid regions and extracts the void and solid phase geometry as well as network connectivity.
porespy.networks.regions_to_network(im[, …]) Analyzes an image that has been partitioned into pore regions and extracts the pore and throat geometry as well as network connectivity.
porespy.networks.map_to_regions(regions, values) Maps pore values from a network onto the image from which it was extracted
porespy.networks.generate_voxel_image(network) Generates voxel image from an OpenPNM network object.
porespy.networks.add_boundary_regions(regions=None, faces=['front', 'back', 'left', 'right', 'top', 'bottom'])[source]

Given an image partitioned into regions, pads specified faces with new regions

Parameters:
  • regions (ND-array) – An image of the pore space partitioned into regions and labeled
  • faces (list of strings) –

    The faces of regions which should have boundaries added. Options are:

    ’right’ - Adds boundaries to the x=0 face (im[0, :, :])

    ’left’ - Adds boundaries to the x=X face (im[-1, :, :])

    ’front’ - Adds boundaries to the y=0 face (im[:, ), :])

    ’back’ - Adds boundaries to the x=0 face (im[:, -1, :])

    ’bottom’ - Adds boundaries to the x=0 face (im[:, :, 0])

    ’top’ - Adds boundaries to the x=0 face (im[:, :, -1])

    The default is all faces.

Returns:

image – A copy of regions with the specified boundaries added, so will be slightly larger in each direction where boundaries were added.

Return type:

ND-array

porespy.networks.generate_voxel_image(network, pore_shape='sphere', throat_shape='cylinder', max_dim=None, verbose=1, rtol=0.1)[source]

Generates voxel image from an OpenPNM network object.

Parameters:
  • network (OpenPNM GenericNetwork) – Network from which voxel image is to be generated
  • pore_shape (str) – Shape of pores in the network, valid choices are “sphere”, “cube”
  • throat_shape (str) – Shape of throats in the network, valid choices are “cylinder”, “cuboid”
  • max_dim (int) – Number of voxels in the largest dimension of the network
  • rtol (float) – Stopping criteria for finding the smallest voxel image such that further increasing the number of voxels in each dimension by 25% would improve the predicted porosity of the image by less that rtol
Returns:

im – Voxelated image corresponding to the given pore network model

Return type:

ND-array

Notes

(1) The generated voxelated image is labeled with 0s, 1s and 2s signifying solid phase, pores, and throats respectively.

(2) If max_dim is not provided, the method calculates it such that the further increasing it doesn’t change porosity by much.

porespy.networks.label_boundary_cells(network=None, boundary_faces=None)[source]

Takes 2D or 3D network and assign labels to boundary pores

Parameters:
  • network (dictionary) – A dictionary as produced by the SNOW network extraction algorithms containing edge/vertex, site/bond, node/link information.
  • boundary_faces (list of strings) – The user can choose ‘left’, ‘right’, ‘top’, ‘bottom’, ‘front’ and ‘back’ face labels to assign boundary nodes. If no label is assigned then all six faces will be selected as boundary nodes automatically which can be trimmed later on based on user requirements.
Returns:

  • The same dictionar s pass ing, but containing boundary nodes labels. For
  • example network[‘pore.left’], network[‘pore.right’], network[‘pore.top’],
  • network[‘pore.bottom’] etc.

Notes

The dictionary names use the OpenPNM convention so it may be converted directly to an OpenPNM network object using the update command.

porespy.networks.map_to_regions(regions, values)[source]

Maps pore values from a network onto the image from which it was extracted

This function assumes that the pore numbering in the network has remained unchanged from the region labels in the partitioned image.

Parameters:
  • regions (ND-array) – An image of the pore space partitioned into regions and labeled
  • values (array_like) – An array containing the numerical values to insert into each region. The value at location n will be inserted into the image where regions is n+1. This mis-match is caused by the fact that 0’s in the regions image is assumed to be the backgroung phase, while pore index 0 is valid.

Notes

This function assumes that the array of pore values are indexed starting at location 0, while in the region image 0’s indicate background phase and the region indexing starts at 1. That is, region 1 corresponds to pore 0.

porespy.networks.add_phase_interconnections(net, snow_partitioning_n, voxel_size=1, marching_cubes_area=False, alias=None)[source]

This function connects networks of two or more phases together by interconnecting neighbouring nodes inside different phases.

The resulting network can be used for the study of transport and kinetics at interphase of two phases.

Parameters:
  • network (2D or 3D network) – A dictoionary containing structural information of two or more phases networks. The dictonary format must be same as porespy region_to_network function.
  • snow_partitioning_n (tuple) – The output generated by snow_partitioning_n function. The tuple should have phases_max_labels and original image of material.
  • voxel_size (scalar) – 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. The default is 1, which is useful when overlaying the PNM on the original image since the scale of the image is alway 1 unit lenth per voxel.
  • marching_cubes_area (bool) – If True then the surface area and interfacial area between regions will be causing the marching cube algorithm. This is a more accurate representation of area in extracted network, but is quite slow, so it is False by default. The default method simply counts voxels so does not correctly account for the voxelated nature of the images.
  • alias (dict (Optional)) – A dictionary that assigns unique image label to specific phase. For example {1: ‘Solid’} will show all structural properties associated with label 1 as Solid phase properties. If None then default labelling will be used i.e {1: ‘Phase1’,..}.
Returns:

  • A dictionary containing network information of individual and connected
  • networks. The dictionary names use the OpenPNM convention so it may be
  • converted directly to an OpenPNM network object using the update
  • command.

porespy.networks.regions_to_network(im, dt=None, voxel_size=1)[source]

Analyzes an image that has been partitioned into pore regions and extracts the pore and throat geometry as well as network connectivity.

Parameters:
  • im (ND-array) – An image of the pore space partitioned into individual pore regions. Note that this image must have zeros indicating the solid phase.
  • dt (ND-array) – The distance transform of the pore space. If not given it will be calculated, but it can save time to provide one if available.
  • voxel_size (scalar) – 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. The default is 1, which is useful when overlaying the PNM on the original image since the scale of the image is alway 1 unit lenth per voxel.
Returns:

  • A dictionary containing all the pore and throat size data, as well as the
  • network topological information. The dictionary names use the OpenPNM
  • convention (i.e. ‘pore.coords’, ‘throat.conns’) so it may be converted
  • directly to an OpenPNM network object using the update command.

porespy.networks.snow(im, voxel_size=1, boundary_faces=['top', 'bottom', 'left', 'right', 'front', 'back'], marching_cubes_area=False)[source]

Analyzes an image that has been partitioned into void and solid regions and extracts the void and solid phase geometry as well as network connectivity.

Parameters:
  • im (ND-array) – Binary image in the Boolean form with True’s as void phase and False’s as solid phase.
  • voxel_size (scalar) – 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. The default is 1, which is useful when overlaying the PNM on the original image since the scale of the image is alway 1 unit lenth per voxel.
  • boundary_faces (list of strings) – Boundary faces labels are provided to assign hypothetical boundary nodes having zero resistance to transport process. For cubical geometry, the user can choose ‘left’, ‘right’, ‘top’, ‘bottom’, ‘front’ and ‘back’ face labels to assign boundary nodes. If no label is assigned then all six faces will be selected as boundary nodes automatically which can be trimmed later on based on user requirements.
  • marching_cubes_area (bool) – If True then the surface area and interfacial area between regions will be using the marching cube algorithm. This is a more accurate representation of area in extracted network, but is quite slow, so it is False by default. The default method simply counts voxels so does not correctly account for the voxelated nature of the images.
Returns:

  • A dictionary containing the void phase size data, as well as the network
  • topological information. The dictionary names use the OpenPNM
  • convention (i.e. ‘pore.coords’, ‘throat.conns’) so it may be converted
  • directly to an OpenPNM network object using the update command.
  • * ``net`` (A dictionary containing all the void and solid phase size data,) – as well as the network topological information. The dictionary names use the OpenPNM convention (i.e. ‘pore.coords’, ‘throat.conns’) so it may be converted directly to an OpenPNM network object using the update command.
  • * ``im`` (The binary image of the void space)
  • * ``dt`` (The combined distance transform of the image)
  • * ``regions`` (The void and solid space partitioned into pores and solids) – phases using a marker based watershed with the peaks found by the SNOW Algorithm.

porespy.networks.snow_dual(im, voxel_size=1, boundary_faces=['top', 'bottom', 'left', 'right', 'front', 'back'], marching_cubes_area=False)[source]

Analyzes an image that has been partitioned into void and solid regions and extracts the void and solid phase geometry as well as network connectivity.

Parameters:
  • im (ND-array) – Binary image in the Boolean form with True’s as void phase and False’s as solid phase. It can process the inverted configuration of the boolean image as well, but output labelling of phases will be inverted and solid phase properties will be assigned to void phase properties labels which will cause confusion while performing the simulation.
  • voxel_size (scalar) – 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. The default is 1, which is useful when overlaying the PNM on the original image since the scale of the image is alway 1 unit lenth per voxel.
  • boundary_faces (list of strings) – Boundary faces labels are provided to assign hypothetical boundary nodes having zero resistance to transport process. For cubical geometry, the user can choose ‘left’, ‘right’, ‘top’, ‘bottom’, ‘front’ and ‘back’ face labels to assign boundary nodes. If no label is assigned then all six faces will be selected as boundary nodes automatically which can be trimmed later on based on user requirements.
  • marching_cubes_area (bool) – If True then the surface area and interfacial area between regions will be using the marching cube algorithm. This is a more accurate representation of area in extracted network, but is quite slow, so it is False by default. The default method simply counts voxels so does not correctly account for the voxelated nature of the images.
Returns:

  • A dictionary containing all the void and solid phase size data, as well as
  • the network topological information. The dictionary names use the OpenPNM
  • convention (i.e. ‘pore.coords’, ‘throat.conns’) so it may be converted
  • directly to an OpenPNM network object using the update command.
  • * ``net`` (A dictionary containing all the void and solid phase size data,) – as well as the network topological information. The dictionary names use the OpenPNM convention (i.e. ‘pore.coords’, ‘throat.conns’) so it may be converted directly to an OpenPNM network object using the update command.
  • * ``im`` (The binary image of the void space)
  • * ``dt`` (The combined distance transform of the image)
  • * ``regions`` (The void and solid space partitioned into pores and solids) – phases using a marker based watershed with the peaks found by the SNOW Algorithm.

References

[1] Gostick, J. “A versatile and efficient network extraction algorithm using marker-based watershed segmenation”. Phys. Rev. E 96, 023307 (2017)

[2] Khan, ZA et al. “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)

porespy.networks.snow_n(im, voxel_size=1, boundary_faces=['top', 'bottom', 'left', 'right', 'front', 'back'], marching_cubes_area=False, alias=None)[source]

Analyzes an image that has been segemented into N phases and extracts all a network for each of the N phases, including geometerical information as well as network connectivity between each phase.

Parameters:
  • im (ND-array) – Image of porous material where each phase is represented by unique integer. Phase integer should start from 1 (0 is ignored)
  • voxel_size (scalar) – 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. The default is 1, which is useful when overlaying the PNM on the original image since the scale of the image is always 1 unit lenth per voxel.
  • boundary_faces (list of strings) – Boundary faces labels are provided to assign hypothetical boundary nodes having zero resistance to transport process. For cubical geometry, the user can choose ‘left’, ‘right’, ‘top’, ‘bottom’, ‘front’ and ‘back’ face labels to assign boundary nodes. If no label is assigned then all six faces will be selected as boundary nodes automatically which can be trimmed later on based on user requirements.
  • marching_cubes_area (bool) – If True then the surface area and interfacial area between regions will be calculated using the marching cube algorithm. This is a more accurate representation of area in extracted network, but is quite slow, so it is False by default. The default method simply counts voxels so does not correctly account for the voxelated nature of the images.
  • alias (dict (Optional)) – A dictionary that assigns unique image label to specific phases. For example {1: ‘Solid’} will show all structural properties associated with label 1 as Solid phase properties. If None then default labelling will be used i.e {1: ‘Phase1’,..}.
Returns:

  • A dictionary containing all N phases size data, as well as the
  • network topological information. The dictionary names use the OpenPNM
  • convention (i.e. ‘pore.coords’, ‘throat.conns’) so it may be converted
  • directly to an OpenPNM network object using the update command.