README file for STIR recon_test_pack version 6.2 (and later versions?)
----------------------------------------------------------------------

This test pack runs some simple tests to check if various STIR reconstruction
algorithms, correct_projdata, generate_image and stir_math (and optionally some ECAT utilities)
work as expected. This works mostly by checking
their output with output generated by the STIR team itself.

Running the test pack is automatic, but takes a few minutes (depending
on your hardware of course).

Tests are independent of each other, as each test uses the 'good' files
as input.

The run_*test*.sh files are (Bourne) shell scripts that run all tests 
automatically. run_*tests.bat is the corresponding DOS/Windows batch file
(currently not available for all tests).

The scripts write some diagnostic output to stdout. Output of
all programs is redirected to log files. In case anything is wrong, these
might contain something useful. Please check the FAQ on the STIR Wiki if
you have test failures. If you cannot solve the problems, email to
the user's mailing list (see http://stir.sourceforge.net for info), with all log 
files attached to the email.

Warning:
Any existing files called my_*s or my_*v will be deleted before the actual
tests start. This is because all tests generate such files and we do not
want to have any confusion with files that remained from a previous run.


Run the tests as follows.

Note: in the command line description the notation [] is used to
denote an optional argument.

Prerequisites:
---------------
You need to have installed STIR into a target directory first, 
i.e. "make install", or build the INSTALL target when using
Visual Studio, XCode or another IDE. You then need to either add the
directory where the STIR executables are copied to your path, or
pass it to the scripts as indicated below.

On Unix/Linux/MacOSX:
--------------------
(this also work on Windows if you installed CYGWIN or MSYS)

Important: if you compiled STIR with the MPI option, you will need to use a special
option to most scripts to tell them how to run the STIR executables. On most 
systems, something like the following would work:

sh run_tests.sh --mpicmd "mpirun -np 4" any_other_arguments_as_below

indicating that MPI is going to use your default configuration with 4 processes.


Testing STIR utilities by comparing output with the output of the STIR team
...........................................................................
sh run_tests.sh [ --mpicmd cmd] [ --nointbp ] 
	(if all executables are in your path)

sh run_tests.sh [ --mpicmd cmd]  [ --nointbp ] my_install_dir/  
	(if you copied the executables to one directory, 
	 but it isn't in your path)

Use the --nointbp option (case is important, don't include the []) if you want to skip 
reconstructions that use  the interpolating backprojector. You
probably want to do this on modern systems using 64bit compilation, as that
backprojector is known to have a problem on many of those processors
in the centre of the image.

sh run_scatter_tests.sh optional_install_path

Testing self-consistency of STIR simulation and reconstruction
..............................................................
This test does a simplistic analytic simulation (no noise) of
a uniform cylinder and reconstructs the data in various ways.
The test checks the ROI mean of the reconstructed image.

sh run_test_simulate_and_recon.sh  [ --mpicmd cmd] [optional_install_path]

Similarly, a test for motion corrected reconstruction of gated data is run as

sh run_test_simulate_and_recon_with_motion.sh  [ --mpicmd cmd] [optional_install_path]

Finally, there are some tests on using SSRB to rebin the data to lower dimensions

sh run_test_SSRB.sh  [ --mpicmd cmd] [optional_install_path]


Testing SPECT reconstructions
.............................
For SPECTUB and PinholeSPECTUB implementations, the following script will 
pass the parameters along when calling the scripts in the subdirectories:
cd SPECT

sh run_SPECT_tests.sh [ --mpicmd cmd] [--usecache] [optional_install_path]

The "--usecache" option will tell OSMAPOSL to keep the SPECT projection matrix in memory 
which means that the reconstruction will be faster IF you have enough RAM memory in your system.


Testing ECAT7 utilities
..............................
If you have compiled STIR to use the LNN matrix library for ECAT7 support.
(ECAT6 support is no longer tested as it usually fails due to bugs in the 
LLN matrix library).

sh run_ecat_tests.sh [optional_install_path]



On Windows:
----------
Note: currently MPI support is not in these batch files. Install CYGWIN or MSYS and use the 
above scripts (which will work executables compiled with Visual Studio)..

Open a command prompt window
cd to where you extracted the test pack.
type

run_tests [ --nointbp ]
	(if all executables are in your path)

run_tests [ --nointbp ] g:\my_install_dir\  
	(if you copied the executables to one directory (on drive g), 
	 but it isn't in your path)

See above for the --nointbp option.

Similarly, to execute tests for ECAT7 routines, do

run_ecat_tests [ install_dir ]


Kris Thielemans
Matthew Jacobson