Summary of changes in STIR release 6.0

This version is 99% backwards compatible with STIR 5.x for the user (see below). Developers might need to make code changes as detailed below. Note though that the locations of installed files have changed. Developers of other software that uses STIR via CMake will therefore need to adapt (see below).

Overall summary

This release is a major upgrade adding Time of Flight (TOF) capabilities to STIR.

This version has a major code-cleanup related to removing old compiler work-arounds, consistent use of override and white-space enforcement.

Overall code management and assistance was Kris Thielemans (UCL and ASC). Other main contributors include: Nikos Efthimiou (UCL, University of Hull, UPenn, MGH) for the TOF framework and list-mode reconstruction, Elise Emond (UCL) for adapting TOF framework for projection-data, Palak Wadhwa (University of Leeds) for adaptations and testing on GE Signa PET/MR data, Robert Twyman for extending projector symmetries to TOF and formalising ROOT-based testing, Nicole Jurjew (UCL) for adaptations and testing on Siemens Vision 600 data. Non-TOF contributors include Daniel Deidda (NPL) and Markus Jehl (Positrigo).

Patch release info

• 6.0.0 released 07/02/2024 GitHub Milestone 6.0

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

Changes breaking backwards compatibility from a user-perspective

• When parsing Interfile headers for projection data and the originating system is not recognised, the previous version of STIR tried to guess the scanner based on the number of views or rings. This was using very old scanners though, and could lead to confusion. These guesses have now been removed.

• (deprecated) support for the GE VOLPET format (an old format used by the GE Advance and Discover LS sinograms when using "break-pointing") has been removed.

• (deprecated) support for the AVW format via the (very old) AnalyzeAVW commercial library has been removed.

• Most installed files are now in versioned directories. The following shows the new and old locations relative to CMAKE_INSTALL_PREFIX, where V.v indicates the major.minor version number, e.g. 6.0:

  • documentation (including examples as subfolder): share/doc/STIR-V.v (was share/doc/stir-V.v)
  • JSON files with radionuclide database: share/STIR-V.v/config (was share/stir/config)

  Developers also need to check the new location to use for STIR_DIR documented below.

Bug fixes

• Interfile parsing no longer gets confused by the use of : in a keyword (e.g., used by Siemens for dates). PR #1267

New functionality

General

• Radionuclide database now has a datasource entry with the radionuclide decay table (lnHB ). This makes it traceable to standardised measures of branching ratios, half lives etc. The change is backward compatible and old format is still supported. However we encourage to use the new one, see src/config/radionuclide_info.json.

TOF of course! This is mostly transparent, i.e. normally no changes are required to the reconstruction code etc. When using Interfile or ROOT files, certain new keywords are required, see examples/samples/PET_TOF_Interfile_header_Signa_PETMR.hs and examples/samples/root_header.hroot. See also the updated STIR_glossary. Please cite the following papers:

• Efthimiou, N., Emond, E., Wadhwa, P., Cawthorne, C., Tsoumpas, C., Thielemans, K., 2019. Implementation and validation of time-of-flight PET image reconstruction module for listmode and sinogram projection data in the STIR library. Phys Med Biol 64, 035004. DOI: 10.1088/1361-6560/aaf9b9.
• Wadhwa, P., Thielemans, K., Efthimiou, N., Wangerin, K., Keat, N., Emond, E., Deller, T., Bertolli, O., Deidda, D., Delso, G., Tohme, M., Jansen, F., Gunn, R.N., Hallett, W., Tsoumpas, C., 2021. PET image reconstruction using physical and mathematical modelling for time of flight PET-MR scanners in the STIR library. Methods, Methods on simulation in biomedicine 185, 110–119. DOI: 10.1016/j.ymeth.2020.01.005

See also the (enormous) PR #304.

Limitations

• Currently on the matrix based projectors support TOF. Note that the implementation is generic but slow: a non-TOF row is computed and then multiplied with the TOF kernel. This is somewhat alleviated by the use of caching. However, as not all symmetries are supported yet, caching of the projection matrix needs substantially more memory than in the non-TOF situation.
• We do not have TOF scatter simulation/estimation yet.

<!-- -->

• Radionuclide information is read from Interfile and GE HDF5 headers. If the radionuclide name is recognised to the STIR database, its values for half-life etc are used, as opposed to what was recorded in the file (if anything).
• list_lm_events now has an additional option --event-bin which lists the bin assigned for the event (according to the "native" projection data, i.e. without any mashing). In addition, the --event-LOR option now also works for SPECT (it was disabled by accident).
• stir_list_registries is a new utility that list possible values of various registries, which can be useful to know what to use in a .par file.

Python (and MATLAB)

• exposed ProjMatrixByBinPinholeSPECTUB PR #1366
• PR #1288
  • exposed ListRecord etc, such that loops over list-mode data can now be performed in Python (although this will be somewhat slow). See examples/python/listmode_loop_demo.py.
  • added LORAs2Points,LORInCylinderCoordinates, LORInAxialAndSinogramCoordinates and PointOnCylinder. Warning: renamed FloatLOR to LOR, and same for derived classes.
• add DetectionPositionPair.__repr__ for printing and change order of text in DetectionPosition.__repr__ to fit with constructor to avoid confusion. PR #1316

Changed functionality breaking backwards incompatibility

General

• ProjDataInfo::ask_parameters() and therefore create_projdata_template has changed:
  1. If the scanner definition in STIR has TOF capabilities, it will ask for the TOF mashing factor.
  2. The default for arc-correction has changed to N, i.e. false.
  3. Default value for span is now 11 for Siemens and 2 for GE scanners.
  4. The span=0 case (i.e. span-3 for segment 0, span=1 for oblique ones, erroneously by STIR used for the GE Advance) is no deprecated. GE uses span=2. (Reading a "span=0" case is still supported)
• Projection-data related classes have accessors with an optional make_num_tangential_poss_odd argument (defaulting to false), which made the returned argument a different size. This has been deprecated since version 5.0. Setting this argument to true will now raise an error.

Python (and MATLAB)

• renamed FloatLOR to LOR, and same for derived classes.

Changed functionality

• We now always check (in ProjDataInfo*NoArcCorr) if number of tangential positions in the projection data exceeds the maximum number of non arc-corrected bins set for the scanner. If it is, an error is raised. You might therefore have to adapt your interfile header.

• Interfile header changes:

  • Write STIR6.0 as Interfile key version to denote TOF changes. This is currently ignored for parsing though.
  • (PET) The effective central bin size (cm) keyword for projection data is now only used for arc-corrected data. It is no longer written to the header for non-arccorrected data.

Build system

• CMake version 3.14 is now required.
• C++-14 is now required. In fact, it is possible that C++-11 still works. If you really need it, you can try to modify the main CMakeLists.txt accordingly.
• STIR_CONFIG_DIR is no longer a CMake cached variable, such that it automatically moves along with CMAKE_INSTALL_PREFIX. However, if you are upgrading an existing STIR build, you might have to delete the cached variable, or it will point to the old location.

Known problems

See our issue tracker.

Documentation changes

• Added (some) documentation on TOF features
• Added examples/C++/using_installed_STIR to illustrate how to use STIR as a "library".
• Renamed examples/C++/src to examples/C++/using_STIR_LOCAL.

New deprecations for future versions

• CMake option STIR_USE_BOOST_SHARED_PTR will be removed. It probably no longer works anyway. Therefore stir::shared_ptr will always be std::shared_ptr.
• Direct X-windows display (corresponding to the CMake option `GRAPHICS=X`) will be removed. It is very outdated and sometimes doesn't work.
• remaining files for ECAT6 support will be removed.

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

White-space and style enforcement

• We now use clang-format to enforce C++-style, including white-space settings, line-breaks etc. This uses the .clang-format file in the root directory of STIR. Developers should configure their editor encordingly, and ideally use pre-commit. It also has consequences for existing branches as you might experience more conflicts than usual during a merge. More detail is in documentation/devel/README.md. PR #1368.

Backward incompatibities

ListModeData now has a shared_ptr<const ProjDataInfo> proj_data_info_sptr protected member, and the scanner_sptr member has been removed. Warning: If your derived class had its own proj_data_info_sptr, it should be removed.

virtual ListModeData::get_scanner_ptr() is replaced by ListModeData::get_scanner().

ProjDataInfo*NoArcCorr::get_bin_for_det_pair is now private. Use get_bin_for_det_pos_pair instead.

The GeneralisedObjectiveFunction hierarchy now has a already_set_up member variable that needs to be set to false by set_* functions and checked by callers.

(deprecated) members/functions have been removed

• BinNormalisation::undo and apply members that take explicit time arguments
• extend_sinogram_in_views, extend_segment_in_views and interpolate_axial_position

As mentioned above, installation locations are now versioned. New locations that could affect developers that use STIR as an external project:

• include files: include/STIR-V.v (was include). This should be transparant if you use find_package(STIR).
• CMake exported STIRConfig.cmake etc: lib/cmake/STIR-V.v (was share/lib). The CMake variable STIR_DIR should now be set to <STIR_CMAKE_INSTALL_PREFIX>/lib/cmake/STIR-V.v. However, this new location increases chances that find_package finds STIR as it follows conventions better. For instance, STIR can now by found by find_package when setting CMAKE_PREFIX_PATH to what was used for CMAKE_INSTALL_PREFIX when installing STIR (indicated as STIR_CMAKE_INSTALL_PREFIX above). Moreover, if you use the same CMAKE_INSTALL_PREFIX for your project as for STIR, you shouldn't need to set STIR_DIR nor CMAKE_PREFIX_PATH.

New functionality

TOF related

• Scanner now allows storing TOF information. This is currently not yet done for all TOF-capable scanners though. Contributions welcome!

• All projection-data related classes and their members now have a TOF bin index and related information. At present, old-style accessors are in an awkward format such as

            auto sino = proj_data.get_sinogram(ax_pos_num, segment_num, false, timing_pos_num);

  These are deprecated since version 5.2 and should be replaced by

            const SinogramIndices sinogram_idxs{ax_pos_num, segment_num, timing_pos_num};
            auto sino = proj_data.get_sinogram(sinogram_idxs);

• List-mode data for TOF-capable scanners need to pass the relevant information through appropriately of course.

Non-TOF related

• Projectors now have a clone() member, currently returning a bare pointer (like other STIR classes).
• Bin can now be output to stream as text.
• Added RunTests::check_if_equal for Bin.
• KeyParser has a new facility to add an alias to a keyword. This can be used to rename a keyword for instance while remaining backwards compatible. By default, a warning will be written, but this can be disabled.

Changed functionality

TOF related

• ProjDataInfoCylindricalNoArcCorr::get_all_det_pos_pairs_for_bin is in most places intended to return the physical locations. However, a `DetectionPositionPair` also contains (unmashed) TOF bin information. This will be further complicated once energy windows are supported. The method therefore has an extra boolean argument ignore_non_spatial_dimensions, which defaults to true.
• multiply_crystal_factors is essentially a non-TOF calculation. When given TOF projection data, it will "spread" the non-TOF result equally over all TOF bins. This is also appropriate for randoms_from_singles.

Code clean-up

• Clean-up of various work-arounds such as STIR_NO_NAMESPACES, STIR_NO_MUTABLE, BOOST_NO_TEMPLATE_SPECIALIZATION, BOOST_NO_STRINGSTREAM and various items specifically for VC 6.0.
• Consistently use override in derived classes, via clang-tidy --modernize-use-override.

Test changes

recon_test_pack changes

• additional tests for TOF, expansion of some existing tests for TOF
• updated version number and added some clarification to the README.txt

C++ tests

• additional tests for TOF, expansion of some existing tests for TOF