Graph-Shifts Java Code Readme File
Jason Corso

This code is dated in the 2007/2008 timeframe.  There is a more up to date C++ version, but it is not ready for release.  (Note, this java version is still faster than our C++ version...)

The code works for 2D and 3D images, defaulting to 3D (medical images).  Specify D=2 on the arg-line for a natural image (an example is provided).


If using this code, please cite one of

[medical imaging]
J. J. Corso, Z. Tu, A. Yuille, and A. W. Toga. Segmentation of Sub-Cortical Structures by the Graph-Shifts Algorithm. In Proceedings of Information Processing in Medical Imaging, pages 183–197, 2007.

[computer vision]
J. J. Corso, A. Yuille, and Z. Tu. Graph-Shifts: Natural Image Labeling by Dynamic Hierarchical Computing. In Proceedings of IEEE Conference on Computer Vision and Pattern Recognition, 2008.



// usage
//  NOTE:  
//     (1) All 3D images should be in the Analyze file format.  When specifying paths to images
//          you can either use the prefix, prefix.hdr, or prefix.img.  All are acceptable, but 
//          for simplicity, I recommend just using the prefix.
//         For 2D images, most popular formats are okay EXCEPT for JPG.
//         3D is the default dimension.
//     (2) Commas (',') or percents ('%') are not allowed to appear in any filename.

//  args[0] is the image data.  You can specify it in three ways:
//     (1) Just put the image filename here.  (e.g., /data/images/pat0.t1w.img)
//           This method only works when you have a single image channel (or RGB natural image)
//     (2) Use a text file that points to the image file(s) to use (multi-channels supported)
//            Each line of the file specifies an image band/sequence,
//             with the first line specifying the manual labels.
//            During segmentation, the manual labels are completely disregarded and only used for evaluation.
//            Example:  Line 1:   /data/CCB40/images/pat0.labels
//                      Line 2:   /data/CCB40/images/pat0.t1w
//            Give the path to the text file as the argument.
//     (3) Also use a text file that points to the image file(s) with a different format.
//            Give each image file (again with the labels image first) separated by commas
//            Example:  Line 1:   /data/CCB40/images/pat0.labels,/data/CCB40/images/pat0.t1w

//  args[1] is the likelihood map data.  You can specify it in two ways:
//     (1) Use a printf style string format to the likelihood maps (e.g., /data/map_%02d)
//     (2) Use a text file that point to the maps file -- sequentially, one path on each line.
//            Example:  Line 1:   /data/map_00
//                      Line 2:   /data/map_01
//  args[2] number of classes (and thus likelihood maps) [integer]
//  args[3] path for writing out the final labels volume (path to write the output file)

//  args[4] (optional) option flag string that specifies various parameters to control the graph-shifts 
//           energy minimization process.  Format is flag1=value1,flag2=value2,etc... 

//          Allowable flags and default values: 


//          D=# (integer, default=3, range=2 or 3) -- Specifies dimension of the images.
//          L=# (integer,default=-1) -- Specifies how many shift levels to consider during the 
//             energy minimization process.  -1 means consider all of the levels and it is default.
//          M=# (integer,default=100000, range M>0) -- Maximum number of shifts to consider before stopping.
//          W=# (float,default=0.7,range 0<=W<=1) -- Weight between appearance term and smoothness term.  
//               For appearance (A) and smoothness (S), the energy is weighted    E = W*A+(1-W)*S.
//          T=# (integer,default=1,range {1,2}) Type of shifts to include.  For value 1, only the original 
//               split/merge shifts are considered, for value 2, the split/merge and spawning shifts are 
//               considered.  Including the spawning shifts increases the computational cost and should 
//               only be used when necessary.
//          V=# (integer,default=0, range >=0) Verbose output during shifting.  Outputs information every #-shifts.
//               0 means no verbose output is made!
//          S=# (integer, default=2, range >= 0 to H) Min level at which to consider spawning (if T=2).
//          P=# (double, default=0.8 range = 0<x<=1) Appearance likelihood threshold when creating 
//                spawn edges.  A spawn edge is created if assigned node likelihood is lower than this.

//          ********* Specifying alternate binary energy terms 

//          The default binary energy term is the boundary smoothness, which simply gives 
//           a weight of 1 to the binary term between any bordering pixels having different models.
//           You can specify alternate binary energy terms by giving the following parameter:
//          BEC=path/to/file  where path/to/file specifies the text file that contains the 
//           information to define the binary energy computer.
//          The BEC file is an ASCII file wherein the first line contains the type of binary term
//           and the following lines contains construction information.
//          Types of terms and definitions:
//            context     -- second line contains number of classes, N, (integer) and the third through
//                            N+3 lines contain the energy terms defining the context matrix.
//                           Each line is a row of the matrix with each entry separated by whitespace.

//          ********* Less Important And Less Useful Flags (that very seldom if ever get changed 

//          H=# (integer,default=4,range H>1) Maximum height of the hierarchical representation.
//          R=# (float, default=0.15, range 0<R<1) Desired reduction factor in the initial bottom-up 
//               construction of the graph hierarchy.

//          ********* For evaluation and testing robustness

//          BAD=#:# (double,long, no defaults for values, but default is OFF)  This initiates a sequence of 
//                  "bad" shifts that perturb the initialization to make the minimization more difficult.
//                  The first is the scale-factor on the energy to achieve before stopping, the second is the random seed.
//          MO=S:S (String to colormap file : String to write output image). Map-Output: This will take the
//                  final output labels and map them into RGB using the colormap file.  
//                  Currently only supported when D=2.


