Merge pull request #1636 from KrisThielemans/prep_v6.3.0

Prepare for v6.3.0

Author: KrisThielemans

.github/workflows/build-test.yml

@@ -253,14 +253,18 @@ jobs:
               if ! command -v ninja > /dev/null; then
                   brew install ninja
               fi
-              if ! command -v python3 > /dev/null; then
-                  brew install python
-              fi
               if ! command -v swig > /dev/null; then
                   brew install swig
               fi
               brew install boost nlohmann-json
-              PYTHON_EXECUTABLE=$(which python3)
+              # Temp fix to 3.13 due to https://github.com/UCL/STIR/issues/1638
+              #if ! command -v python3 > /dev/null; then
+              #    brew install python
+              #fi
+              brew install [email protected]
+              brew ls [email protected]
+              PYTHON_EXECUTABLE=$(find /opt/homebrew/Cellar/[email protected] -type f -name python3.13)
+              #PYTHON_EXECUTABLE=$(which python3)
               ;;
             (windows*)
               # this compiles the whole thing so takes ages

CMakeLists.txt

@@ -54,9 +54,9 @@ endif()
 
 ####### Set Version number etc
 set(VERSION_MAJOR   6)
-set(VERSION_MINOR   2)
+set(VERSION_MINOR   3)
 set(VERSION_PATCH   0)
-set(VERSION   060200) # only used in STIRConfig.h.in and swig/CMakeLists.txt
+set(VERSION   060300) # only used in STIRConfig.h.in and swig/CMakeLists.txt
 
 set(STIR_VERSION
   ${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH})

VERSION.txt

@@ -1 +1 @@
-6.2.0
+6.3.0

documentation/STIR-UsersGuide.tex

@@ -44,7 +44,7 @@
 \\[3cm]
 
 \textbf{{\huge User's Guide\\
- Version 6.2}}
+ Version 6.3}}
 \end{center}
 
 \end{spacing}
@@ -130,7 +130,7 @@ \section{
 recommend to read documentation in the following order:
 \begin{itemize}
 \item general overview documents, such as this User's Guide
-\item the \url{http://stir.sourceforge.net/wiki}{STIR Wiki}
+\item the \url{https://github.com/UCL/STIR/wiki/}{STIR Wiki}
 \item 
 online generated documentation (produced by doxygen). This is 
 produced from comments and (partly) code in the source files.
@@ -156,7 +156,7 @@ \subsection{
 # deactivate the environment
 conda deactivate
 \end{verbatim}
-See \url{https://stir.sourceforge.net/wiki/index.php/Installing_STIR_with_conda}{our Wiki page} for
+See \url{https://github.com/UCL/STIR/wiki/Installing-STIR-with-conda}{our Wiki page} for
 more detail, including on how to get a development version.
 
 \subsection{SIRF distributions}
@@ -169,7 +169,7 @@ \subsection{SIRF distributions}
 \section{
 Installation from source}
 This section describes how to install STIR. It is complemented by information on the
-\url{http://stir.sourceforge.net/wiki}{STIR Wiki} with information for specific systems etc.
+\url{http://github.com/UCL/STIR/wiki}{STIR Wiki} with information for specific systems etc.
 
 Note that as opposed to using the instructions below, you can also
 the \url{https://github.com/SyneRBI/SIRF-SuperBuild/blob/master/README.md}{SIRF-Superbuild}
@@ -181,11 +181,7 @@ \section{
 \subsection{
 Installing source files}
 
-Download the source at the \textit{STIR} site: 
-\begin{center}
-\url{http://stir.sourceforge.net }{http://stir.sourceforge.net} 
-\end{center}
-or from \url{https://github.com/UCL/STIR/releases}{github.com/UCL/STIR/releases}.\\
+Download the source from \url{https://github.com/UCL/STIR/releases}{github.com/UCL/STIR/releases}.\\
 Alternatively, if you are feeling adventurous, you can get the most-recent
 developer version (no guarantees!) of STIR from
 \url{https://github.com/UCL/STIR}{https://github.com/UCL/STIR}.\\
@@ -254,7 +250,7 @@ \subsubsection{
 
 \subsubsection{
 Enabling ROOT support\label{sec:installROOT}}
-STIR can read CERN ROOT files from GATE (see section \ref{sec:ROOTIO}). Check the \url{https://root.cern/install/}{installation instructions for ROOT}.
+STIR can read CERN ROOT files from GATE for PET data (see section \ref{sec:ROOTIO}). Check the \url{https://root.cern/install/}{installation instructions for ROOT}.
 
 \subsubsection{
 Enabling ITK support\label{sec:installITK}}
@@ -264,8 +260,8 @@ \subsubsection{
 
 \subsection{
 Building}
-Since version 2.2, \textit{STIR} contains files to build STIR using the platform-independent
-\url{"http://www.cmake.org"}{CMake}. This is now the only option to build STIR as
+\textit{STIR} contains files to build STIR using the platform-independent
+\url{"http://www.cmake.org"}{CMake}. This is the only option to build STIR as
 it is easier for configuration and finding system dependencies.
 \subsubsection{
 Using CMake}
@@ -390,8 +386,8 @@ \subsubsection{
 \texttt{./install} to put the files inside your build directory.
 \item \textit{CMAKE\_CXX\_STANDARD} can be used to tell CMake to add flags to your compiler to use
 a particular version of the C++ standard (if it supports it). It is set 
-to \texttt{11} since STIR 5.0. Other possible allowed values are
-\texttt{14}, \texttt{17} and \textit{20}. More recent version have not yet been tested.
+to \texttt{17} since STIR 6.2. Other possible allowed values are
+\texttt{20} and \textit{23}. More recent version have not yet been tested.
 \end{itemize}
 
 When building the Python code, and you have multiple versions of Python installed,
@@ -418,7 +414,7 @@ \subsubsection{
 
 If you want to use the X windows display routines,  CMake
 should work out-of-the-box if you have suitable libraries installed, see the wiki
-for required packages.
+for required packages. However, these will be removed soon.
 
 { \subsubsubsubsection{X development libraries}
 }
@@ -2175,6 +2171,15 @@ \subsubsection{
 the default backprojector used by FBP3DRP, has a central artefact 
 on some systems (including Sparc and 64-bit AMD and Intel processors).
 
+\subsubsection{
+Spline Reconstruction Technique (SRT2D and SRT2DSPECT)}
+
+Since STIR 6.3, SRT has been added. This is an alternative analytic reconstruction method.
+For SPECT, it has the notable advantage that attenuation can be taken into account correctly,
+i.e., it implements the inverse of the attenuation (2D) Radon transform.
+The version in STIR implements the algorithm from [Fok2006]. A full description is currently
+under review [Kyr2025].
+
 \subsection{
 Scatter Estimation and simulation}
 \label{sec:scatterestimation}
@@ -5636,7 +5641,7 @@ \subsection{
 \subsubsection{
 X Windows display}
 \label{sec:displayX}
-\textbf{Warning} This functionality is deprecated and will be removed in a next version.
+\textbf{Warning} This functionality is deprecated and will be removed in STIR v7.0.
 
 This provides a (very basic) way of displaying bitmaps when using 
 X windows. This works by creating a new window where some of 
@@ -5871,6 +5876,9 @@ \section{
 reconstruction using ordered subsets of projection data. \textit{IEEE 
 Trans. Med. Imaging}, MI-13: 601-609.
 
+{[}Fok2006] Fokas, A. S., A. Iserles, and V. Marinakis. "Reconstruction algorithm for
+single photon emission computed tomography and its numerical implementation." \textit{Journal of the Royal Society Interface} 3.6 (2006).
+
 {[}Fus13]  Berta Marti Fuster, Carles Falcon, Charalampos Tsoumpas, Lefteris Livieratos, Pablo Aguiar, Albert Cot, Domenec Ros and Kris Thielemans, \textbf{ (2013)} Integration of advanced 3D SPECT modeling into the open-source STIR framework, \textit{Med. Phys. 40}, 092502; http://dx.doi.org/10.1118/1.4816676.
 
 {[}Fus14] Berta Marti Fuster, Kjell Erlandsson, Carles Falcon, Charalampos Tsoumpas, Lefteris Livieratos, Domenec Ros, Kris Thielemans, \textbf{(2014)}  Evaluation of the novel 3D SPECT Modelling Algorithm in the STIR Reconstruction Framework: Simple vs. full attenuation correction, \textit{proc. IEEE MIC 2013}, Seoul, Korea.
@@ -5893,6 +5901,9 @@ \section{
 vol. 2, pp. 1339-1342, 
 \url{http://dx.doi.org/10.1109/NSSMIC.1996.591692}{doi 10.1109/NSSMIC.1996.591692}
 
+[Kyr2025]
+Kyriakopoulou, D., A. Fokas, K. Thielemans \textbf{2025}, submitted to \textt{Inverse Problems}.
+
 {[}Lab97] Labbe C, Ashburner J, Koepp M, Spinks T, Richardson M 
 and Cunningham V \textbf{(1997)} Accurate PET quantification using 
 correction for partial volume effects within cerebral structures. \textit{Neuroimage}, 

documentation/STIR-developers-overview.tex

@@ -16,7 +16,7 @@
 \textbf{{\huge STIR \\
 Overview for developers}}\\
 \textbf{Kris Thielemans}\\
-\textbf{\textit{version 6.2}}
+\textbf{\textit{version 6.3}}
 
 \end{center}
 
@@ -316,7 +316,9 @@ \subsection{
 as possible. Instead, we only declare the classes needed, e.g. \textit{class 
 Bin;} instead of \textit{\#include ``stir/Bin.h''.}
 
-
+Include files should not contain statements like \texttt{using namespace std;} or
+\texttt{using std::cos;} (exceptions for the latter are by intention in texttt{shared\_ptr.h}
+and texttt{format.h}).
 
 \subsection{
 Class definitions}
@@ -391,6 +393,12 @@ \subsection{
 is not slowed down. If an assertion is false, the program aborts 
 with info on the file and line number where the assertion failed.
 
+\subsection{Diagnostics}
+Many function use the \textit{info()} function, which will write to
+\texttt{stdout}. It has a verbosity argument, such that more frequent
+diagnostic messages can be disabled, see \textit{Verbosity::set\_verbosity}.
+Setting the level to 0 suprresses all diagnostics output. This is a global setting.
+
 \subsection{C++ conventions}
 STIR uses C++-17 and is compatible with C++-20 to the best of our knowledge.
 For legacy reasons, we have some preprocessor 
@@ -626,7 +634,7 @@ \section{CUDA support}
 STIR 6.2 introduced first versions of some CUDA code. The include file
 \texttt{cuda\_utilities.h} contains some helpers classes to copy
 arrays to/from the device. This is still work-in-progress as objects
-cannot remain on the device.
+need to be copied to be used by the rest of STIR.
 
 \section{
 Overview of classes}
@@ -760,7 +768,10 @@ \subsection{
 
 Currently missing is support for fan-beam data.
 
-List-mode data is supported as well. See the \textit{Listmode} base-class and its hierarchy.
+\subsection{
+List-mode data}
+
+This is supported as well for both PET and SPECT. See the \textit{Listmode} base-class and its hierarchy.
 
 \subsection{
 Data (or image) processor hierarchy}
@@ -981,6 +992,9 @@ \subsection{Objective functions}
 class hierarchy using either a \texttt{ProjMatrixByBin} object, 
 or a \texttt{ForwardProjectorByBin} and \texttt{BackProjectorByBin} pair.
 
+Note that classes exist for Poisson log-likelihood for both (histogrammed)
+projection data and list-mode data.
+
 Often, one includes a penalty (or prior) in the objective function
 (see doxygen documentation for the class \texttt{GeneralisedPrior}).
 The penalty is expected to be a function that increases with higher 

documentation/release_6.3.htm

@@ -128,6 +128,18 @@ <h3>Changed functionality</h3>
         <a href=https://github.com/UCL/STIR/pull/1591>PR #1591</a> and <a href=https://github.com/UCL/STIR/pull/1605>PR #1605</a>
       </li>
   </ul>
+  <h4>Changes to examples</h4>
+  <ul>
+    <li>
+      Python example <code>plot_sinogram_profiles.py</code> has been renamed to <code>plot_projdata_profiles.py</code>
+      and generalised to work with TOF dimensions etc. A small <code>pytest</code> has been added as well.<br>
+      <a href=https://github.com/UCL/STIR/pull/1370>PR #1370</a>
+    </li>
+    <li>
+      Python example <code>ProjDataVisualisation.py</code> now has a vmax slider.<br>
+      <a href=https://github.com/UCL/STIR/pull/1568>PR #1568</a>
+    </li>
+  </ul>
 
   <h3>Bug fixes</h3>
   <ul>
@@ -143,13 +155,14 @@ <h3>Bug fixes</h3>
       your threshold values. Expected scatter tail-fitting scale factors should now be restored to ~1-1.5 (depending on
       the amount of multiple and out-of-FOV scatter).
       See <a href="https://github.com/UCL/STIR/issues/1532">Issue #1532</a> for more detail. Fixed by using averaging
-      functionality of SSRB instead of adding segments for attenuation correction factors.
+      functionality of SSRB instead of adding segments for attenuation correction factors.<br>
       <a href=https://github.com/UCL/STIR/pull/1531>PR #1531</a>
     </li>
     <li>
       Fixed a bug in the distributed LM computation code (introduced in 6.1) that neglected to accumulate outputs when
-      not build with OpenMP.
-      See <a href="https://github.com/UCL/STIR/pull/1566"">PR #1566</a>" . </li>
+      not built with OpenMP.<br>
+      See <a href="https://github.com/UCL/STIR/pull/1566">PR #1566</a>.
+    </li>
   </ul>
 
   <h3>Build system</h3>
@@ -227,11 +240,13 @@ <h3>New deprecations</h3>
     <li>
       <code>truncate_end_planes</code> will be removed in v7.0
     </li>
+    <li>
+      legacy compatibility with version 3, 4 and 5 will be removed in v7.0.
+      CMake options <tt>STIR_PROJECTORS_AS_V3</tt>, <tt>STIR_LEGACY_IGNORE_VIEW_OFFSET</tt> and
+      <tt>STIR_ROOT_ROTATION_AS_V4</tt> will therefore be removed.
+    </li>
   </ul>
 
-  <h3>Other code changes</h3>
-
-
   <h3>Test changes</h3>
   <h4>Python tests</h4>
   <ul>
@@ -246,17 +261,6 @@ <h4>C++ tests</h4>
 
   <h4>recon_test_pack</h4>
 
-  <h3>Changes to examples</h3>
-  <uk>
-    <li>
-      Python example <code>plot_sinogram_profiles.py</code> has been renamed to <code>plot_projdata_profiles.py</code>
-      and generalised to work with TOF dimensions etc. A small <code>pytest</code> has been added as well.<br>
-      <a href=https://github.com/UCL/STIR/pull/1370>PR #1370</a>
-    </li>
-    <li>
-      Python example <code>ProjDataVisualisation.py</code> now has a vmax slider.<br>
-      <a href=https://github.com/UCL/STIR/pull/1568>PR #1568</a>
-      </ul>
 
 </body>