Summary of changes in STIR release 5.1

This version is 100% backwards compatible with STIR 5.0.

Overall summary

• This release includes the first open-source code available for reconstructing pinhole-SPECT datasets (see PR #1100). It contains code by Carlés Falcón (Neuroimaging Group, Barcelonaβeta Brain Research Center) to create the pinhole-SPECT system matrix. Integration into STIR was completed by Matthew Strugari (Dalhousie University) and Kris Thielemans (UCL). This work is reported in
  • Matthew Strugari, Carles Falcon, Kjell Erlandsson, Brian Hutton, G. Andrew Reid, Ian Pottie, Sultan Darvesh, Steven Beyea, Kimberly Brewer, Kris Thielemans,
    Integration of advanced 3D SPECT modelling for pinhole collimators into the open-source STIR framework,
    Proc. IEEE MIC 2022, Milan, Italy
• Improvements to listmode reconstruction by Nikos Efthimiou, see PR #1030.
• Support for PENNPET Explorer listmode data (if proprietary libraries are found) by Nikos Efthimiou, see PR #1028.
• Scatter simulation, estimation and down/up-sampling, randoms handling and ML normalisation estimation adapted for scanner with Block geometry by Daniel Deidda (NPL) and Kris Thielemans (UCL).
• Various small changes to add functionality to Python interface, mainly by Markus Jehl (Positrigo).
• Python projection data visualiser (in examples/python) by Robert Twyman (UCL).

Of course, there is also the usual code-cleanup and improvements to the documentation. See also the 5.1 milestone on GitHub.

Overall code management and assistance by Kris Thielemans (UCL and ASC).

Patch release info

• 5.1.0 released 14/01/2023
• 5.1.1 released 26/08/2023 (2 fixes for numerical precision in tests)
• 5.1.2 released 10/09/2023 (1 fix for numerical precision in tests)

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

Bug fixes

• Fix of find_LOR_intersections_with_cylinder functions in the LOR hierarchy. This fixes the use of the parallelproj projector for non-cylindrical geometries. See PR #1072 and PR #1074.
• Listmode reconstruction was using all events stored before the start-time of the desired time-frame.

New functionality

• New projection matrix for pinhole-SPECT (called PinholeSPECTUB) supporting cylindrical or polygonal pinhole collimators with circular orbits. Corrections include attenuation modelling, intrinsic PSF, and depth of interaction (DOI). DOI corrections currently have a bug. See PR #1100.
• Improvements to listmode reconstruction to enable caching and multi-threading by Nikos Efthimiou and Kris Thielemans, see PR #1030 and PR #1094. When enabling caching of listmode events, one or more files will be written on disk in a binary format, and re-used. This can result in speed-up for some listmode file formats. In addition, multi-threading will then be enabled, which can result in large speed-ups. See the new example file examples/samples/OSMAPOSL_listmode_emml_with_projmatrix.par and the class doxygen documentation for PoissonLogLikelihoodWithLinearModelForMeanAndListModeData and PoissonLogLikelihoodWithLinearModelForMeanAndListModeDataWithProjMatrixByBin.
• Support for PENNPET Explorer listmode data (if proprietary libraries are found) by Nikos Efthimiou, see PR #1028.
• Improvements to penalty functions including Hessian methods, see PR #901.
• Added write_to_file(fname) method to python VoxelsOnCartesianGrid objects and updated recon_demo.py as a demonstration.
• Added a constructor to CListModeDataSAFIR to read data programmatically.
• Added the option to set output proj data on LmToProjData to read data programmatically. This will fill the proj data object only with the listmode data in the last frame that is defined.
• Added the option to set the radius on TruncateToCylindricalFOVImageProcessor.
• Extra functions get_STIR_doc_dir() and get_STIR_examples_dir(), added these on get_STIR_config_dir() to SWIG, change stir_config utility to have corresponding options and only output the requested information (easier for parsing), see PR #1118.
• Added the option to set slope and intercepts on HUToMuImageProcessor programmatically, to not have to rely on JSON.
• Adapting randoms handling and ML normalisation estimation via template to handle BlocksOnCylindrical data as well, see PR #1085.
• Backwards incompatible change to SAFIRCListmodeInputFileFormat to support a small variation of the SAFIR format for the NeuroLF brain PET scanner, see PR #1106.

New examples

• Added sample files for PinholeSPECTUB configurations.

Python

• PyQt5 projection data visualisation (PR #1059)
  Currently added as a Python example. Includes a brief README on how to launch from command line and how to use from within Python

Changed functionality

• LmToProjData is now filtering out coincidences in the same detector number of different rings. These were previously all added to the central bin of the first view, if not removed from the listmode file prior to reading.
• Code refactoring for the Maximum Likelihood functions, including creation of a new (intermediate) class BinNormalisationPETFromComponents, see PR #1079.
• Clean-up of multiply_crystal_factors to rely on existing functionality, therefore reducing code overlap and increasing generalisibility, see PR #1075.
• Install scripts in examples with correct permissions.
• (private) bitfields random or isRandom have been renamed to delayed to avoid confusion. Affected listmode file formats are SAFIR, ECAT962 and ECAT966.
• DiscretisedDensityDensity::has_same_characteristics now adds actual origins and grid spacing to the explanation if they are different.
• ProjMatrixByBinSPECTUB prints an explanation when the attenuation image has different characteristics.

Build system and dependencies

• STIR now requires parallelproj at least 1.0, although 1.2.13 or more recent is recommended.
• ROOT versions until v6.24 supported C++11, subsequent versions require at least C++14. If ROOT v6.24 or later is detected, STIR will now use a minimum of C++14, see PR #1068.
• Various find_package statements and messages have been improved, see e.g. PR #1140.

Known problems

• See our issue tracker.
• PinholeSPECT related
  • There is currently a bug associated with the DOI correction at small angles from the pinhole axis.
  • The quantitative scale of reconstructed SPECT images is generally different than for PET reconstructions. It behaves differently than the PET projectors when using different voxel sizes.
  • 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).

Minor (?) bug fixes

• Made ProjDataInfo*::get_all_det_pos_pairs_for_bin thread-safe. See PR #1084.

Documentation changes

• Added PinholeSPECTUB documentation to STIR-UsersGuide.
• Added stir_config to the STIR-UsersGuide.

recon_test_pack changes

• Added PinholeSPECTUB tests to SPECT directory and updated run_SPECT_tests.sh script to call SPECTUB and PinholeSPECTUB tests from separate subdirectories.

Other changes to tests

• Significant changes made to test_priors that tests the Hessian's convexity, given x(Hx) > 0, and a perturbation response, using gradients, was added to determine the Hessian (for a single densel) is within tolerance. Tests the Quadratic, Relative Difference (in two configurations) and Log-Cosh Penalties (Robert Twyman, UCL).
• recon_test_pack/run_test_listmode_recon.sh now also tests with a time frame.