Summary of changes in STIR release 3.0 (dated 25/04/2014)

This version is almost backwards compatible with STIR 2.4 for the user (see below), but not for developers. Required code changes are minor however and detailed below.

This release is the first to handle SPECT data properly. It contains code by Carlés Falcón (Biomedical Image Group (GIB), Universitat de Barcelona) to create the system matrix for SPECT, integrated into STIR by Bertá Martí Fuster (Institute for Bioengineering of Catalonia) and Kris Thielemans (University College London, Algorithms and Software Consulting Ltd), together with some additions and minor bug fixes by the same authors. Additional testing by Charalampos Tsoumpas (KCL), Lefteris Livieratos (KCL) and Kjell Erlandsson (UCL). This work was the result of a collaboration between University of Barcelona, King's College London and University College London, and is reported in

• Berta Marti Fuster, Carles Falcon, Charalampos Tsoumpas, Lefteris Livieratos, Pablo Aguiar, Albert Cot, Domenec Ros and Kris Thielemans,
  Integration of advanced 3D SPECT modeling into the open-source STIR framework,
  Med. Phys. 40, 092502 (2013); DOI 10.1118/1.4816676.
• Berta Marti Fuster, Kjell Erlandsson, Carles Falcon, Charalampos Tsoumpas, Lefteris Livieratos, Domenec Ros, Kris Thielemans,
  Evaluation of the novel 3D SPECT Modelling Algorithm in the STIR Reconstruction Framework: Simple vs. full attenuation correction,
  proc. IEEE MIC 2013, Seoul, Korea

In addition, this version contains updates by Kris Thielemans, UCL: changes to the IO code (currently enabled for projection data only) mean that more information such as modality, patient position and timing is available and kept; improvements to the MPI code and tests, some code-cleanup and improvements to the documentation.

Summary for end users (also to be read by developers)

Important bug fixes

• fix PoissonLogLikelihoodWithLinearModelForMeanAndListModeDataWithProjMatrixByBin: it was processing all events up-to end-time as opposed ignoring the events before start-time.

Changes that break backwards compatibility

• The default projectors for the iterative reconstructions and correct_projdata have changed to use the ray tracing projection matrix. This means that the forward and back projector (used for instance for the Poisson log-likelihood) are now matched by default. If you did specify the projectors in your .par file, results will be identical to STIR 2.x, but if you did not, you could add the following to the parameters of the log-likelihood (if you want to get the same results as with STIR 2.x):

  projector pair type := Separate Projectors
   projector pair using separate projectors parameters :=
   forward projector type := Ray Tracing
   forward projector using ray tracing parameters :=
   end forward projector using ray tracing parameters := 
   back projector type := Interpolation
   back projector using interpolation parameters :=
   end back projector using interpolation parameters := 
  end projector pair using separate projectors parameters := 
  

  Alternatively, when building STIR, you could enable set the (advanced) CMake option STIR_DEFAULT_PROJECTOR_AS_V2 to true (not recommended).
• For the Poisson log-likelihood, the default is now to use subset sensitivities (as opposed to computing them as a fraction of the total sensitivity). This new default is more stable for most algorithms and in particular for OSEM (or OS-OSL) where you see less of a subset-cycle when using the correct subset sensitivity.
  If you need to reproduce the default of STIR 2.x, you can use the following setting

  use subset sensitivities:=0
  

  inside the parameters of the log likelihood.

New directory structure

• Top-level directories are now src, scripts, examples, documentation, doximages. The samples directory is now a sub-directory of examples, and the old examples is now examples/src.
  Warning: when using CMake for building, you have to point it to do the main STIR directory (not STIR/src).
• recon_test_pack and documentation are now distributed in zip files that unpack as STIR/recon_test_pack and STIR/documentation.

New functionality

• new projection matrix for SPECT (called SPECT UB) supporting parallel hole collimators with non-circular orbits, including attenuation modelling and 3D PSF
• modifications to ProjMatrixByBin to allow larger matrices (currently needing uint64 support by the compiler) and clearing the cache
• Interfile 3.3 IO for SPECT projection data.
• reading and writing of images via ITK. As ITK has its own registry of file formats, this extends STIR to support DICOM, Nifti (.nii), MetaIO (.mhdr), NRRD (.nhdr) etc. To enable this, you need to have ITK installed when building STIR with CMake. To write images in any of these file formats (DICOM not supported), you need to set an explicit file format type and set it to ITK .
  Warning: The translation of the geometry between STIR and ITK is currently incomplete as STIR ignores patient orientation and direction information for images.
• New utilities forward_project and back_project for easier scripting of STIR (fwdtest and bcktest now really only should be used for testing.)
• The list_projdata_info utilities has an extra option --exam to list some exam information (patient position and timing).
• The distribution now includes sample scripts (in the examples/PET_simulation folder) for simulating PET data, adding Poisson noise and reconstructing the data.

Changed functionality

• Interfile reading/writing has changed to accomodate SPECT.
• Projection data IO (both static and dynamic) now keeps more information such as modality, patient position and timing. This should mean for instance that convertions between different file formats (e.g. conv_to_ecat7, stir_math -s) preserve more information.
• Interfile reading now exits with an error if a vectored key (such as matrix size) is used before its size is given with the appropriate keyword (such as number of dimensions). In prior versions of STIR, a warning was issued, but a crash could happen afterwards.
• extract_segments now handles filenames with more than one dot. It also writes images with voxel-size equal to the central-bin size of the sinogram (the view dimension is set to 1mm).

Build system

• Using CMake is now recommended (see the wiki). Some options such as shared libraries and SWIG support can only be enabled when using CMake. Hand-crafted project files for Visual Studio are no longer distributed. Hand-crafted Unix Makefiles are still there but getting out-of date (no ITK for instance).
• Compilation when using CMake is speeded-up a bit as dependencies of the tests on STIR libraries are reduced.
• You should now point cmake to the STIR main directory, not STIR/src.

Known problems

• SPECT related
  • Do NOT use current PET projectors on SPECT Data. You will have to choose the "SPECT UB" projector in all cases (see the sample .par files).
  • The quantitative scale of reconstructed SPECT images is generally different than for PET reconstructions. It probably also behaves differently than the PET projectors when using different voxel sizes.
  • Images are still written as PET Interfile (but this is ignored when reading).
  • At present, the collimator model varies the width of the PSF linearly with distance. This was experimentally verified with some collimators (for normal distances to the collimator). However, we need to add the possibility to use different models.
  • list_projdata_info still reports SPECT data as if it's a PET scanner, but you can see all necessary geometric info from it anyway.
  • create_projdata_template only works for PET scanners. For SPECT, you could take the sample Interfile header, modify it to your needs (and create an empty file for the binary data pointed to by the Interfile header).
• Building with shared libraries is currently broken on many (all?) systems due to inter-dependencies between libraries.
• This release is known to fail when both MPI and shared libraries are enabled. You will see linking errors in all non_MPI executables.
• ECAT6 is no longer supported
• The incremental interpolating back-projector still gives problems in the centre of the images on some architectures/compiler/optimisation settings. We recommend to use the ray-tracing matrix (with additional rays) instead.
• When using GRAPHICS=X (i.e. on Unix/Linux/MacOSX) the window displaying the bitmaps is sometimes empty. This might depend on your X server settings. This affects manip_image, manip_projdata and display_projdata. We have currently no work-around (aside from using GRAPHICS=PGM or stir_write_pgm).

Major bug fixes

• The MPI version of OSMAPOSL and OSSPS can now compute the value of the objective function. The corresponding test now works.
• The recon_test_pack routines now have an additional option such that they work with the MPI version.

Minor bug fixes

• small changes to allow compilation with the CLang compiler version 5.0 and with Visual Studio 2013.
• removed an error when writing a usage message when converting SimSET projection data.
• when ECAT6 image IO is enabled, now first check if it's an ECAT6 file (this avoids strange crashes when the file turns out not be ECAT6 after all).

Documentation changes

• Added documentation on new features
• Added documentation on the Interpolation matrix. Somehow we had forgotten to include that before.
• Added more examples of shapes to samples/generate_image.par. Also corrected doxygen of EllipsoidalCylinder for initial/final angle parameters.
• The Wiki expands more and more, so use it in addition to the provided PDFs.

recon_test_pack changes

• updated version number and added some clarification to the README.txt
• added a test script for the SPECT reconstructions

Other changes to tests

• added tests for the ITK IO routines

What's new for developers (aside from what should be obvious from the above):

Major bugs fixed

• see above

New functionality

• SPECT matrix modelling etc (see above)
• expanded the class PatientPosition to allow left/right positioning, unknown positioning, and using DICOM-style abbreviations such as HFS.
  WARNING:The default constructor used to set the position to HFS but now sets it to unknown.
• new classes ImagingModality and ExamInfo. The latter contains the modality, PatientPosition and TimeFrameDefinitions.
• projection data (ProjData, DynamicProjData etc) now have an ExamInfo member such that time frames etc can be passed along. Their constructors have been modified accordingly (NOT backwards-compatible).
• list mode data (CListModeData) changes (NOT backwards-compatible):
  • also has an ExamInfo. This member needs to be set by every derived class.
  • removed CListModeData::read_from_file. Use read_from_file<CListModeData> instead.
  • removed CListModeData::get_scan_start_time_in_secs_since_1970(). Get it via its ExamInfo.
• using the above changes, LmToProjData properly writes time frame information to the projection data.
• changes to ProjDataInfoCylindrical to allow different radii for different views, useful for SPECT (or an elliptical PET scanner?)

Other code changes

• removed a few instances of using std::string etc from the include files to avoid conflicts with global or non-std classes. This might mean you need to put these statements in your .cxx files (or add std:: in various places of course).
• add 3rd argument to BSplines templates to specify type of internal constants (with a good default). This gets rid of a lot of conversion warnings with MSVC but could also potentially speed up calculations.
• Many minor changes to avoid conversion warnings with MSVC.
• modified get_directory_name in utilities.cxx to return "." if the directory info was not given.

Build system

• We no longer add the STIR_LOCAL subdirectory in the main CMakeLists.txt (if STIR_LOCAL is enabled). We now leave that to STIR_LOCAL/stir_extra_dirs.cmake. This effectively means that if you extended STIR by having a CMakeLists.txt in your local directory, it will no longer be picked-up and you will have to edit your local stir_extra_dirs.cmake with something like add_subdirectory(${STIR_LOCAL})
• All CMake help-fules have been moved to a spearate sub-directory src/cmake which is added to the CMazke module path. That means that you should use them for instance as

  include(stir_lib_target)