def snow(im,
voxel_size=1,
boundary_faces=['top', 'bottom', 'left', 'right', 'front', 'back'],
marching_cubes_area=False):
r"""
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.
"""
# -------------------------------------------------------------------------
# SNOW void phase
regions = snow_partitioning(im=im, return_all=True)
im = regions.im
dt = regions.dt
regions = regions.regions
b_num = np.amax(regions)
# -------------------------------------------------------------------------
# Boundary Conditions
regions = add_boundary_regions(regions=regions, faces=boundary_faces)
# -------------------------------------------------------------------------
# Padding distance transform and image to extract geometrical properties
dt = pad_faces(im=dt, faces=boundary_faces)
im = pad_faces(im=im, faces=boundary_faces)
regions = regions * im
regions = make_contiguous(regions)
# -------------------------------------------------------------------------
# Extract void and throat information from image
net = regions_to_network(im=regions, dt=dt, voxel_size=voxel_size)
# -------------------------------------------------------------------------
# Extract marching cube surface area and interfacial area of regions
if marching_cubes_area:
areas = region_surface_areas(regions=regions)
interface_area = region_interface_areas(regions=regions,
areas=areas,
voxel_size=voxel_size)
net['pore.surface_area'] = areas * voxel_size**2
net['throat.area'] = interface_area.area
# -------------------------------------------------------------------------
# Find void to void connections of boundary and internal voids
boundary_labels = net['pore.label'] > b_num
loc1 = net['throat.conns'][:, 0] < b_num
loc2 = net['throat.conns'][:, 1] >= b_num
pore_labels = net['pore.label'] <= b_num
loc3 = net['throat.conns'][:, 0] < b_num
loc4 = net['throat.conns'][:, 1] < b_num
net['pore.boundary'] = boundary_labels
net['throat.boundary'] = loc1 * loc2
net['pore.internal'] = pore_labels
net['throat.internal'] = loc3 * loc4
# -------------------------------------------------------------------------
# label boundary cells
net = label_boundary_cells(network=net, boundary_faces=boundary_faces)
# -------------------------------------------------------------------------
# assign out values to dummy dict
temp = _net_dict(net)
temp.im = im.copy()
temp.dt = dt
temp.regions = regions
return temp
def snow_dual(im, voxel_size=1,
boundary_faces=['top', 'bottom', 'left', 'right', 'front', 'back'],
marching_cubes_area=False):
r"""
Extracts a dual pore and solid network from a binary image using a modified
version of the SNOW algorithm
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.
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)
"""
# -------------------------------------------------------------------------
# SNOW void phase
pore_regions = snow_partitioning(im, return_all=True)
# SNOW solid phase
solid_regions = snow_partitioning(~im, return_all=True)
# -------------------------------------------------------------------------
# Combined Distance transform of two phases.
pore_dt = pore_regions.dt
solid_dt = solid_regions.dt
dt = pore_dt + solid_dt
pore_peaks = pore_regions.peaks
solid_peaks = solid_regions.peaks
peaks = pore_peaks + solid_peaks
# Calculates combined void and solid regions for dual network extraction
pore_regions = pore_regions.regions
solid_regions = solid_regions.regions
pore_region = pore_regions*im
solid_region = solid_regions*~im
solid_num = sp.amax(pore_regions)
solid_region = solid_region + solid_num
solid_region = solid_region * ~im
regions = pore_region + solid_region
b_num = sp.amax(regions)
# -------------------------------------------------------------------------
# Boundary Conditions
regions = add_boundary_regions(regions=regions, faces=boundary_faces)
# -------------------------------------------------------------------------
# Padding distance transform to extract geometrical properties
f = boundary_faces
if f is not None:
if im.ndim == 2:
faces = [(int('left' in f)*3, int('right' in f)*3),
(int(('front') in f)*3 or int(('bottom') in f)*3,
int(('back') in f)*3 or int(('top') in f)*3)]
if im.ndim == 3:
faces = [(int('left' in f)*3, int('right' in f)*3),
(int('front' in f)*3, int('back' in f)*3),
(int('top' in f)*3, int('bottom' in f)*3)]
dt = sp.pad(dt, pad_width=faces, mode='edge')
else:
dt = dt
# -------------------------------------------------------------------------
# Extract void,solid and throat information from image
net = regions_to_network(im=regions, dt=dt, voxel_size=voxel_size)
# -------------------------------------------------------------------------
# -------------------------------------------------------------------------
# Extract marching cube surface area and interfacial area of regions
if marching_cubes_area:
areas = region_surface_areas(regions=regions)
interface_area = region_interface_areas(regions=regions, areas=areas,
voxel_size=voxel_size)
net['pore.surface_area'] = areas * voxel_size**2
net['throat.area'] = interface_area.area
# -------------------------------------------------------------------------
# Find void to void, void to solid and solid to solid throat conns
loc1 = net['throat.conns'][:, 0] < solid_num
loc2 = net['throat.conns'][:, 1] >= solid_num
loc3 = net['throat.conns'][:, 1] < b_num
pore_solid_labels = loc1 * loc2 * loc3
loc4 = net['throat.conns'][:, 0] >= solid_num
loc5 = net['throat.conns'][:, 0] < b_num
solid_solid_labels = loc4 * loc2 * loc5 * loc3
loc6 = net['throat.conns'][:, 1] < solid_num
pore_pore_labels = loc1 * loc6
loc7 = net['throat.conns'][:, 1] >= b_num
boundary_throat_labels = loc5 * loc7
solid_labels = ((net['pore.label'] > solid_num) * ~
(net['pore.label'] > b_num))
boundary_labels = net['pore.label'] > b_num
b_sa = sp.zeros(len(boundary_labels[boundary_labels == 1.0]))
# -------------------------------------------------------------------------
# Calculates void interfacial area that connects with solid and vice versa
p_conns = net['throat.conns'][:, 0][pore_solid_labels]
ps = net['throat.area'][pore_solid_labels]
p_sa = sp.bincount(p_conns, ps)
s_conns = net['throat.conns'][:, 1][pore_solid_labels]
s_pa = sp.bincount(s_conns, ps)
s_pa = sp.trim_zeros(s_pa) # remove pore surface area labels
p_solid_surf = sp.concatenate((p_sa, s_pa, b_sa))
# -------------------------------------------------------------------------
# Calculates interfacial area using marching cube method
if marching_cubes_area:
ps_c = net['throat.area'][pore_solid_labels]
p_sa_c = sp.bincount(p_conns, ps_c)
s_pa_c = sp.bincount(s_conns, ps_c)
s_pa_c = sp.trim_zeros(s_pa_c) # remove pore surface area labels
p_solid_surf = sp.concatenate((p_sa_c, s_pa_c, b_sa))
# -------------------------------------------------------------------------
# Adding additional information of dual network
net['pore.solid_void_area'] = (p_solid_surf * voxel_size**2)
net['throat.void'] = pore_pore_labels
net['throat.interconnect'] = pore_solid_labels
net['throat.solid'] = solid_solid_labels
net['throat.boundary'] = boundary_throat_labels
net['pore.void'] = net['pore.label'] <= solid_num
net['pore.solid'] = solid_labels
net['pore.boundary'] = boundary_labels
class network_dict(dict):
pass
net = network_dict(net)
net.im = im
net.dt = dt
net.regions = regions
net.peaks = peaks
net.pore_dt = pore_dt
net.pore_regions = pore_region
net.pore_peaks = pore_peaks
net.solid_dt = solid_dt
net.solid_regions = solid_region
net.solid_peaks = solid_peaks
return net
def snow(im,
voxel_size=1,
boundary_faces=['top', 'bottom', 'left', 'right', 'front', 'back'],
marching_cubes_area=False):
r"""
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.
"""
# -------------------------------------------------------------------------
# SNOW void phase
tup = snow_partitioning(im=im, return_all=True)
im = tup.im
dt = tup.dt
regions = tup.regions
peaks = tup.peaks
b_num = sp.amax(regions)
# -------------------------------------------------------------------------
# Boundary Conditions
regions = add_boundary_regions(regions=regions, faces=boundary_faces)
# -------------------------------------------------------------------------
# Padding distance transform to extract geometrical properties
f = boundary_faces
if f is not None:
if im.ndim == 2:
faces = [(int('left' in f) * 3, int('right' in f) * 3),
(int(('front') in f) * 3 or int(('bottom') in f) * 3,
int(('back') in f) * 3 or int(('top') in f) * 3)]
if im.ndim == 3:
faces = [(int('left' in f) * 3, int('right' in f) * 3),
(int('front' in f) * 3, int('back' in f) * 3),
(int('top' in f) * 3, int('bottom' in f) * 3)]
dt = sp.pad(dt, pad_width=faces, mode='edge')
im = sp.pad(im, pad_width=faces, mode='edge')
else:
dt = dt
regions = regions * im
regions = make_contiguous(regions)
# -------------------------------------------------------------------------
# Extract void and throat information from image
net = regions_to_network(im=regions, dt=dt, voxel_size=voxel_size)
# -------------------------------------------------------------------------
# Extract marching cube surface area and interfacial area of regions
if marching_cubes_area:
areas = region_surface_areas(regions=regions)
interface_area = region_interface_areas(regions=regions,
areas=areas,
voxel_size=voxel_size)
net['pore.surface_area'] = areas * voxel_size**2
net['throat.area'] = interface_area.area
# -------------------------------------------------------------------------
# Find void to void connections of boundary and internal voids
boundary_labels = net['pore.label'] > b_num
loc1 = net['throat.conns'][:, 0] < b_num
loc2 = net['throat.conns'][:, 1] >= b_num
pore_labels = net['pore.label'] <= b_num
loc3 = net['throat.conns'][:, 0] < b_num
loc4 = net['throat.conns'][:, 1] < b_num
net['pore.boundary'] = boundary_labels
net['throat.boundary'] = loc1 * loc2
net['pore.internal'] = pore_labels
net['throat.internal'] = loc3 * loc4
# -------------------------------------------------------------------------
# label boundary pore faces
if f is not None:
coords = net['pore.coords']
condition = coords[net['pore.internal']]
dic = {
'left': 0,
'right': 0,
'front': 1,
'back': 1,
'top': 2,
'bottom': 2
}
if all(coords[:, 2] == 0):
dic['top'] = 1
dic['bottom'] = 1
for i in f:
if i in ['left', 'front', 'bottom']:
net['pore.{}'.format(i)] = (coords[:, dic[i]] < min(
condition[:, dic[i]]))
elif i in ['right', 'back', 'top']:
net['pore.{}'.format(i)] = (coords[:, dic[i]] > max(
condition[:, dic[i]]))
class network_dict(dict):
pass
net = network_dict(net)
net.im = im
net.dt = dt
net.regions = regions
net.peaks = peaks
return net
def snow_n(im,
voxel_size=1,
boundary_faces=['top', 'bottom', 'left', 'right', 'front', 'back'],
marching_cubes_area=False,
alias=None):
r"""
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.
"""
# -------------------------------------------------------------------------
# Get alias if provided by user
al = _create_alias_map(im, alias=alias)
# -------------------------------------------------------------------------
# Perform snow on each phase and merge all segmentation and dt together
snow = snow_partitioning_n(im,
r_max=4,
sigma=0.4,
return_all=True,
mask=True,
randomize=False,
alias=al)
# -------------------------------------------------------------------------
# Add boundary regions
f = boundary_faces
regions = add_boundary_regions(regions=snow.regions, faces=f)
# -------------------------------------------------------------------------
# Padding distance transform to extract geometrical properties
dt = pad_faces(im=snow.dt, faces=f)
# -------------------------------------------------------------------------
# For only one phase extraction with boundary regions
phases_num = np.unique(im).astype(int)
phases_num = np.trim_zeros(phases_num)
if len(phases_num) == 1:
if f is not None:
snow.im = pad_faces(im=snow.im, faces=f)
regions = regions * (snow.im.astype(bool))
regions = make_contiguous(regions)
# -------------------------------------------------------------------------
# Extract N phases sites and bond information from image
net = regions_to_network(im=regions, dt=dt, voxel_size=voxel_size)
# -------------------------------------------------------------------------
# Extract marching cube surface area and interfacial area of regions
if marching_cubes_area:
areas = region_surface_areas(regions=regions)
interface_area = region_interface_areas(regions=regions,
areas=areas,
voxel_size=voxel_size)
net['pore.surface_area'] = areas * voxel_size**2
net['throat.area'] = interface_area.area
# -------------------------------------------------------------------------
# Find interconnection and interfacial area between ith and jth phases
net = add_phase_interconnections(net=net,
snow_partitioning_n=snow,
marching_cubes_area=marching_cubes_area,
alias=al)
# -------------------------------------------------------------------------
# label boundary cells
net = label_boundary_cells(network=net, boundary_faces=f)
# -------------------------------------------------------------------------
temp = _net_dict(net)
temp.im = im.copy()
temp.dt = dt
temp.regions = regions
return temp