Data and matlab analysis code associated with Ultrasound based dewatering manuscript. Ringania et al.
See Tutorial video here: https://youtu.be/01_Xn_gl2Wg
GTFiberUND Image Analysis Protocol
- Download GTFiberUND from github.com: • https://github.com/bhamla-lab/Ultrasound_CNF_Dewatering2021
- Unzip the GTFiberUND download and move contents to a designated folder; lets call this folder MATLAB for sake of example.
- Open MATLAB, click the, “browse for folder” button near top left corner on the home tab, select folder containing GTFiberUND files (i.e. MATLAB folder) • Make sure to add all folders and subfolders to the path (right click on folders, select “Add to Path”, select “Selected Folders and Subfolders”).
- Type “GTFiber” into command window, this opens the GTFiber GUI.
- Click on file and select the image you would like to analyze.
- Enter image width, select the invert color option. • When entering width make sure you check image width with the measurement tool in ImageJ using the appropriate scale factor associated with the zoom setting used during microscopic imaging. • When entering image width the value must be in the thousands of nanometers range, if dealing with images exceeding this width one must scale by a factor to yield a value in the thousands range and scale all image analysis results according to this factor. i. For example: 20x image has a width of 439 micrometers translating to 439,000 nanometers according to ImageJ and appropriate scale factor. This value greatly exceeds the thousands of nanometers range and must be scaled by a factor of 100 to yield a value in this desired range. The resulting scaled image width is 4,390 nanometers 〖×10〗^2. All results from this image analysis will be in terms of nanometers 〖×10〗^2 rather than nanometers and results must be interpreted accordingly.
- Input parameters that best suit the images that you are processing. Typically, If images are taken at the same settings the parameters do not need to be adjusted between analyzing each image. This may take some trial and error to yield filtering and stitching settings that produce acceptable results; typically the default parameters that update upon entering image width provide good results but some settings will likely need to be adjusted. • For the 20x images of 4388.571 nanometers 〖×10〗^2 length the following settings were found to be optimal: i. Don’t adjust gaussian smoothing value (leave as 4388.571) ii. Input an orientation smoothing of 5 (divided default value of 13.1657 by 2.63314) iii. Don’t adjust diffusion time (leave as a default of 5 seconds) iv. Input a top hat size of 17.5 (~half of the default value of 35.1086) v. Change thresholding setting to global threshold and input a value of 0.4 (default value of 0.45 divided by 1.125) vi. Don’t adjust noise max sq area (leave as default value of 1316.5713) vii. Don’t adjust step length (leave as default of 30) viii. Input max curvature of 70 (multiplied default value of 7 by 10) ix. Don’t adjust stitch gap length (leave as default value of 52.6629) x. Don’t adjust minimum fiber length (leave as default value of 100)
- Click on Run Filter button, once filtering is complete click the Stitch Fibers button, once complete click the Fiber Length and Width button under the plotting section.
- Open GTFiber2AnalysisComp.m script contained in the GTFiberUND folder.
- Double click on the GTFiber2Test.mat structure generated by clicking Fiber Length and Width button, can close out of the plots displayed (just had to add the structure to the workspace). Run the code to extract fiber length and fiber width vectors from the structure. • Note: must hardcode names each time you analyze a new image or old data will be overwritten. When analyzing a new image make sure to double click on the GTFiber2Test.mat structure to add it to the workspace, if the GTFiber2AnalysisComp.m script is run prior to adding the new structure to the workspace the script will simply create duplicate length and width vectors from the last images data.
- Repeat steps 5-10 until all of the images in your folder are analyzed. • Make sure to deselect the Scale Parameters with Width option and to keep the GUI open. This prevents one from having to input the same settings repeatedly when analyzing images and greatly speeds up the process.
- Open the VectorNameModification.m script. Running this script compiles all length and width vectors from the images analyzed into a single length vector and a single width vector.
• Make sure to update hardcoded names as indicated in the script.
• Repeat this step as well as steps 1-11 for each set of images analyzed. - Open the CompiledHistogramsRefinedFigures.m script and run it. • Need to adjust the number and names of length and width vectors in the script as they are hardcoded.
This is the public-facing repository for GTFiber 2.0. GTFiber is an open source program for automated quantitative analysis of images of fibrillar microstructures. Automatically extract fiber length, width, and orientation distributions, as well as orientational order parameters.
Please cite the paper if you find the software useful.
See GTFiber 1.1 for the old version that did not vectorize fibers (faster but less rigorous analysis)
GTFiber comes with an installer that enables users to run the program without MATLAB.
- IMPORTANT FOR MAC OS SIERRA+: After downloading the repository, you must create a new folder inside the repository folder (it can be called anything, even "untitled") and move "MyAppInstaller_web" into the newly created folder. This somehow convinces Mac OS that the installer app is trustable, even though it was downloaded from the internet.
- Download the repository, run "MyAppInstaller_web (.exe for Windows, .app for Mac)" and follow the prompts. It will instruct you to download the Matlab Compiler Runtime, which is approximately 700MB, and is necessary to run MATLAB GUIs outside of the MATLAB environment. At the end of installation, it has instructions to change or edit some system files - ignore this and continue. If there are issues, please email me at nils.persson@chbe.gatech.edu.
- Open the installed .app by double-clicking on it. Wait at least one minute, even if it appears nothing is happening on your screen. The Matlab Runtime is being loaded and does not display any message to indicate this is happening.
- Download the repository to your local machine
- Extract the repository to your MATLAB active directory
- Open the extracted folder
- Run
addpath(genpath(pwd)) - Run
GTFiber - Operate the GUI by following the instructions in "Using GTFiber" below
- Running in Matlab provides better access to the raw data and algorithms.
- File -> Load Image
- Enter the image's width (not height) in nanometers, with no commas - for example, 5000
- If your image is much larger than 10 µm, instead enter the width in µm and treat every "nm" as if it were "µm"
- Wait until a figure appears showing your original image. This means the program is initialized and ready to run.
- The name of your image will appear at the top of the app as well.
- Each filter parameter has an editable text box. The app scales these parameters automatically based on the image width provided, so try the defaults first. For further tuning, follow the guide in the supporting info of the paper.
- Filter parameters are generally expressed in nanometers so that they work on images of different pixel resolution, but the same physical size
- To view the result after any step of filtering, check its "Display" button
- Click "Run Filter" and wait for all progress bars to complete and disappear
- Click "Stitch Fibers" and wait for the progress bars to complete
- After both "Run Filter" and "Stitch Fibers", click "Orientational Order" or "Fiber Length/Width" to see plots of various order parameters and structural measurements. Click "Orientation Map" to generate a colored Orientation Map (this is slow).
- "Analyze Folder of Images" will apply your current filter parameters to each image file in a specified directory and output the raw results to a .csv file in that directory
- If you would like to save the Orientation Map, Orientation Distribution, and 2D order parameter decay plot as figures for each image, check "Save Figures" below the "Run a Directory..." button
- Allow progress bars to complete, then open the directory to view your results.
- Images in a single directory should be the same physical size, e.g. 5000 x 5000nm, because the specified Image Width will be applied to all
GTFiber comes with example images from the protocol paper in which it was introduced, to show what each step looks like with good filter parameters.
- Load an image from the "Example Images" folder, such as "Fig 5A 5000nm.tif"
- Enter the size of the image, specified in the image's file name
- Click "Run Filter", wait for processing to complete
- Click "Stitch Fibers", wait for completion