View source for Pablo-Subcort-Structure

'''All source code:'''

[[Media:segmentation_src.zip]] contains the matlab source code and the shell scripts
Code required to do shape and image statistics training

 svn+ssh://your-cs-login@cvs.cs.unc.edu/cvs/proj/midag/svn/matlab/commonQuantileCode
 svn+ssh://your-cs-login@cvs.cs.unc.edu/cvs/proj/midag/svn/matlab/quantileStats
 svn+ssh://your-cs-login@cvs.cs.unc.edu/cvs/proj/midag/svn/matlab/shapeStat

e.g. on linux: svn co svn+ssh://styner@cvs.cs.unc.edu/cvs/proj/midag/svn/matlab/commonQuantileCode
n

Installed under /tools/Pablo/matlab: add this folder to matlab : Set Path... -> add with Subfolders


'''Empty starting directory with config files:'''

[[Media:newSeg.zip]] contains the config files to start the segmentation


    The Pablo installation is located in /tools/Pablo/linux64

-------------------------------------------------------------------------------------------
    copy "newSeg" folder
    [[Media:newSeg.zip]]
    
    This is a folder which contains all the files required to start the
    segmentation process.  It has the configuration files for Pablo in
    the 'config' folder, a 'param.txt' file which serves as the configuration
    for the shape statistics computed in Matlab, and a blank 'binary_raw3'
    folder for holding the original binary segmentations that m-reps must
    be fit to.
 
    In general the param.txt file should not need to be edited.

-------------------------------------------------------------------------------------------
    put binary segmentations in newSeg\binary_raw3
    - compress_raw3.script can be used to take raw3.gz files, gunzip them, and 
      recompress them using Pablo

-------------------------------------------------------------------------------------------
    cd "newSeg"
-------------------------------------------------------------------------------------------
'''from matlab call:'''

    binary_fits('binary_raw3', 'template_model.m3d')
    
    arguments:
    1) path to directory with binary segmentations
    2) initial m3d model
    
    This file does two stages of m-rep fitting.  In the first stage, the template
    model specified as the second argument to the script is used as the initial
    model.  The initial model is then deformed without any use of PGA shape 
    statistics to fit each of the binary segmentations.  The results of this
    stage are output to 'stage_1\output_m3d'.
    
    After the first stage is complete, all of the files in 'stage_1\output_m3d' are
    used to create a mean m-rep with PGA statistics.  This is done in Matlab
    by calling the 'calculatePGA' m-file.  The results are stored in 'stage_1\pga'.
    The file containing the mean m-rep and PGA modes is called SymMean.m3d.
    
    For the second stage, the SymMean.m3d file from the shape statistics is used
    as the initial model to the binary fitting.  This stage uses the statistics
    which generally produces a better fit than the first stage.  The results of
    the second stage are stored in 'stage_2\output_m3d'.  These represent the
    final m-reps fit to the binary images.
    
    The numbers, such as the surface distance match, output by Pablo for each
    binary fit are stored in log files, either 'stage_1/log' or 'stage_2/log'.
    
    In case this is used for simple shape analysis of the m-rep properties of already existing 
    segmentations, it is advised to run also both stages. It is expected that the second stage
    regularizes the atom correspondence.

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

    training_X_regions('..\gray_raw3',50,'trained_local_50');
    
    arguments: 
    1) path to directory with grayscale images
    2) number of training samples to use (chooses randomly)
    3) path to output directory (script will create it)
    
    Can be either training_global_regions or training_local_regions for image statistics
    
    This file computes both image and shape statistics for a training set which
    will be used as input to a segmentation.  It first creates a directory called
    'training' inside the directory given in the third agrument, and randomly selects
    a given number (second argument) of m3d files from 
    'binary_fitting\stage_2\output_m3d' and copies them to 'training\m3d'.  With 
    these, it computes a mean with PGA modes and stores the result in 'training\pga'.  
    It also computes image statistics based on the randomly-selected training set and 
    stores them in 'training/hist_stats'.  The image statistics are first computed
    for individual files using Pablo, then the Matlab command 'doSPETraining'
    aggregates them and stores the main resulting file as 
    'hist_stats\trained\trainedSPE-from-XX.spe', where XX is the number of training 
    samples.

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

    segment('train_local_50', '..\gray_raw3\2368-004-01_10_T1_crop.raw3','2368-004-01');
    
    arguments
    1) path to training directory
    2) path to target grayscale image
    3) path of output (script will append '.m3d')
    
    
    This file runs a segmentation.  It looks in the given training directory for
    the mean/PGA m3d file in 'training\pga\SymMean.m3d' and uses it as the input
    model to the segementation.  It also looks for the training image statistics
    in '\training\hist_stats\trained\trainedSPE-from-XX.spe' .  Finally, it uses the 
    grayscale image given as the second argument as input for Pablo to run the 
    segmentation.

-------------------------------------------------------------------------------------------
'''For comparing output segmentations to original segmentations:'''


    export_segs_to_byu('gray_raw3','hippoL/seg_train_50');
    
    Arguments:  1) directory with grayscale images
                2) directory with m-rep segmentations (.m3d) to convert
    
    This script takes all the .m3d files in the second argument and converts them to .byu.
    It needs an image file to export them in the correct world coordinates, so the first
    argument points to a directory containing grayscale images.  It assumes all the
    grayscale images are of the same dimension and voxel size, so it always uses the
    first file in that directory to get the world coordinates.  It uses the executable
    m3dToByu.exe (Windows only), which uses Pablo code to export an m3d to byu. This part
    can easily be done manually, but a scriptable version is in development.

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

    byu2gipl.script
    
    This file converts all the .byu files in the current working directory to both
    .iv and .gipl.  It uses MeshConvert to go from .byu to .iv.  It then uses surf2vol 
    to go from .iv to .gipl.  The call to surf2vol uses hardcoded values of 162x162x188 
    for the dimensions and 0.75x0.75x0.75 for voxel size.

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

    volume_overlap('/Autism/autism/longitudinal/all_structures/mrep/raw3','*caudL_pp_crop.gipl.gz',
                   'seg_local_50','dice_local_50.txt');
    
    Arguments:  1) directory containing original .gipl segmentations
                2) string to pick which original segmentations to use
                3) directory containing new .iv segemntations
                4) output file name
    
    This function outputs the volume overlap from the original segmentation surfaces
    to the new segmentations.  It assumes both the original segmentations and new
    segmentations are in .gipl format (the script byu2gipl.script will take .byu files
    of m-rep segmentations and convert them to .gipl).  It then calls ImageStat and 
    concatenates the result of "grep DiceCoef" on ImageStat's output to the user-specified
    output file.

-------------------------------------------------------------------------------------------------
    
    surface_dist('/Autism/autism/longitudinal/all_structures/mrep/raw3','*caudL_pp_crop.gipl.gz',
                 'seg_local_50','sd_local_50.txt');
    
    Arguments:  1) directory containing original .gipl segmentations
                2) string to pick which original segmentations to use
                3) directory containing new .iv segemntations
                4) output file name
    
    This function outputs the surface distances from the original segmentation surfaces
    to the new segmentations.  It assumes the original segmentations are in .gipl format and
    converts them to .iv.  It assumes the new segmentations are already in .iv (the script
    byu2gipl.script will leave both .iv and .gipl versions of the new segmentations).  It
    then calls MeshValmet and concatenates the tail of MeshValmet's output file to the 
    user-specified output file.
    
    To make plots of the output, use plot_surface_dist.

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

    plot_volume_overlap('dice_local_50.txt');
    
    Arguments:  1) input file (should be a file output by volume_overlap.m)
    
    This function just plots all the volume overlap coefficients computed by volume_overlap.m
    in ascending order.  Use the Matlab command 'hold all' between calls of plot_volume_overlap
    to plot multiple lines on the same graph.

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

    plot_surface_dist('sd_local_50.txt');
    
    Arguments:  1) input file (should be a file output by surface_dist.m)
    
    This function plots all the surface distance numbers computed by surface_dist.m
    in descending order.  It takes the 9th column from the output of surface_dist.m, which
    is the mean absolute distance.  It also multiplies the numbers by 0.75 to convert
    from voxels to millimeters since each voxel is 0.75 mm.  Use the Matlab command 'hold all'
    between calls of plot_surface_dist to plot multiple lines on the same graph.