How to extract a network and use it in OpenPNM

[jgostick]

One common class of question asked here is about network extraction, by users wishing to study their porous material as a pore network. These questions come from users with different levels of knowledge and experience, as well as from different starting points in terms of input data. This FAQ is meant as a starting point to answer questions for all of these cases. The following steps outline the process with links to relevant examples and resources where possible.

Convert Image Slices into a 3D Stack

If the images were obtained from x-ray tomography, then you probably have a folder full of "tiff" images, with each one representing a slice at a different vertical position. For instance:

This image needs to be converted to a single 3D image, which the "tiff" format supports. There are several ways to do this. This example outlines how to use ImageJ.

Binarize or Segment Greyscale Images

Once you have the greyscale images as a 3D stack they can be opened in Python and "processed" to make them 'binary' such that True represents void space and False represents solid (or vice versa).

Opening the image in Python can be done using scikit-image via the imread function. There are other options here like imageio and open3d but you'll need to have scikit-image installed already so best to just stick with that (Note that setting as_gray=True is helpful). Both the imageio and scikit-image versions of imread create a numpy array from the image, which we can now process.

Converting to a binary image is quite challenging and frustrating. This example outlines the process. Another good tutorial is this one by Emmanuelle Gouillart who contributes to scikit-image.

Extract the Network

With a binary, 3D image it is now possible to extract a pore network. There are a variety of algorithms for doing this which each give slightly different results, and there may not be a definitive network for your material. However, they should all be pretty similar. The snow algorithm is included in PoreSpy, so we'll focus on this one.

We have a number of examples to learn from:

1. Here is a basic introduction to the algorithms
2. Here is a more advanced demo on a 3D image
3. And here is a detailed explanation of the various features and options.

Open Network in OpenPNM

Since network extraction is purely an image-processing tool we decided to keep it separate from our pore network modeling tool OpenPNM They are fully compatible though. The process of opening a network extracted by PoreSpy, cleaning up the data, and running simulations is given here.

[likeduck]

I am very grateful that these works can help us better understand the SNOW algorithm and the process of extracting PNM. And I thought I could add a method (code) that I use frequently to save PNMs to avoid having to re-extract it every time.

1. Save SNOW-PNM
   Assuming you have finished extracting：
   net = ps.networks.regions_to_network(regions*im, voxel_size=sigma)
pn = op.io.network_from_porespy(net)
   Then you need to do is：

import bz2
import pickle
def compressed_pickle(fname, data):
    with bz2.BZ2File(fname + '.pbz2', 'w') as file: 
        pickle.dump(data, file)

compressed_pickle(path+fname, pn)

2. Use the packaged PNM again in other code

import bz2
import pickle

def decompress_pickle(file):
    data = bz2.BZ2File(file, 'rb')
    data = pickle.load(data)
    return data

data = decompress_pickle(path+fname)
pn = data

Although the pickle and bz2 are difficult to install and master, I believe this method can preserve the extracted PNM well, especially in large voxel porous media after several hours of extraction. It is worth mentioning that by completing pre-work before compressing the PNM, you can get a universal PNM that can be used directly. Congratulations on getting started!

[jgostick]

Thanks @likeduck! BTW, I edited your answer to include the language name in the code blocks to get syntax highlighting, like:

``` python
code here
```

[likeduck]

Sure! I have learned this code block display method. It looks great✔

[amiracoder]

I applied the advanced algorithm to an interconnected, ordered lattice structure, which resulted in 2 pores and 3 throats. does that make sense?