CASToR  1.1
Tomographic Reconstruction (PET/SPECT)
 All Classes Files Functions Variables Typedefs Macros Groups Pages
iOptimizerTemplate.cc
Go to the documentation of this file.
1 
2 /*
3  Implementation of the class iOptimizerMLEM
4 
5  - separators: X
6  - doxygen: X
7  - default initialization: X
8  - CASTOR_DEBUG:
9  - CASTOR_VERBOSE:
10 */
11 
18 #include "iOptimizerTemplate.hh"
19 #include "sOutputManager.hh"
20 
21 // =====================================================================
22 // ---------------------------------------------------------------------
23 // ---------------------------------------------------------------------
24 // =====================================================================
25 
27 {
28  // ---------------------------
29  // Mandatory member parameters
30  // (inherited from vOptimizer)
31  // ---------------------------
32 
33  // Initial value of the image voxels before iterating
34  m_initialValue = 1.;
35  // The number of backward images used by the optimizer (most of the time it is 1, but it can be more for special cases)
37  // Specify here is the optimizer is compatible with list-mode and/or histogram data
40 
41  // --------------------------
42  // Specific member parameters
43  // --------------------------
44 
45  // Set here the default values of the parameters specific to this optimizer
46 
47 }
48 
49 // =====================================================================
50 // ---------------------------------------------------------------------
51 // ---------------------------------------------------------------------
52 // =====================================================================
53 
55 {
56  // Delete or free ONLY things that were built into this class
57 }
58 
59 // =====================================================================
60 // ---------------------------------------------------------------------
61 // ---------------------------------------------------------------------
62 // =====================================================================
63 
65 {
66  cout << "This optimizer is only a squeleton template to explain how to add an optimizer into CASToR." << endl;
67  cout << "If you want to implement your own optimizer, start from here." << endl;
68  cout << "The following options can be used (in this particular order when provided as a list):" << endl;
69  cout << " my parameter: blablabla" << endl;
70 }
71 
72 // =====================================================================
73 // ---------------------------------------------------------------------
74 // ---------------------------------------------------------------------
75 // =====================================================================
76 
77 int iOptimizerTemplate::ReadConfigurationFile(const string& a_configurationFile)
78 {
79  // This function is designed to read parameters specific to the optimizer through a configuration file.
80  // To do that, use the ReadDataASCIIFile() function, and take a look at other optimizers to see how it is done.
81  // Do not check the parameters' values, the CheckSpecificParameters() function is designed to do that.
82  // Return 1 if any problem.
83 
84  // Normal end
85  return 0;
86 }
87 
88 // =====================================================================
89 // ---------------------------------------------------------------------
90 // ---------------------------------------------------------------------
91 // =====================================================================
92 
93 int iOptimizerTemplate::ReadOptionsList(const string& a_optionsList)
94 {
95  // This function is designed to read parameters specific to the optimizer through a list of options in a string.
96  // To do that, use the ReadStringOption() function, and take a look at other optimizers to see how it is done.
97  // Do not check the parameters' values, the CheckSpecificParameters() function is designed to do that.
98  // Return 1 if any problem.
99 
100  // Normal end
101  return 0;
102 }
103 
104 // =====================================================================
105 // ---------------------------------------------------------------------
106 // ---------------------------------------------------------------------
107 // =====================================================================
108 
110 {
111  // This function is designed to check that all parameters specific to the optimizer have been set properly.
112  // Return 1 if any problem.
113 
114  // Normal end
115  return 0;
116 }
117 
118 // =====================================================================
119 // ---------------------------------------------------------------------
120 // ---------------------------------------------------------------------
121 // =====================================================================
122 
124 {
125  // Verbose
126  if (m_verbose>=2) Cout("iOptimizerTemplate::Initialize() -> Use the template optimizer" << endl);
127 
128  // This function is designed to initialize everything that should be initialized before being able to launch the iteration.
129  // Return 1 if any problem.
130 
131  // Normal end
132  return 0;
133 }
134 
135 // =====================================================================
136 // ---------------------------------------------------------------------
137 // ---------------------------------------------------------------------
138 // =====================================================================
139 
140 int iOptimizerTemplate::SensitivitySpecificOperations( FLTNB a_data, FLTNB a_forwardModel, FLTNB* ap_weight,
141  FLTNB a_multiplicativeCorrections, FLTNB a_additiveCorrections,
142  FLTNB a_quantificationFactor, oProjectionLine* ap_Line )
143 {
144  // The purpose of this function is to assign the weight of the event. In most cases, it is simply 1 (note that all multiplicative
145  // terms belonging to the system matrix are automatically taken into account during the back-projection, explaining why the weight
146  // is simply 1 in most cases). The weight should be put into *ap_weight.
147  // About the parameters:
148  // a_data: is the data of the event (in number of counts; 1 if list-mode data, and any value for histogram data)
149  // a_forwardModel: is the forward model (also in number of counts); this the forward projection of the image including all system matrix
150  // related multiplicative terms as well as the additive terms; so it is directly comparable to the data
151  // ap_weight: is where the result should be put in
152  // a_multiplicativeCorrections: is the multiplicative corrections specific to the event; in other words, it does not contain the
153  // multiplicative factors global to the image, which are given in a separate parameter as a_quantificationFactor
154  // a_additiveCorrections: is the additive terms (in number of counts); e.g. scatters and randoms for PET
155  // a_quantificationFactor: is the quantification factor associated to the image where the event belongs to
156  // ap_Line: is the projection line associated to the event; in case a forward projection should be perform, it must be passed to the
157  // ForwardProject() function as an argument
158  // Finally, note that this function is only called for histogram data. For list-mode data, the sensitivity is computed before launching the
159  // the iterations, assuming weights of 1. So if the weights here for the specific optimizer are different than 1, then the optimizer cannot
160  // handle list-mode data, so remember to set the m_listmodeCompatibility flag to false in the constructor, in such a case.
161 
162  *ap_weight = 1.;
163 
164  // That's all
165  return 0;
166 }
167 
168 // =====================================================================
169 // ---------------------------------------------------------------------
170 // ---------------------------------------------------------------------
171 // =====================================================================
172 
173 int iOptimizerTemplate::DataSpaceSpecificOperations( FLTNB a_data, FLTNB a_forwardModel, FLTNB* ap_backwardValues,
174  FLTNB a_multiplicativeCorrections, FLTNB a_additiveCorrections,
175  FLTNB a_quantificationFactor, oProjectionLine* ap_Line )
176 {
177  // The purpose of this function is to perform the data space operations specific to the optimizer (this function is called for each event)
178  // in order to compute the correction terms that need to be back-projected. This value should be put into *ap_backwardValues. In case the
179  // optimization requires multiple backward images, one must simply set the number of backward images into the constructor as m_nbBackwardImages.
180  // Then, the multiple values to be back-projected can be put in ap_backwardValues[0], ap_backwardValues[1], etc.
181  // About the parameters:
182  // a_data: is the data of the event (in number of counts; 1 if list-mode data, and any value for histogram data)
183  // a_forwardModel: is the forward model (also in number of counts); this the forward projection of the image including all system matrix
184  // related multiplicative terms as well as the additive terms; so it is directly comparable to the data
185  // ap_backwardValues: is where the result should be put in (multiple values is accepted if m_nbBackwardImages>1)
186  // a_multiplicativeCorrections: is the multiplicative corrections specific to the event; in other words, it does not contain the
187  // multiplicative factors global to the image, which are given in a separate parameter as a_quantificationFactor
188  // a_additiveCorrections: is the additive terms (in number of counts); e.g. scatters and randoms for PET
189  // a_quantificationFactor: is the quantification factor associated to the image where the event belongs to
190  // ap_Line: is the projection line associated to the event; in case a forward projection should be perform, it must be passed to the
191  // ForwardProject() function as an argument
192  // Look at the optimizers already implemented in order to get an idea of how to do it.
193 
194  *ap_backwardValues = 1.;
195 
196  // That's all
197  return 0;
198 }
199 
200 // =====================================================================
201 // ---------------------------------------------------------------------
202 // ---------------------------------------------------------------------
203 // =====================================================================
204 
205 int iOptimizerTemplate::ImageSpaceSpecificOperations( FLTNB a_currentImageValue, FLTNB* ap_newImageValue,
206  FLTNB a_sensitivity, FLTNB* ap_correctionValues )
207 {
208  // The purpose of this function is to perform the image space operations specific to the optimizer (this function is called for each voxel).
209  // In other words, the new voxel value has to be computed based on the previous one, the sensitivity and the correction values which are the
210  // back-projected correction terms computed in the DataSpaceSpecificOperations() function (there can be multiple correction values if
211  // m_nbBackwardImages>1). Note that being here means that the sensitivity value is not 0, so no need to check it.
212 
213  *ap_newImageValue = a_currentImageValue;
214 
215  // End
216  return 0;
217 }
218 
219 // =====================================================================
220 // ---------------------------------------------------------------------
221 // ---------------------------------------------------------------------
222 // =====================================================================
#define FLTNB
Definition: gVariables.hh:55
FLTNB m_initialValue
Definition: vOptimizer.hh:587
bool m_listmodeCompatibility
Definition: vOptimizer.hh:588
~iOptimizerTemplate()
The destructor of iOptimizerTemplate.
Declaration of class iOptimizerTemplate.
int m_nbBackwardImages
Definition: vOptimizer.hh:583
iOptimizerTemplate()
The constructor of iOptimizerTemplate.
int CheckSpecificParameters()
A private function used to check the parameters settings specific to the child optimizer.
bool m_histogramCompatibility
Definition: vOptimizer.hh:589
int ReadOptionsList(const string &a_optionsList)
A function used to read options from a list of options.
int InitializeSpecific()
This function is used to initialize specific stuff to the child optimizer.
int DataSpaceSpecificOperations(FLTNB a_data, FLTNB a_forwardModel, FLTNB *ap_backwardValues, FLTNB a_multiplicativeCorrections, FLTNB a_additiveCorrections, FLTNB a_quantificationFactor, oProjectionLine *ap_Line)
This function performs the data space operations specific to the optimizer (computes the values to be...
This class is designed to generically described any iterative optimizer.
Definition: vOptimizer.hh:36
This class is designed to manage and store system matrix elements associated to a vEvent...
Declaration of class sOutputManager.
#define Cout(MESSAGE)
int ReadConfigurationFile(const string &a_configurationFile)
A function used to read options from a configuration file.
void ShowHelpSpecific()
A function used to show help about the child optimizer.
int SensitivitySpecificOperations(FLTNB a_data, FLTNB a_forwardModel, FLTNB *ap_weight, FLTNB a_multiplicativeCorrections, FLTNB a_additiveCorrections, FLTNB a_quantificationFactor, oProjectionLine *ap_Line)
This function compute the weight associated to the provided event (for sensitivity computation) ...
int ImageSpaceSpecificOperations(FLTNB a_currentImageValue, FLTNB *ap_newImageValue, FLTNB a_sensitivity, FLTNB *ap_correctionValues)
This function perform the image update step specific to the optimizer.