\batchmode

\documentclass{article}

\usepackage{geometry}

\usepackage{amsmath}

%\usepackage{a4wide}

%\usepackage{layout}

\usepackage{graphicx}

\geometry{

margin=2.cm

}

\usepackage{setspace}

\usepackage{longtable}

\usepackage{hyperref}

\def\url#1#2{\mbox{\href{#1}{\tt #2}}}

\newcommand{\tab}{\hspace{5mm}}

% attempt to define lower levels than subsubsections

% This does not work very well as you need to put them in extra {}

% to avoid the fonts being messed up etc.

% However, it does work for automatic numbering

%\newtheorem{subsubsubsection}{{}}[subsubsection]

%\newtheorem{subsubsubsubsection}{{}}[subsubsubsection]

\newcommand{\subsubsubsection}[1]{\paragraph{#1}\mbox{} \\}

\newcommand{\subsubsubsubsection}[1]{\subparagraph{#1} \mbox{} \\}

% a simple definition for formatting command lines

\newcommand{\cmdline}[1]{\par \noindent $>$ \texttt{#1}\par}

\setcounter{tocdepth}{4}

\setcounter{secnumdepth}{4}

\sloppy % prevent text from running into margins

\begin{document}

\begin{spacing}{2}

\begin{center}

\textbf{

{\Huge STIR}

\huge

\\[1cm]

\textit{ Software for Tomographic \\ Image Reconstruction}

}

\\[3cm]

\textbf{{\huge User's Guide\\

Version 6.4}}

\end{center}

\end{spacing}

\large

\noindent

K. Thielemans \\

{\it \small University College London; Algorithms and Software Consulting Ltd; formerly Hammersmith Imanet Ltd}\\

Ch. Tsoumpas\\

{\it \small Hammersmith Imanet Ltd; Imperial College London; King's College London}\\

D. Sauge, C. Labb\'e, C. Morel \\

{\it \small Hopital Cantonal Gen\`eve}\\

M. Jacobson \\

{\it \small Technion University}\\

A. Zverovich \\

{\it \small Brunel University} \\

T. Beisel \\

{\it \small Univ. of Paderborn} \\

C. Falc\'{o}n \\

{\it \small Univ. of Barcelona} \\

R. Twyman \\

{\it \small University College London}\\

D. Deidda \\

{\it \small National Physical Laboratory}\\

M. Strugari \\

{\it \small Dalhousie University}

\\

\\

SPDX-License-Identifier: Apache-2.0 AND License-ref-PARAPET-license

See STIR/LICENSE.txt for details.

\newpage

\normalsize

\tableofcontents

\section{

Introduction}

The objective of this document is to give practical information

about the use of the object-oriented library for 3D Reconstruction

of PET and SPECT data, called \textit{STIR}. The most recent version of this

document (and the library) can be found on \\

\url{http://stir.sourceforge.net}{http://stir.sourceforge.net}.

This library was originally developed by the PARAPET

project (funded by the European Union during 1997-2000), extended by Hammersmith

Imanet and made into an Open Source project. \\

The current library has different license restrictions than the

original PARAPET distribution, with nearly all changes since then released under the Apache-2.0 license.

Details on licensing are in the file \textbf{STIR/LICENSE.txt}

that comes with the distribution.

See the publications section of the STIR website for information on which reference

to use for STIR. You will want to read {[}Thi12], see {[}Fus13] for SPECT additions

since STIR 3.0 (for \textit{STIR} 1.x, use [Lab99a], [Lab99b]).

This guide attempts to give end users an overview of all the functionality

in \textit{STIR}. It mainly provides

procedures for downloading and installing the necessary gnu g++

compiler tools and the \textit{STIR} reconstruction building blocks.

Then a brief explanation is given about how to run reconstruction

algorithms as well as additional utilities. A description of

the reconstruction building block library can be found on our

web site (section \textit{documentation}). A short (but very out-dated) review of analytic

and iterative reconstruction methods is available in [PAR1.3]

(available on the STIR web-site).

\section{

A general note on documentation in STIR}

Although we attempt to keep all documentation up-to-date, we

recommend to read documentation in the following order:

\begin{itemize}

\item general overview documents, such as this User's Guide

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

\item check the source itself if in any doubt.

\end{itemize}

Many questions have already been answered via the mailing lists. See the

web-site on how to search these.

Any comments on documentation, and especially contributions are

always welcome. Please use the stir-users mailing list.

\section{Installing STIR via a pre-built version }

\subsection{

Installing via conda}

The easiest way is to use \texttt{conda} (or one of its derivatives such as \texttt{mamba}):

\begin{verbatim}

conda config --add channels conda-forge

conda create -n stirenv stir matplotlib

conda activate stirenv

# use STIR executable or python

# deactivate the environment

conda deactivate

\end{verbatim}

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}

CCP SyneRBI distributes SIRF with its dependencies, including STIR,

see \url{https://www.ccpsynerbi.ac.uk/downloads/}{its download page} for

a Virtual Machine, docker etc. However, only the STIR libraries are included in

these distributions. You can easily install ``full'' STIR on the Virtual Machine though,

see \url{https://github.com/SyneRBI/SIRF-SuperBuild/blob/master/VirtualBox/documentation/README.md}{its documentation}.

\section{

Installation from source}

This section describes how to install STIR. It is complemented by information on the

\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}

of \url{https://www.ccpsynerbi.ac.uk/}{SyneRBI} to build STIR with CMake. This will take care of all dependencies.

Note that you will need to use advanced CMake variables \texttt{STIR\_BUILD\_EXECUTABLES=ON}

and \texttt{STIR\_BUILD\_SWIG\_PYTHON=ON}.

\subsection{

Installing source files}

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}.\\

Note that you can put the distribution in any location (it does

not have to be your home directory).

After unpacking, you should have a \textbf{STIR} directory (subdirectories are described

in the doxygen documentation).

\subsection{

Installing external software}

STIR relies on some external software and a few external libraries which enable certain functionality.

On most systems, you should be able to get these using your package manager.

Please check the Wiki for most up-to-date information.

\subsubsection{

C++ Compiler}

In order to compile and run the \textit{STIR} programs, you will need a compiler

and associated tools such as \texttt{CMake}. These days, any compiler should work. We would love

to hear from any attempts where there are failures.

\subsubsection{BOOST}

The only required external library is the well-respected \textit{boost} library. If it

is not installed on your system, you can download it from

\url{http://www.boost.org}{http://www.boost.org}. Currently \textit{STIR} only

uses the include files from \textit{boost} (so you do not need to build

the boost libraries). However, you will need to tell your compiler

where to find the \texttt{boost/} directory with all the include files

(see section \ref{sec:UsingCMake}).

\subsubsection{JSON}

The \texttt{HUToMu} and \texttt{Radionuclide} database functionality parse a file in JSON format. We use the

\url{https://github.com/nlohmann/json}{nlohman\_json} library for this. Installation

instructions for this library are available on its github page or you can get it via \texttt{conda}.

Without it, we only support a few basic radionuclides.

\subsubsection{

Enabling ECAT 7 support\label{sec:ECAT67support}}

{\em ECAT7 support is no longer tested.}

Older CTI (Siemens) scanners use a file format called ECAT\texttrademark{}.

At present, \textit{STIR} uses parts of the Louvain la Neuve ecat library (called LLN in

the rest of this document).\footnote{\textit{STIR} versions 1.? came with

specific files for ECAT6 support without the need for the LLN library.

However, due to license restrictions this is now no longer the case.}

The library could be available on the OpenGATE website.

You have to download that library and issue 'make --f Makefile.unix'

(or 'make --f Makefile.cygwin' if you are using CYGWIN on Windows)

in the new ecat directory first. Please get a recent version

of this library (dated 20 July 2004 or later) as Merence Sibomana

has introduced various bug fixes, some of which solve problems

that you would otherwise experience when using \textit{STIR} and ECAT7

files.

\subsubsection{

Enabling GE RDF support}

\label{sec:RDFsupport}

This software includes support for GE Raw Data Format (RDF) version 9 files, used

by the GE Signa PET/MR and some PET/CT scanners (depending on their software version). This is only enabled if CMake was able to find HDF5 libraries.

For most operating systems this can be done via your package manager which we highly recommend. You could also

download from the \url{https://www.hdfgroup.org/downloads/hdf5/}{HDF5 group download page}.

\subsubsection{

Enabling ROOT support\label{sec:installROOT}}

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}}

STIR can use \url{http://www.itk.org}{ITK}, a large open source library. Specifying this

enables NRRD, MetaIO and Nifti IO, and DICOM reading.

Use your package manager, including conda or pip, or check the \url{https://itk.org/download/}{installation instructions for ITK}.

\subsection{

Building}

\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}

\label{sec:UsingCMake}

Normal build procedure on Linux/Unix would be something like\footnote{Point \texttt{CMake} to the main \textbf{STIR}

directory, not \textbf{STIR/src}.}

\cmdline{cd /somewhere/nice/STIRbuild/Release}

\cmdline{cmake-gui /somewhere/else/STIR\&}

This will bring up a basic interface where you might to have to choose your preferred

build system (i.e. \texttt{make} on Linux/Unix) and do an initial configuration. Then

you specify build variables. You can press \texttt{Configure} to do additional configurations,

possibly repeatedly and finally \texttt{Generate} for generating your build files\footnote{

When using \texttt{ccmake} as opposed to \texttt{cmake-gui}, the key presses are:

\texttt{c} to do additional configurations, \texttt{g} for generating

your build files, \texttt{q} to quit}. After this step, you will have to run your build system (e.g.\ on Linux etc,

type \texttt{make}, then \texttt{make test}, then \texttt{make install}).

A helpful note: You can specify just to make a single ``target'',

using \texttt{make <target>}. All executable names are targets that

make just the required executable (e.g., \texttt{make FBP2D}). A

useful target for developers is to just make the tests, using

\texttt{make BUILD\_TESTS}. So \texttt{make BUILD\_TESTS \&\& make test}

would build and then run the tests.

On Windows or MacOSX, the procedure is essentially the same, except that you will likely have

to specify more locations. When using Visual Studio, XCode or other IDEs as your build system,

you do not need to specify the Build Type, as you will be able to select that in

your IDE.

More information on using CMake is on the STIR Wiki.

{\subsubsubsection{CMake configuration variables}

}

\newlength{\MakeTableFirstCol}

\newlength{\MakeTableSecondCol}

\setlength{\MakeTableFirstCol}{1.5in}

\setlength{\MakeTableSecondCol}{\textwidth}

\addtolength{\MakeTableSecondCol}{-\MakeTableFirstCol}

\begin{longtable}{|p{\MakeTableFirstCol}|p{\MakeTableSecondCol}|}

\hline

% ROW 1

{\raggedright \textit{GRAPHICS}} &

{\raggedright Possible values: X, PGM, MATHLINK, NONE. X (default) uses basic

X windows graphics, PGM writes the graphics to a .pgm file, MATHLINK

uses the (external) MathLink library which could be used to send

data directly to Mathematica, NONE switches off all graphics. See also section \ref{sec:display}.

} \\

\hline

% ROW

{\raggedright \textit{STIR\_MPI}} &

{\raggedright Toggles between ON, OFF. Enable parallel processing using MPI.\\

\textit{STIR} contains code for running \texttt{OSMAPOSL} and \texttt{OSSPS} in parallel-mode.

See section \ref{sec:RunningWithMPI} for information on how to run programs using MPI.

\footnote{In fact, any algorithm that uses \texttt{PoissonLogLikelihoodWithLinearModelForMeanAndProjData}.

This functionality was contributed mainly by Tobias Beisel, Univ. of Paderborn). You need a version of the MPI library

to get this to work. We have tested this using \url{http://www.open-mpi.org/}{OpenMPI} 1.4.2 and 1.4.5}.\footnote{

{When using MPI, you can set a compiler define \texttt{STIR\_MPI\_TIMINGS=1}} to

enable additional timings for all send/receive pairs

(see \textbf{distributed\_functions.h} in \textbf{include/stir/recon\_buildblock}.

This should only be used for testing purposes as it can slow down

STIR dramatically.}

} \\

\hline

% ROW

{\raggedright \textit{STIR\_OPENMP}} &

{\raggedright Toggles between ON, OFF. Enable threaded processing using OPENMP.

See section \ref{sec:RunningWithOPENMP} for information on how to run programs using OPENMP.

} \\

\hline

% ROW

{\raggedright \textit{STIR\_LOCAL}} &

{\raggedright Specify location of directory with your own extensions to STIR. See

the developer's guide.}\\

\hline

% ROW

{\raggedright \textit{STIR\_ENABLE\_\\EXPERIMENTAL}} &

{\raggedright Toggles between ON, OFF. Enable to use experimental features in \textit{STIR}.}\\

\hline

% ROW

{\raggedright \textit{STIR\_CONFIG\_DIR}} &

{\raggedright Contains the location of the \textit{STIR} configuration folder, which defaults to a sub-directory of \texttt{CMAKE\_INSTALL\_PREFIX}. See section \ref{sec:configuration} for more info

rmation.}\\

\hline

% ROW

{\raggedright \textit{STIR\_LEGACY\_\\IGNORE\_VIEW\_\\OFFSET}} &

{\raggedright Default to OFF. Introduced in v5.0.0 for backwards compatibility (will be removed in a future version).

When setting to ON, STIR will ignore the \texttt{view offset (degrees)} keyword in Interfile headers and similar information in other places.}\\

\hline

% ROW

{\raggedright \textit{STIR\_ROOT\_\\ROTATION\_AS\_V4}} &

{\raggedright Default to OFF. Introduced in v5.0.1 for backwards compatibility (will be removed in a future version).

When setting to ON, STIR re-enables ad-hoc additions to the correspondence between GATE and STIR crystal indices ``along'' the ring.

See section \ref{sec:ROOTIO} for more info.}\\

\hline

\end{longtable}

You can also (optionally) specify locations of some external libraries for additional IO

capabilities of STIR.

\begin{itemize}

\item LLN files for ECAT support via \texttt{LLN\_INCLUDE\_DIRS} and \texttt{LLN\_LIBRARIES}.

See section \ref{sec:ECAT67support}.

\item ITK\_DIR, use IO from ITK, see section \ref{sec:installITK}.

\item CERN ROOT files used by GEANT and GATE via \texttt{ROOT\_DIR}.

If this is not set, we will try to get it from the \texttt{ROOTSYS} environment (or CMake) variable.

See \ref{sec:installROOT}.

\item GE RDF\texttrademark{} 9 support via \texttt{HDF5\_ROOT} and related variables (requires the HDF5 library).

\end{itemize}

Note that you can use e.g. \textit{DISABLE\_LLN\_MATRIX} to \textit{not}

use the LLN ECAT library, even if cmake found it.

Here are some standard CMake variables that might be useful.

\begin{itemize}

\item set \textit{CMAKE\_BUILD\_TYPE} to \texttt{Release} (default), \texttt{Debug} or \texttt{RelWithDebug}.

(This is ignored when using Visual Studio or XCode).

\item \textit{CMAKE\_INSTALL\_PREFIX} specifies where the final installation has to occur. CMake

provides normally a default in a system location, but you could set it for instance to

\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{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,

it is often necessary to specify the correct Python executable that you want, together with

the libraries. You can use the \texttt{Python\_EXECUTABLE} variable for this. If you

specify the full path to the actual executable, this should be sufficient.

\footnote{If you are using CMake 3.13 or older, use \texttt{PYTHON\_EXECUTABLE}.

In this case, you might have to set \texttt{PYTHON\_LIBRARY} as well.}

There are various other variables that can be set, some of which are only visible if you toggled

the display of \texttt{Advanced} variables on. They should only be set by advanced users, or if a package

cannot be found. For example, if CMake cannot find \textit{boost}, you will have to set \texttt{BOOST\_ROOT}.

\subsubsection{

Operating system specifics}

{ \subsubsubsection{Mac OS}

}

The lln library does not compile on Mac OS.

{ \subsubsubsection{All Unix/Linux flavours}

}

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. However, these will be removed soon.

{ \subsubsubsubsection{X development libraries}

}

If you experience compilation

or linking problems mentioning X11, you have to check if the

X development libraries are installed on your system. You can

check this by doing

\cmdline{find /usr -name Xlib.h -print}

If this file is not found, you'll have to install these libraries

somehow.

{ \subsubsubsubsection{X display depth}

}

\textit{STIR} version 1.0 required that your Xserver worked in 8bit

mode (or Pseudocolor mode in X terminology). This is no longer

necessary. However, if you are experiencing problems with the

display, you could try 8bit mode anyway.

{ \subsubsubsection{Cygwin on Windows}

}

\textit{Cygwin support has not been tested since about 2018 but likely still works. Instructions below are likely out-of-date though.

We highly recommend to use WSL instead.}

If you are using Windows but would like

to have nearly everything that Linux/Unix has to offer, Cygwin could help. Check out http://cygwin.com.

{ \subsubsubsubsection{Using X windows on cygwin}

}

\begin{itemize}

\item Install the Xorg-x11 packages using the cygwin setup utility

(you need the devel package).

\item

install ncurses-devel if you don't have it yet (use the cygwin

Net setup).

\item make sure that /usr/X11R6/bin is in your PATH (necessary

for DLLs)

\end{itemize}

You can start the Xorg X server by executing the startxwin.sh

script (you might want to modify this a bit to suit your taste).

Other decent X servers should work as well (Kris Thielemans used Exceed at

some point).

\subsection{

Running tests}

We \textbf{highly recommend} running test programs after building. There are currently two

sets of tests. The first set tests various components of

\textit{STIR}. This process is described on the Wiki, but briefly can

be run using \texttt{make BUILD\_TESTS \&\& make test}.

The second set of tests is available via the \textit{STIR} web-site, where we

we provide test reconstructions as part of the

\textbf{recon\_test\_pack}, with an

automated procedure to see if you can reproduce the correct results.

You really should download this and run it.

Note that if you are using a non-standard scanner,

you might want to run one reconstruction on your data with

the debug version of the reconstruction program, to see if everything

works as intended. You'll probably want to choose a small value

for the `maximum absolute segment number to process' parameter

in your reconstruction (see Section \ref{sec:OSMAPOSL}), as this will be \textbf{\textit{very}}

slow.

\section{Configuration after installation

\label{sec:configuration}

}

Since \textit{STIR} version 5.0, STIR reads some configuration files, currently JSON files used for

the estimation of attenuation factors from a CT image and a database with isotope information.

The location of these files is found as follows

\begin{itemize}

\item Environment variable: if the \texttt{STIR\_CONFIG\_DIR} environment variable exists, it is used.

\item CMake variable: when running \textit{CMake}, you can specify the default location via the

\texttt{STIR\_CONFIG\_DIR} CMake variable. By default, this is set to a sub-directory \texttt{share/stir/config}

in your install folder.

\end{itemize}

If you want to use a non-default location, it is highly recommended to set the variable to an absolute path.

The installation process will copy the default configuration files to the path specified by the

(CMake) \texttt{STIR\_CONFIG\_DIR} variable.

This currently contains

\begin{itemize}

\item \texttt{ct\_slopes.json} which is used for the estimation of attenuation factors from a CT image,

\item \texttt{radionuclide\_info.json} contains information on radio-isotopes, such as decay rates etc.

\item \texttt{radionuclide\_names.json} contains a look-up table for radio-isotope names to convert them

to the standard (as used by DICOM).

\end{itemize}

You might need to edit these files to add information for your scanner.

See section \ref{sec:stirconfig} for a utility to display the directory where the configuration files are found.

See section \ref{sec:RunningWithOPENMP} for information on OpenMP and mult-threading (if enabled when building \textit{STIR}).

\section{

Running \textit{STIR} programs}

Here we describe:

\begin{itemize}

\item documentation and program conventions (section \ref{sec:conventions})

\item supported file formats (section \ref{sec:fileformats})

\item list mode processing (section \ref{sec:listmodeprocessing})

\item rebinning algorithms (section \ref{sec:Rebinning})

\item reconstruction programs (section \ref{sec:imagereconstructionprograms})

\item scatter estimation and simulation (section \ref{sec:scatterestimation})

\item parametric image construction using kinetic modelling (section \ref{sec:KineticModels})

\item motion correction (section \ref{sec:motioncorrection})

\item utility programs (section \ref{sec:Utilities})

\item user-selectable components such as projectors, filters etc (section \ref{sec:user-selectablecomponents})

\item display properties (section \ref{sec:display})

\end{itemize}

\textit{STIR} is highly configurable and modular. It is therefore difficult to give a complete (and readable)

description of all the options in this guide. Moreover, many options are common to many

programs. For instance, a forward projector will be needed in many places, and there are

different forward projectors implemented in \textit{STIR}, each with their own set of

parameters. Your best bet might be to start with some of the sample parameter files, and then

come back to this guide. In particular, section \ref{sec:user-selectablecomponents}

on user-selectable components gives more detail on what options are available

and what their parameters are.

\subsection{

Conventions}

\label{sec:conventions}

When discussing command line parameters of the \textit{STIR} executables,

the following format is used in this documentation (and the usage messages):

\cmdline{executable\_name parameter1 parameter2 {\textbackslash}\\

{[}optional\_parameter3 [optional\_parameter4 etc]]}

This means that the first 2 parameters are mandatory, but a 3$^{rd}$

parameter can be given, or 4 parameters. A single parameter is

usually given as one word, but sometimes as a string between

\texttt{<} \texttt{>}.

All parameters have to be on a single command line. This is indicated

by the backslash {\textbackslash}, as in Unix this is the standard way

of continuing a command line on the next line.

All executables are supposed to be located in the path of the

command shell used.

Most \textit{STIR} programs accept a single parameter on the command

line, which is sometimes optional

\cmdline{executable\_name [parameter\_filename]}

The parameter file is a text file which uses an Interfile-like

syntax. It is composed of keywords, corresponding to the names

of the various parameters, with the values entered next to them.

Spaces and tabs are normally irrelevant. Parameters omitted from

the parameter file are assigned a default value.

Comments are indicated via a semi-colon (;) at the start of the line. Do

not put a comment before the first keyword in the file.

If a parameter file is not passed to the executable, some

programs will prompt the user

for the required information. For questions that

ask for a number, the format is as follows:

\tab What number do you want to enter today \\

\tab [minimum, maximum, D: default]:

If a simple Carriage Return is entered, the default value is

selected.

Sample parameter files for particular programs (or part of a

parameter file relevant to a particular common component) are

presented in subsequent sections. See also the files in \texttt{STIR/examples/samples/}.

\subsection{

Error handling etc}

\textit{STIR} executables tend to write a lot of information to the terminal on what is happening.

Check for lines starting with \texttt{WARNING} and \texttt{ERROR}.

After an error, the executable will stop\footnote{On some systems there is at the end

a somewhat confusing error about

exceptions thrown, but ignore that and check the ERROR line.}.Information on some of the common

causes for errors is on the Wiki.

All \textit{STIR} executables return a status value to signify success

or failure. What value this is depends on your Operating System.

On Unix, Linux and Windows variations, success is indicated by

a status of 0, and failure by anything else. There is currently

no differentiation between the reasons for failure.

\subsection{

Running programs using MPI \label{sec:RunningWithMPI}}

If you have compiled with STIR\_MPI, you need run the executables in such a way that

they know about the availables nodes. How to do this is system/MPI version specific. The following

should work with OpenMPI on Linux:

\cmdline{mpirun -np 12 --hostfile ~/myconf.txt OSMAPOSL mypars.par}

\noindent

where the host file describes your set-up, e.g. if you have 3 nodes with differing number of cores, the

host file could look like this:

\begin{verbatim}

# The Hostfile for Open MPI

beo-09 slots=4

beo-10 slots=8

beo-11 slots=8

\end{verbatim}

Without host file, the executables will normally be run on the host where you executed the command, which

is useful for multi-processor/core machines.

\textit{MPICH} would use a similar line using \texttt{mpiexec}.

If you have a queueing system that supports MPI such as

\url{http://www.clusterresources.com/products/torque-resource-manager.php}{Torque}, it is better to use

that system for sorting out available resources etc. For example, to use 2 nodes with 4 processes each,

the following should work

\cmdline{qsub -I -l nodes=2:ppn=4}

This will open a interactive prompt on one node where you just type

\cmdline{mpirun OSMAPOSL mypars.par}

Of course, you can use \texttt{qsub} to submit a job as opposed to getting an interactive prompt.

\subsection{

Running programs using OPENMP \label{sec:RunningWithOPENMP}}

If you have compiled with OPENMP support, the executables should run as normal.

The environment variable \texttt{OMP\_NUM\_THREADS} can be set to the number of processes to be used for OpenMP.

Without using this, the number of threads is defined as the number of cores on your system. It is probably

useful to reduce the number of threads as currently performance is limited by the available cache in your

processor.

\subsection{

File formats}

\label{sec:fileformats}

The STIR utility and reconstruction programs frequently need

to read and write files of image and projection data. Files formats

are encountered in which data and header information are maintained

in separate files (e.g. interfile). In other formats, data files

carry header information (e.g. the native GE Advance sinogram

format).

When reading a file, \textit{STIR} will automatically discover its file format

(independent of its name). See section \ref{sec:outputfileformats} for supported output file formats. In addition,

utilities are available for converting ECAT6 and ECAT7 to/from

interfile (see Section \ref{sec:convertingdata}).

\subsubsection{Interfile}

The most comprehensively supported file format in the library

is a newly proposed version of interfile. More details about

this type can be found in the ''Other info'' section of the \textit{STIR} website.

\begin{itemize}

\item For PET projection data, we use the proposed Interfile version. You can

find sample Interfile headers in the \textbf{recon\_test\_pack} or by using

\texttt{create\_projdata\_template}.

\item For SPECT projection data, we use Interfile version 3.3 (with a few small changes).

You can find a sample SPECT Interfile header in the \texttt{samples} directory.

\item For images, we use the proposed Interfile version. Currently, images have to

be written as PET data, even for SPECT.

\end{itemize}

Interfile is currently the only format supported for writing projection

data (except by the \textit{conv\_to\_ecat?} utilities\textit{)}. Projection

data files are written in pairs:\\

\textit{projdata\_filename.hs,

projdata\_filename.s}\\

where \textit{projdata\_filename.hs} is the header text file and \textit{projdata\_filename.s}

is the data file. Please read section \ref{sec:outputinterfile} for info regarding

images written by \textit{STIR} in Interfile.

\subsubsection{Siemens interfile-like}

Siemens PET/CT and PET/MR scanners use a file format that is based on the mentioned

proposed Interfile standard but with some variations. We read this since STIR 4.0,

but do not write it.

\subsubsection{RDF9 data}

See section \ref{sec:RDFsupport} for enabling support for data from GE scanners

that use the GE RDF format. We currently support uncompressed listmode,

uncompressed sinograms and normalisation files. (well-counter files are not

yet supported). Please check \texttt{examples/GE-Signa-PETMR} for some

information.

\subsubsection{ECAT6 and ECAT7 data}

See section \ref{sec:ECAT67support} for enabling support for ECAT data.

ECAT6 data are no longer supported.

ECAT7 sinograms, attenuation files and images can be read without

conversion. However, only the first frame (ECAT matrix 1,1,1,0,0)

will be read for static reconstruction.

\textbf{Warning} The calibration factor field in the main header of ECAT7 images

is currently ignored.

For dynamic or gated data, conversion can be used, see \ref{sec:convertingdata}.

\textbf{Warning} ECAT7 support is no longer tested.

\subsubsection{Image IO using the ITK library \label{sec:ITKIO}}

If you compiled \textit{STIR} such that it could find the \textit{ITK} library, you will be read

all image formats supported by \textit{ITK}, see \url{http://www.itk.org/Wiki/ITK/File_Formats}{the ITK Wiki}

for some information. However, many file formats do not specify geometric information (e.g jpg). For those

that do, \textit{STIR} currently timing. Except for DICOM, \textbf{orientation and offset code

assumes the patient is in HFS position}. Only if DICOM is used and the correct DICOM codes are set

(0018, 5100) will the orientation be correct.

Note that as DICOM files often store only a single slice, \textit{STIR} attempts to find

other slices belonging to the same series. When there are multiple time frames/gates in a folder,

these may be incorrectly treated as a single volume.

\subsubsection{SimSET files}

There are some preliminary files to make it easier to use SimSET and \textit{STIR} together in the

\textbf{SimSET} directory. See the README.txt in that directory for more info.

\subsubsection{ROOT files as output by OpenGATE \label{sec:ROOTIO}}

We highly recommend

\url{https://github.com/UCL/STIR-GATE-Connection}{STIR-GATE-Connection} to be sure that GATE input

and STIR images are aligned etc.

We give information on the details here.

You need to create a text file header for your ROOT file

to specify the scanner (as this information is not stored in the ROOT file).

We tend to name this header \texttt{something.hroot} but this is not mandatory.

We currently support only ROOT output using the CylindricalPET and ECAT systems

from GATE.\footnote{There are some unfinished classes

available on the \textit{STIR} web-site to read \textit{LMF} format files,

in conjunction with the \textit{LMF} library. However, these might be out-dated.

.}

\textbf{Warning:} There is a check of consistent scanner geometry information between \textit{STIR} template projection data headers that are used for \texttt{lm\_to\_projdata}

with the information in the \texttt{.hroot} file

as discrepancies can lead to crashes if the actual number of blocks/crystals etc is

larger than what is specified in the scanner info. However, this check still requires the \texttt{.hroot}

file to accurately correspond to your GATE macro (which are not read by STIR).

\textbf{Warning:} Since STIR 5.0, some scanners (currently some Siemens scanners) default to using

``virtual crystals" to accomodate for gaps between blocks. If you use

the \texttt{originating system} to specify the scanner, this will be automatically enabled.

(If you do not want this, set it to \texttt{User\_defined\_scanner} and specify all values).

An OpenGATE scanner geometry is modular. For CylindricalPET, \textit{STIR} uses the conversion

scheme detailed in Table \ref{tab:STIR-OpenGATE_terminology}.

\begin{table}[h]

\centering

\begin{tabular}{ |c | c| }

\hline

\textbf{GATE} & \textbf{STIR} \\

\hline

Crystal & Crystal \\

Submodule & Block \\

Module & Bucket \\

Rsector & Buckets around the ring \\

\hline

\end{tabular}

\caption{A guide on the terminology equivalents between STIR and OpenGATE for CylindricalPET

scanner geometries.}

\label{tab:STIR-OpenGATE_terminology}

\end{table}

A full example is given in \texttt{STIR/examples/samples/root\_header.hroot}. Below are

2 shorter examples.

If the scanner is known to \texttt{stir::Scanner}, you can use this

\begin{verbatim}

ROOT header :=

Originating system := Siemens mMR

; specify GATE output format (could be GATE_ECAT_PET as well)

GATE scanner type := GATE_Cylindrical_PET

GATE_Cylindrical_PET Parameters :=

; name of the actual ROOT file

name of data file := mysim.root

; See elsewhere for other parameters

End GATE_Cylindrical_PET Parameters :=

end ROOT header :=

\end{verbatim}

This is of course very brief, but it is hard to know if the STIR defined scanner is

compatibile with your GATE macros. Below is an example using a user-defined scanner.

\begin{verbatim}

ROOT header :=

Originating system := User_defined_scanner

Number of rings := 4

Number of detectors per ring := 504

Inner ring diameter (cm) := 65.6

Average depth of interaction (cm) := 0.7

Distance between rings (cm) := 0.40625

Default bin size (cm) := 0.208626

Maximum number of non-arc-corrected bins := 344

Default number of arc-corrected bins := 344 ; default is same as previous value

View offset (degrees) := 0 ; default, but see info below

GATE scanner type := GATE_Cylindrical_PET

GATE_Cylindrical_PET Parameters :=

; name of the actual ROOT file

name of data file := mysim.root

; root tree chain to use

name of input TChain := Coincidences

; Gate scanner geometry terminology used to check scanner properties

number of Rsectors := 504

number of modules_X := 1

number of modules_Y := 1

number of modules_Z := 1

number of submodules_X := 1

number of submodules_Y := 1

number of submodules_Z := 1

number of crystals_X := 1

number of crystals_Y := 1

number of crystals_Z := 4

Singles readout depth := 1

; exclude different event types

exclude non-random events := 0

exclude unscattered events := 0

exclude scattered events := 0

exclude random events := 0

low energy window (keV) := 0 ; Default 0

upper energy window (keV):= 10000 ; Default 10000

End GATE_Cylindrical_PET Parameters :=

end ROOT header :=

\end{verbatim}

See \texttt{STIR/examples/samples/root\_headerECAT.hroot} for an example using the ECAT system.

OpenGATE energy information is recorded in MeV units into the ROOT file.

For STIR files, e.g. \texttt{.hroot} and \texttt{.hs}, should use keV units.

STIR assumes this convention and will convert this automatically.

\subsubsubsection{STIR GATE geometry alignment}

\noindent \underline{Rotation}

When \texttt{View offset} is 0, STIR's first crystal/detector index is at $y=-R$, while GATE (by default)

places the centre of the first module at $x=+R$.

This results in a rotation of about 90 degrees in the reconstructed images unless accounted for.

Two possible correction methods exist:

\begin{enumerate}

\item Rotate the GATE scanner geometry using \texttt{/gate/cylindricalPET/placement/setRotationAngle}.

\item Use the \texttt{View offset (degrees)} parameter in the scanner definition of the \texttt{.hroot} header file.

\end{enumerate}

Of course, these 2 methods can be combined. This can be necessary if you want to reproduce the

gemoetry of an existing scanner. For instance, most GE scanners have the first ``bucket''

horizontally on ``top'' of the scanner.

See an example to accomodate this by using a rotation by -90 degrees in the GATE macro

\url{https://github.com/UCL/STIR/blob/master/examples/ROOT_files/ROOT_STIR_consistency/Gate_macros/geometry.mac}{ROOT\_STIR\_consistency/Gate\_macros/geometry.mac}

and a small rotation for the ``bucket'' in

\url{https://github.com/UCL/STIR/blob/master/examples/ROOT_files/ROOT_STIR_consistency/root_header_test_template.hroot}{ROOT\_STIR\_consistency/root\_header\_test\_template.hroot}.

Note, pre-STIR version 5.0.1, a number of rotations were used in STIR to rotate the scanner and align GATE simulation

with STIR. However, these were removed because with the addition of \texttt{View offset (degrees)} into scanner definitions.

More information can be found in the

\url{http://stir.sourceforge.net/documentation/release_5.0.htm}{documentation/release\_5.0.htm notes}.

\noindent \underline{Translation}

At present, STIR image coordinates are such that the origin is in the centre of the first plane,

normally corresponding to the centre of the first detector ring. GATE macros usually

define the origin in the centre of the scanner. Therefore, when comparing shapes generated

with STIR (e.g. via \texttt{generate\_image}), and geometric shapes from GATE, you need to use

the following

\begin{equation}

z_\textrm{STIR} = (N-1) d/2 + z_\textrm{GATE}

\end{equation}

\noindent

with $d$ the ring spacing (as given in the STIR files) and $N$ the number of rings.

\subsubsubsection{ROOT exclusion keys configurations}

The \textit{exclude xxx events := 1} keys can be used to process specific types of events.

Below are sets event types that will be processed with an exclusion or combination of exclusions.

The exclusions of an event type is false by default.

\begin{table}[h]

\centering

\begin{tabular}{ | c | c | }

\hline

\textbf{Event(s) type} & \textbf{Exclusion Configuration}

\\ \hline \hline

All events & \textit{None}

\\ \hline \hline

\vtop{\hbox{\strut Scattered from same eventID }

\hbox{\strut Unscattered from same eventID}}

& \textit{exclude random events := 1}

\\ \hline

\vtop{\hbox{\strut Unscattered from same eventID }

\hbox{\strut Unscattered from different eventIDs}}

& \textit{exclude scattered events := 1}

\\ \hline

\vtop{\hbox{\strut Scattered from different eventIDs }

\hbox{\strut Unscattered from different eventIDs}}

& \textit{exclude non-random events := 1}

\\ \hline

\vtop{\hbox{\strut Scattered from same eventID}

\hbox{\strut Scattered from different eventIDs}}

& \textit{exclude unscattered events := 1}

\\ \hline \hline

Unscattered from same eventID & \vtop{\hbox{\strut \textit{exclude random events := 1} }\hbox{\strut \textit{exclude scattered events := 1}}}

\\ \hline

Unscattered from different eventIDs & \vtop{\hbox{\strut \textit{exclude non-random events := 1} }\hbox{\strut \textit{exclude scattered events := 1}}}

\\ \hline

Scattered from same eventID & \vtop{\hbox{\strut \textit{exclude random events := 1} }\hbox{\strut \textit{exclude unscattered events := 1}}}

\\ \hline

Scattered from different eventIDs & \vtop{\hbox{\strut \textit{exclude non-random events := 1} }\hbox{\strut \textit{exclude unscattered events := 1}}}

\\ \hline

\end{tabular}

\caption{A guide on how to process specific types of events from a ROOT file using various exclusion keys and combinations of keys.}

\label{tab:ROOT_file_exclusions}

\end{table}

\subsubsection{Multi header format}

\label{multi-file-format}

It is often useful to be able to constract a single dataset from multiply components (e.g. images

or projection data). We have a (STIR-specific) header format for this which is very simple, for example

\begin{verbatim}

Multi :=

total number of data sets := 2

data set[1] := sinogram_1.hs

data set[2] := sinogram_2.hs

end :=

\end{verbatim}

Each ``component'' will be read independently, so could in principle be in a different file format

from the others.

We currently support this format for dynamic images and projection data.

\subsubsection{SPECT DICOM projection data}

SPECT raw projection data in DICOM format is currently only supported by running the \texttt{SPECT\_dicom\_to\_interfile} utility,

see \ref{utility:SPECT_dicom_to_interfile}.

\subsection{

List mode processing}

\label{sec:listmodeprocessing}

Some scanners produce list mode data, which is essentially a

list of events. \textit{STIR} provides utilities to use

the list mode files, for example to convert them to sinograms. It is

also possible to reconstruct images directly from list mode data.

Currently supported list mode formats are specific to the ECAT

HR+, ECAT EXACT 3D and Siemens mMR scanners. We also support \textit{CERN ROOT} files

as output by OpenGATE (see section \ref{sec:ROOTIO}).

\subsubsection{

lm\_to\_projdata}

This utility can be used to bin (or ``sort'') the list mode data

into 'projection data' (also known as \textbf{3D sinograms}.

This can then be processed further by other \textit{STIR} utilities. It

needs to be run as follows:

\cmdline{lm\_to\_projdata par\_filename}

See \textbf{STIR/examples/samples/lm\_to\_projdata.par} for an example file. Please

check out the online documentation (as generated by doxygen)