v5.2.0

Summary of changes in STIR release 5.2.0

This version is 100% backwards compatible with STIR 5.0 as far as usage goes. However, there are changes in the output of scatter estimation and ECAT8 normalisation, see below for more information.

Overall summary

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

Overall code management and assistance by Kris Thielemans (UCL and ASC). Other main contributors were Daniel Deidda (NPL) and Markus Jehl (Positrigo).

Patch release info

• 5.2.0 released 30/10/2023

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

Bug fixes

• Scatter estimation was setting initial activity image to 1 at set-up, effectively ignoring the initial image, aside from geometric info.
• Setting SPECTUB resolution model with STIR python or SIRF divided slope by 10 in error. The problem did not occur when set using parameter file

Changed functionality

• The ECAT8 normalisation (used for the Siemens mMR) code now takes the 4th component axial effects into account. These normalisation factors are therefore different (even up to ~10%). This gives improved axial uniformity in the images. The use of the axial effects can be switched off by adding setting use_axial_effects_factors:=0 to the parameter file (see an example in examples/Siemens-mMR/correct_projdata_no_axial_effects.par), or the class member of the same name.
  In addition, the Siemens normalisation header is now read (using a new class InterfileNormHeaderSiemens) such that hard-coded variables for the Siemens mMR have been removed. Further testing of this functionality is still required however.
  PR #1182.
• Interfile header parsing now correctly identifies keywords that contain a colon by checking for :=.
• The set_up() method of the ray-tracing projection matrix now skips further processing if it was already called with data of the same characteristics. This will means that any cached data will be re-used, potentially leading to a speed-up when re-using it from Python.
  PR #1281.

New functionality

• The Discretised Shape3D shape/ROI has now an extra value label index. For ROIs, this allows using a single volume with multiple ROIs encoded as labels, such as output by ITKSnap and many others. When used as a shape in generate_image, it could be used to extract a single ROI from such a label image.
  PR #1196.

• Global variables in SPECTUB have been substituted by class members, such that multiple SPECTUB projectors can be used.
  PR #1169.

• Global variables in PinholeSPECTUB have been substituted by class members, such that multiple PinholeSPECTUB projectors can be used.
  PR #1212.

• Scatter estimation is now smoothed in axial direction for BlocksOnCylindrical scanners.
  PR #1172.

• InverseSSRB now works for BlocksOnCylindrical after a rewrite.
  PR #1172. /

• Parallelised function set_fan_data_add_gaps_help across segments to reduce computation time.
  PR #1168.

• New utility SPECT_dicom_to_interfile which reads a DICOM file with SPECT projection data and extracts the data and writes one or more Interfile 3.3 headers (still somewhat preliminary).
  PR #1182.

• The new stir_timings utility is mostly useful for developers, but you could use it to optimise the number of OpenMP threads to use for your data.
  PR #1237.

• New classes SegmentIndices, ViewgramIndices and SinogramIndices, used by ProjData related classes, as opposed to having to specify all the elements directly, e.g. in C++

        auto sinogram = proj_data.get_sinogram(sinogram_indices);
  

  This makes these functions more future proof, in particular for TOF. The older functions are now deprecated. Note that as Bin is now derived from ViewgramIndices, instantations of Bin can now be used to specify the indices as well in most places.
  There is still more work to do here, mostly related to the symmetries.
  PR #1273.

Python (and MATLAB)

• Examples use stir.ProjData.read_from_file as opposed to stir.ProjData_read_from_file. The former is supported since SWIG 3.0, and the default from SWIG 4.1.
• Addition of DetectionPosition and DetectionPositionPair.
• bin.time_frame_num is now no longer a function in Python, but acts like a variable (as the other Bin members).
• Addition of RadionuclideDB

New examples

• examples/python/construct_projdata_demo.py illustrates constructing a ProjDataInMemory

Changed functionality

• Scatter estimation was resetting the activity image to 1 before each iteration. This led to cases where the reconstructed image (and therefore the scatter estimation) did not converge, especially when using a small number of sub-iterations. Now, the reconstructed image is continuouslu updated between scatter iterations by default. This should also allow users to use less sub-iterations, therefore saving some time for the scatter estimation. The old behaviour can be re-enabled by setting restart_reconstruction_every_scatter_iteration to true either via a parameter file or via the set_restart_reconstruction_every_scatter_iteration() function.
  PR #1160.
• energy resolution functions and keywords have now more documentation. Scanner::check_consistency also checks if the energy resolution is less than 20 (as it is FWHM/reference_energy).
  PR #1149.
• Errors now throw std::runtime_error instead of std::string.
  PR #1131.
• The parameter use_view_offset was removed from the interpolate_projdata functions. View-offset is now always taken into account.
  PR #1172.
• The info, warning and error calls are thread safe now (which makes them slower), and the logging output in distributable.cxx was changed from verbosity 2 (which is the STIR default) to verbosity 3. This is to reduce the default output during iterative reconstructions.
  PR #1243.
• The Succeeded class has a new method bool succeeded() enabling more concise code (avoiding the need for comparing with Succeeded::yes which is especially verbose in Python).
• The example files for the Siemens mMR now use lower min/max thresholds for the (single) scatter scale. This gives better results, see Issue #1163.
  PR #1279.

Deprecated functionality and upcoming changes to required tool versions

• The following functions (previously used for upsampling the scatter estimate) have been made obsolete or replaced, and will be removed in STIR version 6.0.0: interpolate_axial_position, extend_sinogram_in_views and extend_segment_in_views
• Constructors/functions in ProjData related classes that explicitly use axial_pos_num, view_num etc in their arguments are now deprecated, and should be replaced by their respective versions that use SegmentIndices, ViewgramIndices or SinogramIndices. The former will not be compatible with TOF information that will be introduced in version 6.0.0.
• Use of the AVW library to read Analyze files will be removed in 6.0, as this has not been checked in more than 15 years. Use ITK instead.
• GE VOLPET and IE support will be removed in 6.0, as we have no files to test this, and it's obsolete anyway.
• STIR version 6.0.0 will require C++ 14 (currently we require C++ 11, but already support C++ 20) and CMake 3.14.

Build system and dependencies

• CMake 3.12 is now required on Windows.
• We now use CMake's OBJECT library feature for the registries. This avoids re-compilation of the registries for every executable and therefore speeds-up building time. Use of STIR in an external project is not affected as long as the recommended practice was followed. This is now documented in the User's Guide.
  PR #1141.
• The error and warning functions are now no longer included from common.h and need to be included manually when used (as was already the case for #include "stir/info.h").
  PR #1192.
• add .h and .i as dependencies for SWIG generated wrappers to make sure they get rebuild. (Currently adding all .h files, which is too much, but CMake needs a fix before we can do this properly).
  PR #1218.

Changes for developers

• moved all functionality in CListEventCylindricalScannerWithDiscreteDetectors to template class CListEventScannerWithDiscreteDetectors (templated in ProjDataInfoT). This enables re-use for generic/blocksoncylindrical scanners.
  PR #1222.
• rewritten ProjDataInMemory to avoid streams, causing a speed-up of some operations, and removing a limit of total size of 2GB.
  PR #1260.

Known problems

• See our issue tracker.

Minor (?) bug fixes

• Small change in scatter simulation to how non-arccorrected bins are computed. Added a check in the construction of non-arccorrected projdata that the number of tangential bins is not larger than the maximum non-arccorrected bins.
  PR #1152.
• extend_segment_in_views does not handle view offsets correctly and does not work for BlocksOnCylindrical scanners
  issue #1177. A new function extend_segment was added that works for Cylindrical and BlocksOnCylindrical and allows extension in tangential and axial direction as well.
  PR #1172.
• sample_function_on_regular_grid did not handle offset correctly in all places
  issue #1178.
  PR #1172.
• Ray tracing projection for BlocksOnCylindrical scanner geometries contained a bug where some bins were swapped across oblique segments
  issue #1223. This sometimes lead to large artifacts in reconstructions.
  PR #1231.

Documentation changes

• Updated the STIR developers guide, which was quite out-of-date w.r.t. C++ features etc.

recon_test_pack changes

• Updated headers of most images and projection data to avoid warnings.

Other changes to tests

• test_Scanner.cxx tests for energy resolution, PR #1149.
• New file test_interpolate_projdata, PR #1141.