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

                   USAGE OF TSMAP PACKAGE

               Hui Cheng and  Charles A. Bouman
            Electronic Imaging System Laboratory
         School of Electronic and Computer Engineering
                     Purdue University
                 West Lafayette, IN 47907
               {hui, bouman}@ecn.purdue.edu

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

The TSMAP is a supervised multiscale contextual image segmentation
algorithm. In TSMAP, the textural information of each image class is 
specified as a Gaussian-mixture model, and the contextual information
is modeled using the Class Probability Tree (CPT). The parameters of 
TSMAP are estimated from a data base which contained original images
and their ground truth segmentations.


1.  Contents of TSMAP package 

	configure - run this script to perform system configuration

	Makefile - compile and link the package

	example/ - a directory containing a demo of how to use TSMAP

	manual/ - a directory containing a software user_manual

	segment/ - the TSMAP segmentation algorithm

	training/ - parameter estimation for the TSMAP segmentation algorithm

	test_img/ - original and test images for training and testing

	utilities/ - ANSII C utility subroutines used for both parameter 
            	estimation and segmentation

	tiff_lib/ - standard tiff library for reading and writing tiff images



2.  How to use TSMAP

.  TSMAP can be complied on Linux operating
     system by:
      -  The first running the shell script ./configure
      -  Next type "make" in the TSMAP/ directory to compile all the code
  .  TSMAP can be complied on Solaris 2.X, HPUX 9.X or 10.X operating
     systems by:
      -  The first running the shell script ./configure
      -  Next change the CFLAG option in the following Makefiles:
      ./segment/src/Makefile
      ./utilities/src/Makefile
      ./training/src/Makefile
      
      All that is needed is to comment out the current CFLAG statement and
      uncomment the statement for cc.   


      -  Next type "make" in the TSMAP/ directory to compile all the code



     
  .  To run the demo, go to TSMAP/example/,  type "./Demo"
       
      -  The first part of the demo estimates model parameters from training
         images stored in 
             TSMAP/test_img/
         The estimated parameters are then save under 
             TSMAP/example/par/

      -  After parameter estimation, the original images in 
             TSMAP/test_img/
         are segmented and the results are saved in
             TSMAP/example/results/

  .  To perform parameter estimation and segmention on your own images, please
     read the shell files  "Demo", "runTraining" and "runSegment", and tailor
     these files to your needs.
     
  .  Image file format:  TSMAP can read either tiff or pxm images.
     The segmentation will be saved as a palette image using tiff format 
     with a pre-specified color map.

  .  The training algorithms produces a set of parameters that capture
     the behavior of the distinct classes in the training data. 
     Once these pararmeters are extracted, they may be repeatedly used
     to compute segmentations for any new image.

  .  Parameters for running TSMAP training programs 
     "TSMAP/training/bin/EM_Dec", "TSMAP/training/bin/GMM" and 
     "TSMAP/training/bin/CPT".
   
      -i  sample_img.name
         You must provide a file (e.g. "sample_img.name") which contains 
         the file names of all original training images and their 
         corresponding ground truth segmentations.
         The format of this file is as follows:

         ---------------------------------------------------------------------
         lines   |  content of the line  |          meaning
         ---------------------------------------------------------------------
          1st    | nFiles=10             | # of training images, e.g. 10
          2nd    | nClasses=4            | # of classes of the segmentation
                 |                       |    e.g. 4
          3rd    | img_base/img.1.pgm    | path and name of the 1st original
                 |                       |    image
          4th    | img_base/seg.1.hs.pgm | path and name of ground truth
                 |                       |    segmentation of the 1st image
          5th    | img_base/img.2.pgm    | path and name of the 2nd original
                 |                       |    image
          6th    | img_base/seg.2.hs.pgm | path and name of ground truth
                 |                       |    segmentation of the 2nd image
                 |   .......             | 
         21st    | img_base/img.10.pgm   | path and name of the 10th original
                 |                       |    image
         22nd    | img_base/seg.10.hs.pgm| path and name of ground truth
                 |                       |    segmentation of the 10th image
         ---------------------------------------------------------------------

      -o  Output filename  
          All parameters and intermediate results will be saved using
          this name augmented with a appropriate extension.
      
      -P  Percentage of samples taken for parameter estimation
          The range is from 0 to 100 and the default value is 20.
          
          For our demo, when using "-P 5", the training needs approximately
          50 minutes on HP755.  When using "-P 10", the training needs 
          approximately 200 minutes. 
          
          The number of training images, their sizes and the percentage of
          samples taken will determin the size of all sample sets, the 
          training time and the accuracy of the parameter estimation.

      -B  The size of neighborhood.  The package only takes 1x1 neighborhood
          where "-B 1", 3x3 "-B 9", 5x5 "-B 25",  7x7 "-B 49", and 
          9x9 "-B 81".
          
          
      -v  Verbose_level.  0 means no print-out at all.  The default value
          is 1.  A verbose_level less than 50 is recommended.
          
          For training,  if the last digit of the verbose_level is "6", 
          all intermediate results will be undeleted, otherwise they will be 
          all deleted.
                
      -M  maximal number of leaves of CPTs.  It should be greater than
          0 and the default value is 100.
      
      -C  initial number of clusters for Gaussian mixture model. It should 
          be greater than 0 and the default value is 15.   
                 
                 
                 
  .  Parameters for running TSMAP training program
       
      -i  file name of the input image
      
      -o  file name of the output segmentation
      
      -p  file name (common prefix) of the parameter files
          It should be the same name that one specifies using "-o" in
          training.
      
      -v  Verbose_level.  0 means no print-out at all. The default value
          is 1.  A verbose_level less than 50 is recommended.
       
          For segmenting an image,  verbose_level
             [0,  15]    save the segmentation at the finest scale.
             [16, 30]    save segmentations at the 3 finest scales.
             [30, up]    save segmentations at all scales.   
          
                 
      
       
       

