The IUcalib package computes a system kernel
for the IndyPET scanner.
The package requires Matlab including the statistics
and optimization toolboxes.
(If you get an error concerning the lsqnonlin command, you
might have an old version of the optimization toolbox,
see troubleshooting below).

In addition, the package uses the reconstruction package IUrecon
which is supplied in the IUrecon subdirectory.

The IUcalib directory also contains an example which
can be run to compute a system response matrix.

This README file contains 3 sections:

Section 1: Installation
Section 2: How to run the example
Section 3: General description of the package
Section 4: USE of the package
Section 5: Troubleshooting



Section 1: INSTALLATION
---------------------------------------------
First, unzip and untar the package using the commands

gunzip IUcalib.tgz
tar -xvf IUcalib.tar 

This creates a directory ./IUcalib containing all files.

The matlab part of the package does not require any further
installation. However, you will need to compile the IUrecon
package. The instructions for this are given in 
IUcalib/IUrecon/README.INSTALL. Don't forget to edit the
Makefile.



Section 2: HOW TO RUN THE EXAMPLE
---------------------------------------------
The supplied example consists of the configuration file

IUcalib/config_file 

as well as of the 3 data files 

IUcalib/example_data/norm_990823_37_w.scn
IUcalib/example_data/sysmat_37_w_septa.scn
IUcalib/example_data/res_37_0_w.scn

After installing the package as described in Section 1
you can run the example as follows:

1) Make sure you are in the IUcalib directory
2) Start Matlab by typing 'matlab'
3) At the Matlab prompt, type 'calib'

Depending on your hardware, the program may run
for multiple hours. In the end, it will write the
computed system response matrix to a file called 
IUcalib/system_response.
For reference, the results of running the example 
are also supplied in the directory 
IUcalib/example_reference (see the README there).



Section 3: GENERAL DESCRIPTION OF THE PACKAGE
---------------------------------------------
The package estimates the system response from
a 'moving needle phantom'. The phantom file must
be in CTI .scn file format. It must contain frames
that are all taken at gantry position zero. From frame
to frame, the needle(s) must be moved to the RIGHT by
exactly the same amount. The direction RIGHT here means
physically or in the reconstruction. It corresponds
to a movement to the left in the sinogram.
In the following, this phantom will be referred to as the
mov-ndl phantom. Notice, that the estimation of the
system response is performed using a SINGLE needle only 
(combining data from multiple frames/needle positions).

In addition, the package requires a second phantom
consisting of a SINGLE needle that is approximately 
in the center of the scanner. The file must be in CTI .scn
file format. Just like a standard scan, the file must contain
a number of frames (best >=30) taken at different gantry positions.
The centered needle phantom is used to correct initial estimates
of the x-y position of the moving needle. The same calibration
process also corrects for the center of gantry rotation.

How the package works: Below is a list of the
steps of the program in pseudocode. The top-level
routine in calib.m:

1) read configuration file 'config_file' containing the
   filnenames of the phantoms, normalization files and 
   user configuration.

2) convert moving needles phantom to matlab format with
   normalization applied to sinogram (if normalization file present).

3) get an initial rough estimate of the initial 
   x position of all needles from frame 0 of the sinogram
   (add sino-entries over a few angles, then estimate positions
   of all needles taking the sinogram maxima under the constraint
   that the needles have to be apart by at least the amount specified
   in the config file (min_distance_between_needles_cm)).

4) get a good estimate of the initial x-position x0pos 
   of the selected needle:
   take multiple projections at angle approx. 0 that are on the
   right of the rough estimate of x0pos from 3).
   For each of these projections, plot the number of counts as 
   a function of sinogram frame (=needle position). Fit a Gaussian
   to the resulting 1-D function and estimate 
   x0pos(prj) = displacement_prj - mean_of_Gaussian*needle_movement_per frame  
   
   The final estimate x0pos is then calculated as the mean over
   the x0pos(prj), i.e. x0pos=mean(x0pos(prj)).

5) get a estimate of the initial y-position y0pos
   of the selected needle: Separately, reconstruct all frames 
   of the mov-ndl phantom. Take a small window in x direction around
   the needle and estimate y as the mean in y direction. Then refine
   the estimate by taking a window in y around the estimated mean
   and reestimate mean. (Refinement avoids border effects in 
   the reconstruction).

For iter=0 to MAX_NO_CTR_CALIBS


6) Estimate system response: Knowing the x-y position of the 
   needle, record counts(projection) as function of prj_angle
   difference in displacement between needle and projection. 
   Accumulate the counts over multiple frames, taking into
   account the position of the needle in each frame.
   Map the resulting table to a uniformely spaced grid of size
   N_t, N_th corresponding the physical range [-t_range, + t_range]
   and [-theta_range, + theta_range]. 
   theta: projection angle
   t    : difference in displacement prj. to needle

   After mapping to square grid, filter the response using
   Gaussian lowpass.
   Iter=Iter+1.

7) To calibrate center of gantry rotation and to correct estimates
   x0pos and y0pos, separately reconstruct each frames of the centered 
   needle phantom.
   For each frame reconstruction, calculate the mean x and y position
   using a window. 
   Plot the x and y position over frame number. Errors in x0pos and
   y0pos as well as offsets in center of gantry rotations show up
   as circles, i.e. sin waves in the x and y position over frame.
   Fit 180 degrees of a sin wave through x and y position over frame.
   Allow for different phase but require amplitude to be the same
   for x and y.

   If amplitude of fitted sin waves is smaller than 'tol_rotctr_pix'
   finish, break out of loop. Final system response is in file
   IUcalib/system_response.

   Else correct x0pos,y0pos by estimated difference between 
   center of circle and point on circle corresponding to frame 0.

End For loop (goto 6)

   



Section 4: USE OF THE PACKAGE
---------------------------------------------

1) Edit the configuration file IUcalib/config_file:

scn_file_moving_needles:   filename of moving needles phantom
nrm_file_moving_needles:   corresponding normalization file (.scn)
                           use 'none' if you don't want to use a
                           normalization file.
scn_file_ctr_ptsrc:        filename of centered point source phantom
nrm_file_ctr_ptsrc:        corresponding normalization file (.scn)
                           or 'none'
detector_width_cm:         value, currently 0.33
detector_thickness_cm:     value, currently 3, will be added on
                           to detector separation and half will
                           be added on to radius_detector_curvature_cm.

radius_detector_curvature_cm: nominal value (w/o taking into account
                           detector thickness), right now 40.336229

plane:                     plane for which the calibration should 
                           be performed.

needle_step_mm:            distance that needles are moved to the right
                           (physically, i.e. to the left in sinogram)
                           from frame to frame.

no_needles_in_frame0:      Number of needles that are visible in the
                           sinogram of frame 0

min_distance_between_needles_cm: value, used to roughly estimate
                           the x positions of all needles. 
                           Set this to approx. 0.5-0.7 times the
                           smallest physical distance between the
                           needles.

use_single_needle_no:      Select which needle is used to determine
                           system response. THE NEEDLE NUMBER COUNTS
                           FROM THE RIGHT PHYSICALLY, i.e. from the
                           left in the sinogram of frame zero.
                           YOU CAN ONLY SPECIFY NEEDLE THAT ARE VISIBLE
                           IN THE SINOGRAM OF FRAME ZERO.

verbose_level:             0: no graphical output, only text. This way
                              you can run it in the background.
                           1: adds some figures: display sinogram
                              of frame 0, unfiltered and filtered
                              system response (meshplot), 
                              and the sin wave fits of calibration
                              (see step 7 in section above).  
                           2: adds plots of the estimation
                              of the initial x and y position of
                              the selected needle. Plot Gaussian 
                              fits used to determine x0pos by profiling
                              projections (see step 4 in section above).
                              Plot Gaussian fits used to determine y0pos  
                              from frame reconstructions 
                              (see step 5 in section above).
                            I would recommend level 1 unless you must 
                            run in the background or you need to do 
                            some debugging.



2) OPTIONAL: Edit parameters in the head of calib.m:
   This should only be necessary if you have problems. 
   

3) Run the program:
   a) make sure you are in the IUcalib directory.
   b) start matlab 
   c) at the matlab prompt, type calib.
  

4) After the program finishes, the estimated system response
   is in IUcalib/system_response.
   Notice, that this file is saved at iteration of the
   calibration, so it does not contain the correct information
   when the program is still running.


Section 4: TROUBLESHOOTING
---------------------------------------------

1) If you get an error concerning the 'lsqnonlin'
   command: You are probably using an older version of
   the optimization toolbox that uses the command 'leastsq'
   instead of lsqnonlin. You can change the lsqnonlin commands
   in
   IUcalib/matlab/findx.m   and in
   IUcalib/matlab/findy2.m

   to leastsq statements with similar syntax. In the next version
   I will provide the leastsq statements commented out.

2) If things go wrong, consider changing the values set in the header
   of calib.m. Some NOTES:

   a) The number of iterations for the frame reconstructions of the
      centered point source is set to 70 which might seem high. However,
      since the ML reconstruction is not that stable, I have
      found the estimates to be a lot better than with say 20 iterations.
      In addition, the sigma for the reconstruction is hard-wired 
      to a large value corresponding to ML reconstruction. That has worked
      much better than trying regularization.

   b) NORMALIZE_SYSTEM_RESPONSE_MEAN: Right now, the program is set
      to normalize the amplitude of the final system response. 
      This can be switched off by setting  
      NORMALIZE_SYSTEM_RESPONSE_MEAN=0.

   c) If the program finishes and you get an error 
      'Maximum number of iterations reached. 
       Result NOT within specified tolerance 
       (i.e. radius of circle).'
      you should check if the plots (verbose_lev=1) seem reasonable.
      If so, you might want to increase the value of
      tol_rotctr_pix to something between 0.4 and 1.
      It should not need to be greater than one.
      In addition, you can increase the maximum number of 
      calibration iterations MAX_NO_CTR_CALIBS, the default is
      2 which essentially is only a single correction iteration.


