The MuscleUS_Toolbox consists of a series of custom-written Matlab functions for performing ultrasound fiber tractography in skeletal muscle. This README file contains
- Acknowledgements
- License information
- Getting started
- A list of the conventions assumed regarding data acquisition
- An overview of a typical workflow using the toolbox
- Links to other resources in the toolbox and online
The functions in this toolbox reflect the collective contributions of many individuals, including: Emily Bush, Crystal Coolbaugh, Bruce Damon, Zhaohua Ding, Hannah Kilpatrick, and Ke Li. Details regarding authorship and individual contributions are noted in each function.
This work was supported by NIH grant NIH/NIAMS R01 AR073831. By using this software, users agree to acknowledge the active grant (NIH/NIAMS R01 AR073831) in presentations and publications and to adhere to NIH policies regarding open access to their publications.
This work is covered under a GNU General Public License, v. 3 or later.
The easiest way to do this is to click once on the green Code button. Select the "Download ZIP" option; this will download a compressed folder to your computer. Then extract the files to a convenient place on your computer (note that after extracting the files, you will need to set a MATLAB path to the directory that holds the custom-written functions).
The functions have been tested using MATLAB v. 2021 b, Release 2. The toolbox consists primarily of custom-written functions, but also calls MATLAB functions in the base package and the image processing toolbox.
To begin the session, a DICOM-formatted ultrasound file is opened. The function read_dicom_us (current version, v. 1.0.0) will prepare image data and information structures in the form expected by subsequent functions. Help is available here.
Real muscle fibers are assumed to be contained entirely within a single muscle of interest. The function define_muscleroi_us, v. 1.0.0, is therefore used to create a binary image mask demarcating the muscle boundaries; this mask is used to restrict analyses to the region of interest within the muscle. The tracts are propagated from a set of points, commonly called "seed points." In the MuscleUS_Toolbox, the anatomical structure into which the muscle fibers insert (a flattened tendinous structure called an aponeurosis) is used to define these points. Follow this link for detailed help on this function.
Using the B-mode image, the muscle fascicles orientations are estimated using the algorithm presented by Rana et al., (J Biomech, 42:2068, 2009). The images are processed using the following steps:
- Vesselness filtering:
- A series of Gaussian blurring steps of varying sizes
- Calculation of the vesselness response of the structures
- Calculation of the Hessian matrix of the vesselness response
- Orientation modeling:
- An anisotropic wavelet is convolved with the image at a range of orientations
- The angle at which the maximum convolution of the wavelet with the image is taken as the fascicle orientation
- The angles are averaged across grid squares of user-defined dimensions
The function returns an image at the original resolution, a masked image at the original resolution, a gridded image of angles, a masked image with the components of unit vectors indicating the fascicle orientations, and images for QA purposes. The current version of bmode2angle_us is 1.0.0 and has a detailed help file available here.
Fiber tracts are propagated from the seed points by integrating through the vector field defined by the second eigenvector of the image intensity gradient's Hessian matrix. The function fiber_track_us, v. 1.0.0, is used to perform this integration. The major output of this function is a matrix containing the {row, column, slice} coordinates of each point along each fiber tract. Follow this link for detailed help on this function.
Fiber tract points are subject to errors in position because of the presence of noise and artifacts in the images. To mitigate these effects, the function fiber_smoother_us, v. 1.0.0, performs a polynomial fit to each fiber tract. This also allows the interpolation of the fiber tract positions at a resolution higher than the original tracts. This step is not required, but is strongly recommended prior to calling the fiber_quantifier_us function. Follow this link for detailed help on this function.
After the fiber tracts have been polynomial-fitted, their structural properties are quantified using the function fiber_quantifier_us (current version, v. 1.0.0). The properties quantified include the pennation angle, curvature, and length. These properties are calculated in a pointwise manner along the fiber tracts. Follow this link for detailed help on this function.
At any stage, the results can be visualized using the function fiber_visualizer_us (current version, v. 1.0.0). The user can select the mask, seed surface, and/or fiber tracts for display. Follow this link for detailed help on this function.
- Here's a direct link to all of the MATLAB functions
- Here's a direct link to all of the help files
- Here's a direct link to a sample data processing script
- Here's a direct link to a sample dataset suitable for practicing using the code
- Here's a direct link to templates for submitting feature requests and bug reports
- Here's the PubMed link for the paper with the algorithm for modeling fascicle orientation that we used.
- Our paper describing this method is in press in the Journal of Applied Biomechanics and will be linked here as soon as the preprint is available.