muscle_track_v1.m

Written by Dr Glen Lichtwark (The Univesity of Queensland)
Copyright Dr Glen Lichtwark 2011.

Please cite the following manuscripts in any academic publications arising
from this contribution -

Jarred G. Gillett, Rod S. Barrett, Glen A. Lichtwark
Reliability and accuracy of an automatic tracking algorithm to measure 
passive and active muscle fascicle length changes from ultrasound.  

Cronin, NJ, Carty, CP, Barrett, RS and Lichtwark, G. (In Press). 
Automatic tracking of medial gastrocnemius fascicle length during human 
locomotion. Journal of Applied Physiology.
doi:10.?1152/?japplphysiol.?00530.?2011

This Matlab GUI demonstrates how muscle fascicles from the medial 
gastrocnemius (MG) muscle in humans that are imaged using B-mode ultrasound 
can be automatically tracked using optical flow algorithms utilising an 
affine transformation to track end points of muscle fascicles as determined 
in an initial frame.

This toolbox requires the Image Processing toolbox.

This toolbox utilises Dr David Young's (Susses University) excellent 
algorithms for calculating the optical flow using the affine transformation
extension - 
http://www.mathworks.com/matlabcentral/fileexchange/27093-affine-optic-flow

It also uses Sandra Martinka's Rubberband Line function - 
http://mathworks.com/matlabcentral/fileexchange/1552-rubberband-line

The GUI comes with an example video file which was collected by Mr Jarred 
Gillett (Griffith University) and represents a passive rotation of the 
ankle which in turn changes the length of the MG muscle. This file is 
called passive_length_changes.avi. 

To install -

1. Unzip folder
2. Add folder and subfolders to Matlab path -
	a. Type 'editpath' at the Matlab command line >>
	b. Select 'Add with folder with subfolders' option and select the
	unzipped folder.
	c. Save the new path definitions

To use - 

1. Load the GUI - type 'muscle_track_v1' at the Matlab command line >>
2. Load the video file - File menu --> Open video file...
    An example video file (passive_length_changes.avi or 
    passive_length_changes.mpg) is supplied with GUI. At the end of the 
    video file the frame rate has been decreased to demonstrate effect of a
    low frame rate when large movements occur and hence tracking is poor.
    *** Please note that this video is compressed into a common format that 
    should be able to be opened by most computers. Compressing ultrasound 
    video has the effect of reducing the quality of the image and 
    introducing potential motion artefacts which may hinder tracking 
    performance with different files and hence is NOT recommended. If you
    can not load the video I recommend downloading the DivX codec pack -
    www.divx.com
3. Set the image depth - Image menu --> Set image depth (this is the depth
    of the image in millimeters - before cropping). This only needs to be 
    set once and can be permanently changed by modifying line 78 --> 
    e.g. 'handles.ID = 60;' to 'handles.ID = 70;'  
4. Crop image to desired area if necessary - Image menu --> Crop image
    a. Hold down left mouse button at top left corner of croppable area and 
    drag down to bottom right corner to define croppable area and release 
    mouse button
    b. Resize by dragging corner boxes if necessary
    c. Double click inside box to crop to selected region
5. Determine the frames you want to analyse - 
    a. Select first frame and click '[' button to cut frames before. 
    b. Select the final frame and click ']' button to cut frames after.
6. Define the fascicle end points in the middle of the image - Click the 
    'Define fascicle' button and then select an end point at the 
    superficial border of the muscle and then use the rubber band line to 
    follow the line of action of the fascicles down to the deep border of 
    the muscle.
7. Define the muscle region of interest (ROI) which is the area inside the 
    deep and superficial borders of the muscle (see example_fascicle.tif 
    for example of defining the ROI and the fascicle end points). 
    a. Select points which define borders of the ROI and select the first 
    point to close of ROI polygon (select as many points as necessary).
    b. Double click inside the ROI to accept ROI or adjust points in ROI if 
    necessary and then accept.
8. Advance forward by a frame by clicking the right arrow on the the frame
    slider bar. The new frame and the new tracked fascicle should be shown.
8. If happy with tracking from manual advancing of frames, select the 
    'Process All' button to process all frames from the current frame.
10. Save the muscle fascicle length and pennation angle data from the 
    tracking of each frame to a text file for viewing/plotting.
11. Clear tracking (Clear tracking button) and reset image (Image menu --> 
    Reset image). 

Other function -
Save and Load Fascicles (Tracking Menu --> Fascicle Tracking --> Load 
Fascicle or Save Fascicle) which saves the coordinates of the fascicle in 
the current frame (saved to a MAT file) or loads the coordinates from a MAT 
file made from the Save function.
Affine flow algorithm settings can be changed (Tracking Menu -->
Affine Flow Settings)
Save Image saves the current frame and any fascicle and/or ROI drawings to 
a TIFF image file (File Menu -- Save Image)



