Merge remote-tracking branch 'upstream/master' into scatter_3d

Author: NikEfth

.appveyor.yml

@@ -5,17 +5,18 @@ skip_commits:
     - .github/**/*
     - '**/*.md'
     - '**/*.html'
+    - '**/*.htm'
     - '**/*.tex'
 
 version: '{build}'
 
 os:
+  - Visual Studio 2022
+  - Visual Studio 2019
   - Visual Studio 2015
-  - Visual Studio 2013
 
 platform:
   - x64
-  - x86
 
 configuration:
   - Release
@@ -24,14 +25,16 @@ build:
   verbosity: detailed
 
 environment:
-  BOOST_ROOT: C:\Libraries\boost_1_63_0
   CMAKE_INSTALL_PREFIX: C:\projects\stir\install\
 
 build_script:
+  # find boost on Appveyor. Version depends on VM
+  - for /D %%d in (C:\Libraries\boost_*) do set BOOST_ROOT=%%d
+  - echo Using Boost %BOOST_ROOT%
   - mkdir build
   - mkdir install
   - cd build
-  - cmake.exe .. -DCMAKE_INSTALL_PREFIX="C:\projects\stir\install" -DCMAKE_BUILD_TYPE=%CONFIGURATION%  -DCMAKE_CONFIGURATION_TYPES=%CONFIGURATION% -DSTIR_OPENMP=ON
+  - cmake.exe .. -DCMAKE_INSTALL_PREFIX="C:\projects\stir\install" -DCMAKE_BUILD_TYPE=%CONFIGURATION%  -DCMAKE_CONFIGURATION_TYPES=%CONFIGURATION% -DSTIR_OPENMP:BOOL=ON -DBUILD_DOCUMENTATION:BOOL=OFF
   - cmake.exe --build . --config %CONFIGURATION%
   - cmake.exe --build . --target install --config %CONFIGURATION%
 

.github/workflows/build-test.yml

@@ -7,10 +7,18 @@ on:
       - '.appveyor.yml'
       - '**/*.md'
       - '**/*.html'
+      - '**/*.htm'
       - '**/*.tex'
 
   pull_request:
     branches: [ master ]
+    paths-ignore:
+      - '.appveyor.yml'
+      - '**/*.md'
+      - '**/*.html'
+      - '**/*.htm'
+      - '**/*.tex'
+
   workflow_dispatch:
     inputs:
       debug_enabled:

CMakeLists.txt

@@ -15,7 +15,7 @@ set(CMAKE_LEGACY_CYGWIN_WIN32 0)
 find_program(CCACHE_PROGRAM ccache)
 if(CCACHE_PROGRAM)
   set_property(GLOBAL PROPERTY RULE_LAUNCH_COMPILE "${CCACHE_PROGRAM}")
-  message(STATUS "ccache found, so we will use this.")
+  message(STATUS "ccache found, so we will use it.")
 endif()
 
 
@@ -26,7 +26,11 @@ SET_PROPERTY(GLOBAL PROPERTY USE_FOLDERS ON)
 if (POLICY CMP0025)
   cmake_policy(SET CMP0025 NEW) # Compiler Id for Apple Clang is AppleClang, see STIR issue #531
 endif()
-  
+
+if(POLICY CMP0074)
+  cmake_policy(SET CMP0074 NEW) # find_package() uses <PackageName>_ROOT variables
+endif()
+
 # add project source to cmake path such that it can use our find_package modules and .cmake files
 set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/src/cmake;${CMAKE_MODULE_PATH}")
 include(src/cmake/SetC++Version.cmake)
@@ -104,7 +108,7 @@ option(DISABLE_UPENN "disable use of UPENN filetypes" OFF)
 
 if(NOT DISABLE_ITK)
    # See if we can find a compiled version of ITK (http://www.itk.org/)
-   find_package(ITK 4.9)
+   find_package(ITK 4.9 CONFIG)
    if (ITK_FOUND)
       include(${ITK_USE_FILE})
    endif()
@@ -138,12 +142,12 @@ if(NOT DISABLE_HDF5)
 endif()
 
 if(NOT DISABLE_NLOHMANN_JSON)
-    find_package(nlohmann_json 3.2.0)# QUIET)
+    find_package(nlohmann_json 3.2.0 CONFIG)# QUIET)
     if (nlohmann_json_FOUND)
-      message(STATUS "nlohmann JSON library found.")
+      message(STATUS "nlohmann JSON library ${nlohmann_json_VERSION} found.")
       set(HAVE_JSON ON)
     else()
-      message(STATUS "nlohmann JSON library not found. Try and set nlohmann_json_DIR if you have it.")
+      message(STATUS "nlohmann JSON library not found. Radionuclide support will be minimal.")
     endif()
 endif()
 
@@ -193,14 +197,17 @@ endif()
 
 # Parallelproj
 if(NOT DISABLE_Parallelproj_PROJECTOR)
-    find_package(parallelproj 1.0)
+    find_package(parallelproj 1.0 CONFIG)
     if (parallelproj_FOUND)
       set(STIR_WITH_Parallelproj_PROJECTOR ON)
       if (parallelproj_built_with_CUDA)
         message(STATUS "Found parallelproj ${parallelproj_VERSION} (will use its CUDA support)")
       else()
         message(STATUS "Found parallelproj ${parallelproj_VERSION} (but using its OpenMP version as it wasn't built with CUDA)")
       endif()
+      if (parallelproj_VERSION VERSION_LESS 1.2.13)
+        message(STATUS "If the above parallelproj info looks incorrect, upgrade it to at least 1.2.13")
+      endif()
     endif()
 endif()
 if (STIR_WITH_Parallelproj_PROJECTOR)
@@ -237,9 +244,20 @@ WRITE_BASIC_PACKAGE_VERSION_FILE(${CMAKE_CURRENT_BINARY_DIR}/STIRConfigVersion.c
 # the installed files, not the source.
 set (STIR_INCLUDE_DIRS "include")
 
-# install the registry sources
-install(FILES ${STIR_REGISTRIES} DESTINATION ${STIR_DATA_DIR}/src)
 
+# Older CMake cannot import or export object libraries. So we have to export
+# the sources and tell the user to explicitly use STIR_REGISTRIES.
+# This will be set to either a list of source files, or a list of object files.
+# See STIRConfig.cmake.in on how we cope with this
+if (CMAKE_VERSION VERSION_LESS 3.12)
+  message(WARNING "Your CMake version is older than 3.12. The STIR_REGISTRIES
+    will be exported as source files only. Please upgrade CMake!")
+else()
+  install(TARGETS stir_registries EXPORT STIRTargets DESTINATION lib)
+endif()
+
+# install the registry sources for older CMake versions
+install(FILES ${STIR_REGISTRIES} DESTINATION ${STIR_DATA_DIR}/src)
 # set STIR_REGISTRIES to this location before export
 # first create a new variable.
 set(INSTALLED_STIR_REGISTRIES)
@@ -253,11 +271,12 @@ foreach(r  ${STIR_REGISTRIES})
 endforeach()
 set(STIR_REGISTRIES ${INSTALLED_STIR_REGISTRIES})
 
+# New create STIRConfig.cmake
 CONFIGURE_PACKAGE_CONFIG_FILE(
   src/cmake/STIRConfig.cmake.in
   "${CMAKE_BINARY_DIR}/STIRConfig.cmake"
-   INSTALL_DESTINATION "${ConfigPackageLocation}"
-   PATH_VARS STIR_INCLUDE_DIRS STIR_REGISTRIES # relocatable variables
+  INSTALL_DESTINATION "${ConfigPackageLocation}"
+  PATH_VARS STIR_INCLUDE_DIRS STIR_REGISTRIES # relocatable variables
 )
 
 # create and install STIRTargets*.cmake for the installation-tree

LICENSE.txt

@@ -1,4 +1,4 @@
-Licensing information for STIR 5.0.2
+Licensing information for STIR 5.1.0
 ----------------------------------
 
 See for more info http://stir.sourceforge.net, section Registration.
@@ -67,11 +67,13 @@ Explicit list of files that carry the PARAPET license
 ./src/include/stir/PixelsOnCartesianGrid.h
 ./src/include/stir/IO/stir_ecat6.h
 ./src/include/stir/IO/interfile.h
+./src/include/stir/IO/InputStreamWithRecordsFromUPENNbin.h
 ./src/include/stir/IO/InterfileHeader.h
 ./src/include/stir/IO/InterfileHeaderSiemens.h
 ./src/include/stir/IO/ecat6_utils.h
 ./src/include/stir/IO/stir_ecat_common.h
 ./src/include/stir/IO/stir_ecat7.h
+./src/include/stir/IO/InputStreamWithRecordsFromUPENNtxt.h
 ./src/include/stir/IO/ecat6_types.h
 ./src/include/stir/ProjDataInfo.inl
 ./src/include/stir/SegmentBySinogram.inl

documentation/STIR-UsersGuide.tex

@@ -5679,6 +5679,31 @@ \section{
 
 See the doxygen documentation for an overview of the directory tree with brief descriptions.
 
+\section{Using STIR in an external C++ project
+\label{sec:ExternalProjectC++}}
+STIR exports its CMake settings. Therefore, an external project can do
+\begin{verbatim}
+find_package(STIR 5.1 CONFIG)
+add_library(my_lib file1.cxx file2.cxx)
+# my_lib uses STIR functionality
+target_link_libraries(my_lib ${STIR_LIBRARIES})
+add_executable(my_exe my_exe.cxx ${STIR_REGISTRIES})
+target_link_libraries(my_exe my_lib)
+\end{verbatim}
+In addition, if your CMake is older than 3.12, you need to add
+\begin{verbatim}
+include_directories("${STIR_INCLUDE_DIRS}")
+\end{verbatim}
+to your CMake file to get the source code files listed in \texttt{STIR\_REGISTRIES} to compile.
+For more recent CMake, this should not be necessary (as \texttt{STIR\_REGISTRIES} is set to
+a list of compiled files).
+
+Note that if CMake did not find the STIR files, you can point it to where they are installed.
+For example, if you installed STIR with
+\texttt{CMAKE\_INSTALL\_PREFIX=\$HOME/install}, set
+\texttt{STIR\_DIR=\$HOME/install/lib/cmake}.
+\footnote{This uses CMake Config mode for \texttt{find\_package}. There is no need for a \texttt{FindSTIR.cmake}}
+
 \section{
 Future developments and Support}
 

documentation/STIR-developers-overview.tex

@@ -1245,36 +1245,22 @@ \subsection{How does the STIR implementation of registries work?}
 
 \section{
 Extending STIR with your own files \label{sect:extendingSTIR}}
+(See the section on using STIR in an external project in the User's Guide if you just want to
+use STIR functionality in your own work.)
 
-If you want to add your own files to the libraries, or have your 
-own main programs, you can of course set-up your own directory 
-and
-\begin{itemize}
-\item 
-make sure that your compiler finds the STIR include files in \textbf{STIR/include}
-\item 
-make sure that you link with all the necessary libraries
-\item 
-make sure that you link with the *\_registries object files
-\end{itemize}
-
-All of this is made easier if you  \textit{installed}
-STIR after you built it (\textit{i.e.} used \texttt{make install} or built the \texttt{INSTALL}
-target in your IDE).
-
-Nevertheless, wipping up your own \textbf{CMakeLists.txt} is slightly painful, and when using the
-above mechanism, it is impossible for STIR to call your own routines, \textit{e.g.} if you
-added your own filter or prior and want to use that during reconstruction.
-For a true integration with  STIR, we provide the following alternative.
+If you want to let STIR use your own
+extra classes, \textit{e.g.} if you
+added your own filter or prior and want to use that during reconstruction,
+you can do this while keeping your own work independent of the STIR sources.
 
 \begin{itemize}
-\item Put all your files in a separate subdirectory or in \textbf{STIR/local} (the distribution 
+\item Put all your files in a separate folder (which can be outside the STIR tree) or in \textbf{STIR/src/local} (the distribution 
 will never contain any files in that directory). Let us call your directory 
 \textbf{mySTIRext} as an example.
 \item Create a file \textbf{mySTIRext/extra\_stir\_dirs.cmake} with CMake statements,
 in particular a list of your subdirectories. For instance,
 \begin{verbatim}
-# add include directory to compiler switches
+# add my include directory to compiler switches (or better: use target_include_directories)
 include_directories(include)
 
 # check CMakeLists in next directories

documentation/history.htm

@@ -11,7 +11,7 @@ <h1>History of public releases of the STIR software</h1>
 The following links give you a summary what has changed. However,
 the ChangeLog is the definite (but tedious) information.
 <ul >
-<li><a href="release_5.1.htm">version 5.1.0 (dated 5 Jan 2023)</a></li>
+<li><a href="release_5.1.htm">version 5.1.0 (dated 14 Jan 2023)</a></li>
 <li><a href="release_5.0.htm">version 5.0.2 (dated 26 May 2022)</a></li>
 <li><a href="release_5.0.htm">version 5.0.1 (dated 11 May 2022)</a></li>
 <li><a href="release_5.0.htm">version 5.0.0 (dated 22 March 2022)</a></li>

documentation/release_5.1.htm

@@ -40,7 +40,7 @@ <h2>Overall summary</h2>
 
 <h2>Patch release info</h2>
 <ul>
-  <li> 5.1.0 released ??/01/2023</li>
+  <li> 5.1.0 released 14/01/2023</li>
 </ul>
 
 <h2> Summary for end users (also to be read by developers)</h2>
@@ -130,12 +130,15 @@ <h3>Changed functionality</h3>
 
 <h3>Build system and dependencies</h3>
 <ul>
-    <li>STIR now requires parallelproj at least 1.0, although 1.2.10 or more recent is recommended.</li>
+    <li>STIR now requires parallelproj at least 1.0, although 1.2.13 or more recent is recommended.</li>
     <li>
       ROOT versions until v6.24 supported C++11, subsequent versions require at least C++14.
       If ROOT v6.24 or later is detected, STIR will now use a minimum of C++14,
       see <a href="https://github.com/UCL/STIR/pull/1068/">PR #1068</a>.
     </li>
+    <li>Various <code>find_package</code> statements and messages have been improved, see
+      e.g. <a href="https://github.com/UCL/STIR/pull/1140/">PR #1140</a>.
+    </li>
 </ul>
 
 

documentation/release_5.2.htm

@@ -0,0 +1,82 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+  <head>
+    <title>Summary of changes in STIR release 5.2</title>
+  </head>
+
+  <body>
+    <h1>Summary of changes in STIR release 5.2</h1>
+
+<p>This version is 100% backwards compatible with STIR 5.0.
+</p>
+<h2>Overall summary</h2>
+
+<p>Of course, there is also the usual code-cleanup and 
+  improvements to the documentation. See also <a href="https://github.com/UCL/STIR/milestone/6">the
+    5.2 milestone on GitHub</a>.
+</p>
+<p>Overall code management and assistance by Kris Thielemans (UCL and ASC).</p>
+
+<h2>Patch release info</h2>
+<ul>
+  <li> 5.2.0 released ??/??/2023</li>
+</ul>
+
+<h2> Summary for end users (also to be read by developers)</h2>
+
+<h3>Bug fixes</h3>
+<ul>
+</ul>
+
+<h3>New functionality</h3>
+<ul>
+</ul>
+
+<h3>New examples</h3>
+<ul>
+</ul>
+
+<h4>Python</h4>
+<ul>
+</ul>
+
+<h3>Changed functionality</h3>
+<ul>
+  <li>energy resolution functions and keywords have now more documentation. <code>Scanner::check_consistency</code> also checks if the energy resolution is less than 20 (as it is FWHM/reference_energy).
+  <br /><a href="https://github.com/UCL/STIR/pull/1149/">PR #1149</a>.
+  </li>
+</ul>
+
+<h3>Build system and dependencies</h3>
+<ul>
+  <li>We now use CMake's <a href=https://gitlab.kitware.com/cmake/community/-/wikis/doc/tutorials/Object-Library>OBJECT library feature</a> 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.
+    <br /><a href="https://github.com/UCL/STIR/pull/1141/">PR #1141</a>.
+  </li>
+</ul>
+
+
+<h3>Known problems</h3>
+<ul>
+<li>See <a href=https://github.com/UCL/STIR/labels/bug>our issue tracker</a>.</li>
+</ul>
+
+
+<h3>Minor (?) bug fixes</h3>
+<ul>
+</ul>
+
+<h3>Documentation changes</h3>
+<ul>
+</ul>
+
+<h3>recon_test_pack changes</h3>
+<ul>
+</ul>
+
+<h3>Other changes to tests</h3>
+<ul>
+  <li><tt>test_Scanner.cxx</tt> tests for energy resolution. <a href="https://github.com/UCL/STIR/pull/1149/">PR #1149</a>.</li>
+</ul>
+</body>
+
+</html>

examples/samples/PET_Interfile_header.hs

@@ -38,11 +38,13 @@ image duration (sec)[1] := 3
 image relative start time (sec)[1] := 1
 
 number of energy windows:=1
+; lower/upper level (in keV)
 energy window lower level[1]:=425
 energy window upper level[1]:=650
 
 Scanner parameters:= 
 Scanner type := unknown
+; energy resolution as a fraction at the reference energy
 Energy resolution := 0.145
 Reference energy (in keV) := 511