Summary of changes in STIR release 4.1

Overall summary

This release contains mainly code written by

• Kris Thielemans (UCL) for general overview, fixes, help and maintenance
• Palak Wadhwa (Leeds) addition of support for GE Signa PET/MR, with help from many others, including coding by Ottavia Bertolli (UCL), Nikos Efthimiou (Hull), Elise Emond (UCL) and Kris Thielemans (UCL), and supervision by Ch. Tsoumpas (Leeds). This work received help from GE Healthcare with particular thanks to Gaspar Delso, Kristen Wangerin and Floris Jansen. See the following publication for more details
  Palak Wadwha et al.
  PET Image Reconstruction Using Physical and Mathematical Modelling For Time of Flight PET-MR Scanners in the STIR Library
  Methods 2020, DOI: 10.1016/j.ymeth.2020.01.005
• Ander Biguri (UCL) for extending the Signa support to GE PET/CT scanners using RDF9
• Richard Brown (UCL) for wrapping of NiftyPET's GPU functionality for projecting and unlisting
• Robert Twyman (UCL) for Relative Difference Prior, computation of the log-likelihood modification, and GATE geometry check fixes.
• Gemma Fardell (UKRI) for implementing xapyb and sapyb array methods.

See also the GitHub milestone for v4.1

Patch release info

• 4.1.0 released 02/05/2021

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

License change

The license used to distribute STIR has now changed! As opposed to the LPGL and/or GPL license, almost all modifications and additions since version 0.92 in 2001 are now licensed under the Apache 2.0 license. This is a more permissive license than both LGPL and GPL. Please note that older files are still covered by the PARAPET license, which is permissive as well.

Unfortunately there is one exception: updates since PARAPET to the FourierRebinning.cxx are still licensed under the LPGL 2.1 license. Therefore, if you use Fourier Rebinning, you should probably assume that the STIR library is licensed under the LPGL-2.1.

License information is now indicated in the files using SPDX identifiers. This allows easier automatic checking and is also more compact.

Some more information is in the distributed LICENSE.txt.

We would like to thank all previous contributors and their institutions who agreed to relicense their work.

New functionality

• Reading of GE HDF5 data (GE fileformat RDF 9) for the GE Signa PET/MR and recent GE PET/CT scanners (but depending on their software version). We currently read listmode, sinograms and calibration files (except for the WCC (well-counter calibration) files). This code is TOF-ready, but TOF is not enabled pending merge of the TOF Pull Request. Therefore, all reconstructions will be non-TOF.
  See examples in examples/GE-Signa-PETMR (also applicable for PETCT data).
  Warning: currently images will be reconstructed flipped with respect to the standard STIR orientation. This is particularly noticeable when output in Nifti/MetaIO etc. See issue #675.
• A new script create_fdef_from_listmode.sh that can be used to create a single-time frame definition file for a given listmode file.
• Addition of the Relative Difference Prior [J. Nuyts, et al., 2002].
• NiftyPET's GPU projectors have been wrapped. If NiftyPET is installed, these projectors can be used on data from the Siemens mMR. See the example parameter file in examples/samples/OSMAPOSL_NiftyPET.par. NiftyPET's GPU-accelerated unlisting has also been wrapped, also allowing for randoms estimation and norm extraction.
• estimate_triple_energy_window_scatter_sinogram can use different width for the upper and lower energy windows
• stir_math now supports the --output-format option for dynamic and parametric images as well. (An example file using the Multi format is given in the examples/samples folder).
• Interfile and ITK image IO now understand some date/time fields. This required a change to our Interfile version specification to be able to handle time-zones. These can now be added via the same suffix as used by DICOM, e.g. 10:01:01.00+0130.
  Warning: If the time-zone is not specified, we assume it's in the current time-zone without DST. This is dangerous, but allows us to subtract time-fields.
• Added a utility list_lm_info.
• Implementation of a*x+b*y methods xapyb and sapyb where a and b can be scalar or vector types.
• The LmToProjData hierarchy has a new member function set_up(), and more set_* functions, such that it can be used without parsing. Note that it will be automatically called when parsing (which might change in the future).

Deprecated functionality

• ECAT6 and VOLPET files
• bitmap display using X Windows

Changed functionality

• Modification of log-likelihood computation to use more doubles, improving numerical stability, see PR 528.
• Reconstruction algorithms perform now more checks during set_up() etc. However, this means that you have to call set_up() also for analytic reconstruction algorithms. (This was already documented, but not yet enforced).
• copy energy information from the template in the forward_project utility.
• PET scatter improvements:
  • the scatter estimation parsing now prefers specifying normalisation and attenuation via two separate keywords (as opposed to via a chained bin normalisation), (keyword normalisation type) and the attenuation factors. Check the updated sample file. The old parsing keyword Bin normalisation type will still work but is deprecated and will be removed in a future version.
  • scatter estimation uses now more defaults such that you need to have less files.
  • ScatterEstimation has now many more set* functions such that most (all?) parameters can be set from C++/Python (i.e. without parsing).
• The SinglesRates hierarchy has been revised. The SinglesRates classes assumed that stored singles were rates but in practice were totals-per-time-interval (for both ECAT7 and RDF9). It is convenient to be able to access totals and rates, so SinglesRates has now get_singles (returning the singles in the time interval) and get_singles_rate (returning the rate per second). See #615 for more information. Due to the previous confusion, "client"-code will need to be adapted to use either get_singles or get_singles_rate, depending on what is needed.
  WARNING Previous results on ECAT7 dead-time correction using sinograms as singles-info might have been incorrect therefore.
  WARNING We no longer have the capability to test ECAT7 normalisation. Therefore, the dead-time correction code might still not be correct (due to a scale factor).

Python (and MATLAB) interface

Other

• moved examples/src to examples/C++/src
• examples and documentation are now installed, together with doxygen files (if built) into CMAKE_INSTALL_PREFIX/share/doc/stir-majorversion.minorversion.

Known problems

See the Github issues for more information.

• currently images reconstructed using the GE RDF9 functionality will be reconstructed flipped and slightly rotated, causing problems with attenuation alignment for instance. issue #675.
• 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).
• data read from GE RDF9 uses wrong conventions, and images will be reconstructed flipped with respect to the standard STIR orientation. See issue #675.
• 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.
• 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).

Minor bug fixes

• Changes to GATE/root cylindrical PET geometry interpretation, see PR 569.
• OpenGATE energy information is MeV. Added a method to convert between MeV to (STIR convention) keV units when reading root files.

Documentation changes

• Added documentation on new features and fixed some old doxygen problems.

recon_test_pack changes

• added a test for scatter estimation

Other changes to tests

• store data in ProjDataInMemory in the same order as what is used by copy_to and fill_from. This enabled using straight-forward copy. (This change should not affect anyone, except if you relied on a specific order in the buffer before.)
• C++ tests for consistency of forward projection and reconstruction, executed via ctest. This is on top of the recon_test_pack.

Build system

• To enable the functionality for GE HDF5 files, you will need to first install HDF5 libraries. For most operating systems this can be done via your package manager which we highly recommend. You could also download from the HDF5 group download page.

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

Major bugs fixed

• see above

New functionality

• Addition of the randoms_from_singles function.
• Addition of xapyb and sapyb methods for Array and all inherited classes. (code>axpby was introduced on the release_4 branch after STIR 4.0 but is now deprecated).
• ProjDataInMemory now provides iterators.
• added get_sinograms() and size_all() to ProjDataInfo
• added functions for date-time processing
• added ExamInfo.set_energy_information_from

Other code changes

See the ChangeLog, specific items:

• ScatterEstimation now requires calling set_up() explicitly.