A vector-based 3D rolling motion sediment entrainment model was developed with application to X-ray computed tomography (XCT) scanned riverbed grains. VectorEntrainment3D extracts grain characteristics and locates all grain-to-grain contact points from XCT scanned images of riverbed samples in an effort to estimate a threshold of entrainment critical shear stress for all surface grains in the sample. A vector-based 3D moment balance about a rotation axis is used to calculate a critical shear stress for each 'viable pair' of contact points for a single coarse surface grain, the smallest value of which is the entrainment threshold solution for that grain. An empirical cohesive force model is used to estimate the resistance force associated with coarse grain contact with a fine-grain matrix. Once a critical shear stress solution is found, three entrainment angles are calculated: the bearing and tilt angles describing the orientation of the grain's plane of rotation, which are determined by two contact points forming the axis of rotation; and the pivot angle describing the forward rotation of the grain, which lies within the plane of rotation.
Clone this GitHub project to a local folder on a computer that has MATLAB installed. There are a suite of functions and subroutines that are run from the main.m script. Follow the instructions in the main.m script header.
Images of riverbed samples must be processed to separate individual grains from the fine-grain matrix. Two sets of these processed image samples used in the Voepel et al (2019) paper are provided and reside as image stacks in the stacks folder. The structure of the out folder and its subfolders are necessary for output images generated by this code. The user may rename and restructure both stack and out folders as they see fit; however, they must also update the filepaths.xlsx file and run the code to update the filepath.mat database. Code for this update is located in STEP 1 section of the main.m file. Please note the following Prerequisites.
To run the 3D entrainment code, you will need MATLAB R2018a or higher installed with the following MATLAB Toolboxes:
- Image Processing Toolbox
- Mapping Toolbox
- Parallel Computing Toolbox
- Statistics and Machine Learning Toolbox
- Hal Voepel - PDRA coding - University of Southampton
- Julian Leyland - CI - University of Southampton
- Rebecca Hodge - PI - Durham University
- Sharif Ahmed - PDRA imaging - Diamond Light Source
- David Sear - CI - University of Southampton
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details