# 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

Support for the following will be removed in the next version:

- 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

none

#### 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.