Tom Frese, May 9, 2001. frese@ecn.purdue.edu



I. Overview
-------------------------------------------------

   This directory contains programs for Bayesian MAP 
   reconstruction of PET data. The algorithm uses a  
   generalized Gaussian Markov random field (GGRMF)  
   prior model and iterative coordinate descent (ICD) 
   optimization of the MAP equation.

   The code is general purpose and uses Matlab 5 file
   format for input and output files. 

   The main program for the MAP reconstruction is called
   emisnew. In addition, a utility 'for' for noisy forward 
   projection of images is supplied (see section V in this
   file).

   The directory EXAMPLES contains five examples
   of how emisnew can be used for reconstruction.
   See Section III in this file for more details. 

   Before you can use this code, you will need
   to edit src/Makefile and compile the programs. 
   Details about compilation/installation can be
   found in README.INSTALL.

   For a few important details about the projection matrix
   computation please see section IV.




II. Using the program 
-------------------------------------------------

   After compilation you will find a file 'emisnew'
   in the MAP_ICD directory. Typing 'emisnew' at
   the command prompt will return the command-line
   syntax:
   -------------
      Usage:
      emisnew [-i #iter (10)] [-s sigma (10.0)] [-p GGMRF_param (2.0)] 
        [-f field_of_view_mm (200.0)] [-r recon_resol (128)] 
        [-I interpolate_output] [-T attn_corr.mat] input.mat 
        initial.mat output.mat

      Use 'none' for constant initial condition.
   -------------

   Note that parameters in brackets [ ] are optional where
   the value in () is the default used if the parameter is not
   specified in the command line. 
   A detailed description of the syntax is listed below:

1) input.mat
------------
   Filename for file containing the sinogram data (e.g. data/mri_sino.mat).
   The matlab file must contain the following variables:

   counts	sinogram matrix, rows=displacements, cols=angles  
   
   n_t          number of displacements (#rows in counts)
 
   n_theta      number of projection angles (#cols in counts)

   delta_t      projection spacing (displacement in mm)

   delta_theta  angular projection spacing (in rad)
                typically, delta_theta=pi/n_theta

   scatter      single value for scatter correction
                (this is the value for
                a single projection count, e.g. what would be 
                subtracted from each count before FBP recon).

   t_0          displacement of first projection, i.e. for first 
                row of counts matrix, in mm. For a centered projection array,
                this should be 
                  t_0 = -1.0*(n_t - 1))/2.0 * delta_t;

   theta_0      first projection angle, i.e. angle corresponding to
                first column of counts matrix.


2) initial.mat
--------------
   Filename for matlab file containing the initial condition
   for the reconstruction optimization. The file must contain
   a matrix called 'img' that is of the same resolution as 
   that specified for the reconstruction (-r flag).

   By entering 'none' at the command-line for initial.mat,
   the algorithm uses a constant initial condition that matches
   the total count in the measured sinogram. However, this is NOT
   recommended as the ICD algorithm converges VERY slowly 
   for a flat initial condition (see example 1).

   A good initialization can be obtained using a multiresolution
   strategy (see examples 2-5). Specifically, a shell script
   can be used to perform a series of reconstructions at different
   resolutions. You can start with a resolution  
   of say 32 x 32 pixels with a constant initial condition ('none').
   Use the result to initialize the next finer reconstruction 
   at 64 x 64 pixels (-r 64), then use that result to initialize
   the reconstruction at 128 x 128 pixels until you are at the
   desired resolution. The overall procedure is typically much faster
   than a single reconstruction at the finest scale since, due to
   the good initialization, fewer computationally expensive fine
   scale iterations are necessary. Note that the -I parameter
   must be used for the coarse scale reconstructions.

   Another way of obtaining a good initial condition is to use FBP,
   however, it is crucial that the scaling of the FBP image
   matches exactly that of the MAP reconstruction.


3) output.mat
-------------

   Filename for the reconstruction. This file will be written at
   the end of the execution of emisnew and will contain an 'img'
   matrix with the MAP reconstruction.


4) Options
----------
   -i <value>	Number of ICD reconstruction iterations. 

   -s <value>   Scale parameter for the GGMRF prior model.
                This parameter controls the smoothness
                of the reconstruction. Higher value = less
                smoothing, lower value = more smoothing.

   -p <value>   Shape parameter of the GGMRF prior model.
                p=2.0 : Gaussian MRF 
                1<p<2 : generalized Gaussian MRF 

   -f <value>   Field of view for the reconstruction in mm. 
                Typically, this would be something like 2*abs(t_0),
                beware of the default 200mm which may not be appropriate
                for you.

   -r <value>   Resolution of the reconstruction (number of pix
                in each direction, e.g. -r 64 will generate a 
                64x64 pixel reconstruction image).

   -I           Switch on pixel-replication of the output image, i.e.
                interpolation by a factor of 2. This is used for 
                multiresolution initialization such that 
                e.g. '-r 64 -I' will produce an output image of size
                128x128 pixels which can be used to initialize a
                reconstruction at 128x128 pixels (-r 128).

   -T <fname>   Attenuation correction with sinogram in <fname>.
                fname must specify a .mat file containing a 
                matrix called 'trn'. This matrix must have the
                same dimensions as the 'counts' matrix in the 
                emission data file input.mat. The trn counts
                typically are obtained by forward projecting
                a transmission reconstruction. The trn matrix
                should be such that, for FBP reconstruction,
                one would precorrect the emission data by taking the
                ratio counts/trn. NOTE: FOR MAP reconstruction, 
                the emission data must NOT be precorrected! 
                

 




III. Examples
-------------------------------------------------

   The subdirectory EXAMPLES contains the files
   example_1.sh, ... , example_4.sh .

   These examples all execute reconstructions 
   of simulated projection data generated from 
   the image in data/mri_groundtruth.mat. The
   sinogram files are data/mri_sino.mat and
   data/mri_sino_wattn.mat.

   example_1.sh: This example performs a reconstruction
                 at a resolution of 128 by 128 pixels
                 using a constant initial condition. This
                 does not converge well, but it is
                 the simplest call to emisnew.

   example_2.sh: Shell script that performs the reconstruction
                 as in example_1 but using a multiresolution
                 initialization. Note, that even after only the
                 first iteration at the finest scale, the
                 log-posterior is already higher (=better)
                 than for the final result of example_1.

   example_3.sh: As example 2, but generates its own 
                 sinogram data by using the 'for' program 
                 to forward project the image 
                 data/mri_groundtruth.mat.

   example_4.sh: As example 2, but with transmission 
                 correction (-T flag).

   
   The example_X.sh files contain comments
   with more details.
   The example_X.sh should run as they are once you have
   compiled the code. 
   For reference, the nominal output files for the examples
   are supplied under EXAMPLES/REFERENCE_results .





IV. Projection matrix computation
-------------------------------------------------

1) PROJECTION WIDTH AND SHAPE
-----------------------------

   The emisnew reconstruction algorithm computes
   the tomographic projection matrix not using 
   line integrals, but rather, assuming a triangular
   projection kernel of width 2.34mm. 
   
   The integrals of the projection kernel 
   over the pixel area are (pre-)computed 
   by subsampling the pixels by a factor of 15 in
   each direction and summing the values of the
   projection shape function at the centers of the
   subsamples multiplied by their area.

   The width of the triangular projection profile can
   be set by modifying the define statement
      #define PRJ_WIDTH 2.34
   in ansi_lib_loc/A_comp_dbl_storeflt.c.
 
   The shape can be changed by modifying the 
   subroutine 'proj_shape' in ansi_lib_loc/A_comp_dbl_storeflt.c.


2) STORING THE MATRIX VS. 
   COMPUTING ON THE FLY
-----------------------------

   By default, the code is set up to pre-compute and
   store the tomographic projection matrix in order to
   speed up computation. This may require large amounts 
   of RAM, especially with the wide projection kernel of 2.34mm.

   To configure the code to compute the matrix 'on-the-fly'
   at each iteration, remove '-DSTORE_A_MATRIX' in the 
   CC definition in src/Makefile and recompile.
  
   For the examples provided, storing the matrix 
   results in a speed-up of a factor of 2.3 (on a
   Linux PII 400MHz).




     

V. Utility for forward projection 'for'
-------------------------------------------------

   The program for is a utility that can be used to forward
   project images to generate simulated projection data with
   Poisson noise. However, this program is NOT production code,
   but is for experimentation or can be used as a basis
   to write a more user friendly program. 
   Right now, the geometric parameters such as image size
   and projection spacing are hardwired into the for.c
   code, so before you use it, you have to modify these
   parameters and recompile.





VI. Experimental options
-------------------------------------------------
  The emisnew program has two hidden options that
  are meant for future experimental/research use. 
  Specifically, [-E #iter_param] will switch on
  ML parameter estimation of sigma, the scale parameter
  of the GGMRF, using iter_param iterations of the
  Hastings-Metropolis algorithm. If -E is specified, 
  a mask for the estimation must also be specified
  with 
   -m <fname_mask>
  where the .mat file with filename fname_mask
  must contain a binary image of the same size
  as specified with the -r option. 
  The mask should be 1 roughly over the support 
  of the object to be reconstructed and zero elsewhere.
 

 
