ContactAngle-Curvature-Roughness

Automatic measurements of contact angle, interfacial curvature and surface roughness in pore-scale 3D-images

Summary

This document presents the implementation of codes and scripts and the instructions for using them to run the automatic measurements of contact angle, fluid/fluid interface curvature and solid surface roughness applied on segmented 3D pore-space images. This package, when installed, performs surface extraction between contact phases, smoothing the extracted surface, measuring the distributions of contact angle, fluid/fluid interface curvature and solid roughness.

In the following, this document is organized into three sections. First is Installation, where the user can understand how to install and compile the code on his workstation. Next is Usage, where the user is guided how prepare his input data, run the code to analyze his input data and visualize the final results. Finally is Citations, here the user is refered for publications related to this work for more additional detials.

Installation

Prerequisites

You should have official OpenFOAM (version 1606+ in this document: https://www.openfoam.com/releases/openfoam-v1606+/) installed in your Linux machine. Paraview should be installed for visualization, preferably through system provided packages.

Downloading and extracting files

Create a directory in your home (~) folder named "works" and extract/download the codes inside it in a folder named apps. You can choose any other folder and the scripts will work, but this ducument assumes you install the codes in "~/works/apps" folder.

To clone and unzip this repo

git clone https://github.com/AhmedAlratrout/ContactAngle-Curvature-Roughness
tar -zxvf contactAngle.tar.gz
cd contactAngle

To check that the directories are created correctly, type in a terminal:

#  Important: replace ~/works/apps with the 
#  directory in which you have extracted the codes 
ls   ~/works/apps/scripts   ~/works/apps/contactAngle/voxelImage

and it should not show the error message "No such file or directory".

Compiling the codes

Edit the ~/works/apps/contactAngle/bashrc file making sure it sources the OpenFOAM-1612+/etc/bashrc file based on your OpenFOAM installation directories.

The mesh generation code requires a recent C++ compiler, you can set it either in the voxelImage/Makefile or by setting the variable CXX in file ~/works/apps/bashrc. The default (g++) may work and hence you don't need to do any change.

Then open a terminal and type the following commands to compile the codes:

(cd ~/works/apps/contactAngle && ./AllMake) 

Setting the Environmental variables:

Add the following line to your ~/.bashrc file (optional but recomended),

source ~/works/apps/contactAngle/bashrc

This makes the contact angle and roughness scripts available in any new terminal you open.

Usage

Input file format

The following required input files are provided in docs/Example:

1. Segmented dataset from 3D multiphase images (i.e. Micro-CT) should be given in ascii (suffix should be .dat) or binary files (better to have .raw suffix, the data should be in 8bit unsigned char). For contact angle and oil/brine interface curvature - the voxel values of the segmented phases are required to be in the following: oil = 2, rock (solid) = 1 and brine = 0. The contact angle is measured through the brine phase (voxel value = 0). An example is provided in docs/Example/Carbonate1_WW.raw, which is a binary segmented image cropped from Sample-1 image available on Digital Rocks Portal website: https://www.digitalrocksportal.org/projects/151. For measuring roughness - it is required to be applied on dry images (contain solid phase only). The voxel values of the segmented dry image should be solid = 1 and brine (or air) = 0.

2. Input header file: to declare the number of voxels in the three dimensions (x, y and z), the voxel dimensions (x, y and z) in microns and the offset distance (0 0 0 for no shifting). Rename the header file as the image file.

3. A sub-directory called system to comply with the basic directory structure for an OpenFOAM case. Make sure that there are two files (controlDict file and meshingDict file) in the system folder that contain the setting parameters. Note: the controlDict file is where run control parameters are set including start/end time. The meshingDict file is where the input and output files in each step of the algorithm is specified.

Running the contact angle and fluid/fluid interface curvature code

Open a terminal and type the following to run the code:

voxelToSurfaceML && surfaceAddLayerToCL && surfaceSmoothVP && more contactAngles.txt >>Kc.txt && more Kc.txt >> *_Layered_Smooth.vtk

This command will execute the following:

1. Extract the surface (multi-zone mesh M). Note: Mesh M is divided into three face-zones: z₁ represents the oil/rock interface, z₂ is the oil/brine interface and z₃ is the brine/rock interface in an oil-brine system. All vertices are given a label i. The set of vertices that belong to each zone will be denoted as V_OR, V_OB and V_BR respectively. V_CL is the set of vertices which are shared by all three face-zones representing the three-phase contact line. The name of the output file here (*.vtk) is specified.

2. Add a “layer” near the three-phase contact line. Note: Here the extracted file from the previous step is used as an input file (*.vtk) and the name of the output file (*_Layered.vtk) is specified. Each vertex in the contact line set (i ∈ V_CL) is constrained to have a single edge connection with a neighboring vertex of each zone.

3. Smooth the surface and curvature measurement. Note: In this step, the output file from the previous step (*_Layered.vtk) is used as an input mesh to apply the smoothing algorithm. The name of the smoothed output file (*_Layered_Smooth.vtk) is specified. In this step, a volume-preserving Gaussian smoothing is applied on mesh M, and then a volume-preserving curvature uniform smoothing is applied, which is consistent with capillary equilibrium. Two output files (Kc_x.txt and Kc.txt) are specified. The file Kc_x.txt contains the curvature values of the vertices belonging to the oil/brine interface (i ∈ V_OB) and their spatial location coordinates.

4. Contact angle measurement. Note: The contact angle is computed on each vertex that belongs to the contact line set, i ∈ V_CL. The contact angle (\theta _i)for each vertex is calculated through the brine phase by:

The normal vectors are computed on the vertices comprising the contact line, i ∈ _V__{_CL_}. Each vertex is represented with two vectors normal to the oil/brine interface (**z**₂) and the brine/rock interface (**z**₃), as shown in abstract figure.

Running the surface roughness code

Open a terminal and type the following to run the code:

voxelToSurfaceML && surfaceRoughness && more Ra.txt >> *_Smooth_Roughness.vtk

This command will execute the following:

1. Extract the surface (single-zone mesh S). Note: Mesh S is a single face-zone mesh that represents the rock surface only. For best results, it is better to apply this code on dry images (contain solid phase only).

Visualization

The generated files: surface (*.vtk), layered surface (*_Layered.vtk) and smoothed surfcae (*_Layered_Smooth.vtk). These files can be visualized using three-dimensional image visualization software (in this work Paraview software was used), as demonstrated in the abstract figure.

Citations

If you use our code for your own research, we would be grateful if you cite our following publications:

The developed algorithm for measuring contact angle and interfacial curvature in pore-space images

@article{ALRATROUT2017158,
title = "Automatic measurement of contact angle in pore-space images",
journal = "Advances in Water Resources",
volume = "109",
pages = "158 - 169",
year = "2017",
issn = "0309-1708",
doi = "https://doi.org/10.1016/j.advwatres.2017.07.018",
url = "http://www.sciencedirect.com/science/article/pii/S0309170817303342",
author = "Ahmed AlRatrout and Ali Q Raeini and Branko Bijeljic and Martin J Blunt"
}

The spatial correaltion of contact angle and interfacial curvature in pore-space images

@article{doi:10.1029/2017WR022124,
author = {AlRatrout, Ahmed Ahed Marouf and Blunt, Martin Julian and Bijeljic, Branko},
title = {Spatial correlation of contact angle and curvature in pore-space images},
journal = {Water Resources Research},
volume = {0},
number = {ja},
pages = {},
keywords = {Contact angle, Curvature, Spatial correlation, Wettability, pore-network, micro-CT},
doi = {10.1029/2017WR022124},
url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2017WR022124},
eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2017WR022124}
}

The developed algorithm for measuring surface roughness and its relationship to contact angle and interfacial curvature

@article {AlRatrout201803734,
	author = {AlRatrout, Ahmed and Blunt, Martin J. and Bijeljic, Branko},
	title = {Wettability in complex porous materials, the mixed-wet state, and its relationship to surface roughness},
	year = {2018},
	doi = {10.1073/pnas.1803734115},
	publisher = {National Academy of Sciences},
	issn = {0027-8424},
	URL = {http://www.pnas.org/content/early/2018/08/16/1803734115},
	eprint = {http://www.pnas.org/content/early/2018/08/16/1803734115.full.pdf},
	journal = {Proceedings of the National Academy of Sciences}
}