readme.txt



TILT, the Technique of Iterative Local Thresholding, http://TILT.princeton.edu

Developers: Hang Deng, Jeffrey P. Fitts, Catherine A. Peters, 

Environmental Geochemistry Lab, http://www.princeton.edu/~cap

Department of Civil & Environmental Engineering, Princeton University

Contact: Prof. Catherine A. Peters, Send email to cap@princeton.edu



Published work using TILT should cite:

Deng, H.; Fitts, J.P.; Peters, C.A. (2016) “Quantifying Fracture Geometry 

with X-ray Tomography: Technique of Iterative Local Thresholding (TILT) 

for 3D Image Segmentation" 
Computational Geosciences. DOI 10.1007/s10596-016-9560-9



TILT version 1.0 August 2015

----------------------------------------------------------------------------


TILT is written in MATLAB (MathWorks) code, including scripts and functions.



To learn how to use TILT, we recommend that you follow the examples provided, 

for two different types of materials/images. 



******* runTILTexample1.m : 

This is the case of a fracture in a rock that is nonporous and the fracture 
has fairly large apertures.  Also, this is the case of an xCT image

that has already been cropped to eliminate the experimental core holder 
and vessel sleeve from the xCT image. For this example, the final binary 
segmented image is generated simply by running the segmentation 
stage of TILT without use of a fracture template/mask.



******* runTILTexample2.m. 

This is the case of a fracture in a porous rock. Also, in this case, the xCT image 

still contains the image of the core holder and vessel sleeve around the rock core.

In this example, all the steps of the workflow of TILT are used.



-----------------------------------------------------------------------------



Procedural steps in running TILT. 

1. Load the '*.mat' file that contains the 3D xCT grayscale image.  

	1a. In advance, create the '*.mat' file by using 'imread' to read the png
	    (or tiff, etc.) of the xCT image exported from reconstruction software
	1b. The image must be grayscale, so if needed convert it using 'rgb2gray'.

	1c. The resulting image is a 3D matrix in which each image slice is a 2D 
	    matrix.
	1d. Save the 3D matrix using 'save'.
	1e. In the example scripts, the 3D image stack is called 'Imatrix'.

2. If a fracture template is needed, such as for a fracture in a porous material,
prepare the mex functions 'eig3volume' and 'imgaussian'.
	2a. These are needed in order to run MHFfilter3D.m.
	2b. Generate the mex functions by running the mex command on the '*.c'
	    codes as demonstrated in the script 'compileCfiles.m'.

3. If a fracture template is needed, generate a fracture template, which will be
used by TILT to generate a custom mask, as described in Deng et al 2016.
	3a. The commands are demonstrated in the script 'runMHFfilter.m'. 
	3b. In this script, first are the commands to generate the sheetness 
	    matrix using the Multi-scale Hessian Fracture filter
	    with user-specified option variables. 
	3c. The sheetness matrix is then segmented to identify regions of flatness. 
	3d. The 3D (and 2D) connectivity operator is then used to retain only the 
	    largest object. Both BW_mask3D and BW_mask2D fracture templates are 
	    generated.
	3e. These functions are based on the work presented in Manniesing et al. 
	    2005, Voorn et al 2014, and Frangi et al 1998.

4. Load the fracture template. 
	4a. Decide which of the fracture templates previously generated will be used.
	4b. Set the 'option.BW_frac' equal to the selected fracture template.

5. For the image thresholding that will be done in TILT, decide whether to do 
thresholding in 2D (slice by slice) or in 3D (using the entire stack of masked 
fracture image slices.). Tradeoffs are explained in Deng et al 2016. Example 
2 uses 3D.


6. If needed (as in example 2), prepare to crop out the domain that contains 
the experimental sample holder. In this example, this is done by  specifying 
the radius "R". The matlab  function 'imfindcircles' can be used to find the 
center and radius. Then set the TILT option variable 'options.IMdomain' equal to 'flag'.



7. If desired, specify parameters for the fracture dilation used by TILT in generating
a custom mask. Otherwise, use the default values which are: dilation shape is 
disk, and dilation length is 10 pixels.

8. Run the TILT function on the Imatrix, specifying the optimization parameters and 
domain options. The primary output from TILT is the 3D binary image, BW_TILT.


9. In the figure commands in the example scripts, for a single slice (the tenth) ...
	9a. Figure 1 shows the original grayscale image, 
	9b. Figure 2 is the resulting binary segmentation from TILT, 
	9c. Figure 3 is what you would get if simply using global thresholding 
	    and the connectivity filter (without the optimization process in TILT), 
	9d. Figure 4 shows the difference between fig 2 and fig 3.



------------------------------------------------------------------------------

Files:


*** scripts ***

	compileCfiles.m

	runMHFfilter.m

	runTILTexample1.m

	runTILTexample2.m
		

*** functions ***

	MHFfilter3D.m

	TILT.m

	Hessian3D.m

	imgaussian.m


*** data files ***

	example1.mat

	example2.mat

	example2Mask.mat

	MHFresults.mat

	Results3D_example2.mat

	Results3D_example2.mat


*** C/C++ code ***

	eig3volume.c

	imgaussian.c


*** mex files ***

	eig3volume.mexa64

	eig3volume.mexw32

	imgaussian.mexw32


*** PNG figures ***

	ex1_figure1.png

	ex1_figure2.png

	ex1_figure3.png

	ex1_figure4.png

	ex2_figure1.png

	ex2_figure2.png

	ex2_figure3.png

	ex2_figure4.png