********************************************************************
*    MBIR RECONSTRUCTION SOFTWARE FOR 2D PARALLEL-BEAM X-RAY CT    *
*               by Pengchong Jin, Purdue University                *
********************************************************************

**************
0. Change log
**************
 - created by Pengchong Jin, Purdue University, 11/2013


****************************
1. Installation requirement
****************************
 - GNU C Compiler


**********************
2. Installation steps
**********************
 - enter directory ./src
 - execute "make"
 - an executable named "mbir_ct" will be created in ./


**********************
3. Files descriptions
**********************
 - ./data
  (a) ./data/shepp
      Dataset for a 128x128 Shepp-Logan phantom.
      The original phantom image (.img) and the simulated sinogram (.sino) are under ./data/shepp/input in plain ANSCII format, which can be read directly using "load" in MATLAB.
      The reconstruction parameters setting and execution command are under ./data/shepp/recon.
      The reconstructed image will also be created under ./data/shepp/recon.
  (b) ./data/ncat
      Dataset for a 128x128 NCAT phantom.
      Subdirectory structure is the same as ./data/shepp.

 - ./src
   The source files in C.

 - ./demo.sh
   Demo BASH script.
   It will reconstruct sample images using two sample datasets, Shepp-Logan phantom under ./data/shepp, and NCAT phantom under ./data/ncat.
   It will takes 2-3 minutes to reconstruct both images.
   The reconstructed images with suffix ".rec" will be created under ./data/shepp/recon, and ./data/ncat/recon.

 - ./mbir_ct
   The software executable created after installation.
   Enter command without options to display the manual page.

 - README
   This file.


*************************
4. Usage of the software
*************************
This section explains the use of the software executable ./mbir_ct.

 ******************************************
 4.1 Execute with external parameter files
 ******************************************
 ./mbir_ct can be executed with three parameter files as follows
      ./mbir_ct -i <image parameter file> -j <sinogram parameter file> -k <prior parameter file>
 Sample parameter files are provided with the dataset. Follow the format to create new parameter files for new dataset.

 ************************************************
 4.2 Execute with the specified option arguments
 ************************************************
 ./mbir_ct can also be executed with the specified option arguments. The parameters description and the recommended setting are listed below. Sample BASH script with the specified option arguments can be found under the ./data.

 ************************
 (a) required parameters
 ************************
     -S: sinogram file, should be in plain ANSII format. Each line presents a view.
     -A: (N_theta) number of view angles in the sinogram
     -T: (N_t) number of detector measurements per view
     -a: (delta_theta) view angle spacing in rad
     -t: (delta_t) detector spacing in mm
     -O: output reconstructed image file, ".rec" will be appended.

 ************************
 (b) optional parameters
 ************************
     -x: (Nx) number of pixels horizontally in the reconstructed image, smaller (e.g. 64 or 128) for faster testing, larger for higher resolution image. The default value is set to be equal to number of detector measurements (can be large and makes algorithm slow). Recommend to set it accordingly.
     -y: (Ny) number of pixels vertically in the reconstructed image, should be equal to Nx.
     -f: field of view (FOV) horizontally (and vertically) in mm, assuming squared FOV. The default value is set to be equal to number of detector measurements x detector spacing.
     -r: radius of reconstruction in mm. Pixels outside the circle will be set to zero.
     -w: linear attenuation coefficients of water in mm-1. The default value is 0.0202527 mm-1.
     -u: initial image option. 0 if starts from a constant initial image. 1 if starts from an initial image with the same resolution as the output image. 2 if starts from an initial image with 1/4 size of the output image. Will up-sample the smaller image. The default is to use a constant initial image. Recommend to use a rough estimated image for fast convergence.
     -I: initial image file. Not specified if -u = 0.
     -b: initial view angle in rad. The default value is 0 rad.
     -s: the initial position of the first detector measurement. The default value is set to be -(N_t-1)*delta_t/2.
     -p: if -1, use ML estimate (weighted least square), if 2, use q-GGMRF prior. The default value is 2.
     -q: q parameter of q-GGMRF prior, between 1.0 and 2.0. The default value is 1.2. No need to set it normally.
     -c: c parameter of q-GGMRF prior. The default value is 15 HU.
     -X: regularization parameter. The larger, the less regularization. The default value is 0.8. Change accordingly to balance the noise reduction and edge preserving.
     -W: weights in the likelihood term (weighted least square). 0 if identity weighting, 1 if weight = exp(-sinogram). The default value is 1.
     -h: stopping threshold of average pixel update. 0 if no threshold. The default value is 1 HU.
     -N: number of iterations. The default value is 20 iterations.


********************
5. BibTex Reference
********************

@UNPUBLISHED{mbirsoftware,
        author = "P. Jin and S. J. Kisner and T. Frese and C. A. Bouman",
        title  = "Model-Based Iteartive Reconstruction ({MBIR}) Software for {X}-ray {CT}",
        note   = "Available from http://engineering.purdue.edu/\string~bouman",
        month  = "Nov",
        year   = "2013"
}


**************
6. Bug Report
**************
For bug report, please send an email to Prof. C. A. Bouman (bouman@purdue.edu), Purdue University.