CASToR  2.0
Tomographic Reconstruction (PET/SPECT/CT)
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
vOptimizer.hh
Go to the documentation of this file.
1 /*
2 This file is part of CASToR.
3 
4  CASToR is free software: you can redistribute it and/or modify it under the
5  terms of the GNU General Public License as published by the Free Software
6  Foundation, either version 3 of the License, or (at your option) any later
7  version.
8 
9  CASToR is distributed in the hope that it will be useful, but WITHOUT ANY
10  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
11  FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
12  details.
13 
14  You should have received a copy of the GNU General Public License along with
15  CASToR (in file GNU_GPL.TXT). If not, see <http://www.gnu.org/licenses/>.
16 
17 Copyright 2017-2018 all CASToR contributors listed below:
18 
19  --> current contributors: Thibaut MERLIN, Simon STUTE, Didier BENOIT, Claude COMTAT, Marina FILIPOVIC, Mael MILLARDET
20  --> past contributors: Valentin VIELZEUF
21 
22 This is CASToR version 2.0.
23 */
24 
31 #ifndef VOPTIMIZER_HH
32 #define VOPTIMIZER_HH 1
33 
34 #include "gVariables.hh"
36 #include "oImageSpace.hh"
37 #include "vDataFile.hh"
38 #include "oProjectionLine.hh"
39 
60 {
61  // -------------------------------------------------------------------
62  // Constructor & Destructor
63  public:
70  vOptimizer();
78  virtual ~vOptimizer();
79 
80 
81  // -------------------------------------------------------------------
82  // Public member functions
83  public:
89  void ShowHelp();
98  int CheckParameters();
107  int Initialize();
118  int UpdateVisitedVoxels();
132  int PreDataUpdateStep(int a_iteration, int a_nbIterations, int a_subset, int* ap_nbSubsets);
146  int PostDataUpdateStep(int a_iteration, int a_nbIterations, int a_subset, int* ap_nbSubsets);
147 
148 
149  // -------------------------------------------------------------------
150  // Virtual public member functions that may be overloaded by specific child optimizers
151  public:
171  virtual int DataStep1ForwardProjectModel( oProjectionLine* ap_Line, vEvent* ap_Event,
172  int a_bed, int a_timeFrame, int a_respGate, int a_cardGate,
173  int a_thread );
189  virtual int DataStep2Optional( oProjectionLine* ap_Line, vEvent* ap_Event,
190  int a_bed, int a_timeFrame, int a_respGate, int a_cardGate, int a_iteration,
191  int a_thread );
209  virtual int DataStep3BackwardProjectSensitivity( oProjectionLine* ap_Line, vEvent* ap_Event,
210  int a_bed, int a_timeFrame, int a_respGate, int a_cardGate,
211  int a_thread );
227  virtual int DataStep4Optional( oProjectionLine* ap_Line, vEvent* ap_Event,
228  int a_bed, int a_timeFrame, int a_respGate, int a_cardGate,
229  int a_iteration, int a_thread );
247  virtual int DataStep5ComputeCorrections( oProjectionLine* ap_Line, vEvent* ap_Event,
248  int a_bed, int a_timeFrame, int a_respGate, int a_cardGate,
249  int a_thread );
265  virtual int DataStep6Optional( oProjectionLine* ap_Line, vEvent* ap_Event,
266  int a_bed, int a_timeFrame, int a_respGate, int a_cardGate,
267  int a_iteration, int a_thread );
286  virtual int DataStep7BackwardProjectCorrections( oProjectionLine* ap_Line, vEvent* ap_Event,
287  int a_bed, int a_timeFrame, int a_respGate, int a_cardGate,
288  int a_thread );
303  virtual int DataStep8ComputeFOM( oProjectionLine* ap_Line, vEvent* ap_Event,
304  int a_timeFrame, int a_respGate, int a_cardGate,
305  int a_thread );
316  virtual int ImageUpdateStep( int a_iteration, int a_nbSubsets );
317 
318 
319  // -----------------------------------------------------------------------------------------
320  // Virtual private member functions that may be overloaded by specific child optimizers
321  private:
334  virtual int PreDataUpdateSpecificStep(int a_iteration, int a_nbIterations, int a_subset, int* ap_nbSubsets);
347  virtual int PostDataUpdateSpecificStep(int a_iteration, int a_nbIterations, int a_subset, int* ap_nbSubsets);
348 
349  // -----------------------------------------------------------------------------------------
350  // Pure virtual public member functions that need to be implemented by child optimizers
351  public:
362  virtual int ReadConfigurationFile( const string& a_configurationFile ) = 0;
373  virtual int ReadOptionsList( const string& a_optionsList ) = 0;
374 
375 
376  // -----------------------------------------------------------------------------------------
377  // Pure virtual private member functions that need to be implemented by child optimizers
378  private:
387  virtual void ShowHelpSpecific() = 0;
396  virtual int CheckSpecificParameters() = 0;
406  virtual int InitializeSpecific() = 0;
425  virtual int SensitivitySpecificOperations( FLTNB a_data, FLTNB a_forwardModel, FLTNB* ap_weight,
426  FLTNB a_multiplicativeCorrections, FLTNB a_additiveCorrections, FLTNB a_blankValue,
427  FLTNB a_quantificationFactor, oProjectionLine* ap_Line ) = 0;
447  virtual int DataSpaceSpecificOperations( FLTNB a_data, FLTNB a_forwardModel, FLTNB* ap_backwardValues,
448  FLTNB a_multiplicativeCorrections, FLTNB a_additiveCorrections, FLTNB a_blankValue,
449  FLTNB a_quantificationFactor, oProjectionLine* ap_Line ) = 0;
468  virtual int ImageSpaceSpecificOperations( FLTNB a_currentImageValue, FLTNB* ap_newImageValue,
469  FLTNB a_sensitivity, FLTNB* ap_correctionValues, INTNB a_voxel ) = 0;
470 
471 
472  // -------------------------------------------------------------------
473  // Public Get & Set functions
474  public:
480  inline void SetVerbose(int a_verbose)
481  {m_verbose = a_verbose;}
487  inline void SetImageDimensionsAndQuantification(oImageDimensionsAndQuantification* ap_ImageDimensionsAndQuantification)
488  {mp_ImageDimensionsAndQuantification = ap_ImageDimensionsAndQuantification;}
494  inline void SetImageSpace(oImageSpace* ap_ImageSpace)
495  {mp_ImageSpace = ap_ImageSpace;}
501  inline void SetNbTOFBins(int a_nbTOFBins)
502  {m_nbTOFBins = a_nbTOFBins;}
508  inline void SetDataMode(int a_dataMode)
509  {m_dataMode = a_dataMode;}
515  inline void SetDataType(int a_dataType)
516  {m_dataType = a_dataType;}
522  inline void SetDataSpec(int a_dataSpec)
523  {m_dataSpec = a_dataSpec;}
530  inline void SetAttenuationImage(FLTNB* ap_attenuationImage, int a_thread)
531  {m2p_attenuationImage[a_thread] = ap_attenuationImage;}
537  inline void SetFOMFlag(bool a_optimizerFOMFlag)
538  {m_optimizerFOMFlag = a_optimizerFOMFlag;}
544  inline void SetImageStatFlag(bool a_optimizerImageStatFlag)
545  {m_optimizerImageStatFlag = a_optimizerImageStatFlag;}
551  inline int GetNbBackwardImages()
552  {return m_nbBackwardImages;}
559  {return m_initialValue;}
560  /*
561  inline bool GetAcceptPenalty()
562  {return m_penaltyEnergyFunctionDerivativesOrder>0;}
563  inline int GetPenaltyEnergyFunctionDerivativesOrder()
564  {return m_penaltyEnergyFunctionDerivativesOrder;}
565  */
566 
567 
568  // -------------------------------------------------------------------
569  // Private member functions
570  protected:
586  FLTNB ComputeSensitivity( FLTNB**** a4p_sensitivityImage,
587  int a_timeBasisFunction, int a_respBasisFunction, int a_cardBasisFunction,
588  int a_voxel, int a_nbSubsets );
598  FLTNB ForwardProject( oProjectionLine* ap_Line, FLTNB* ap_image = NULL );
609  void BackwardProject( oProjectionLine* ap_Line, FLTNB* ap_image, FLTNB a_value );
610 
611  // -------------------------------------------------------------------
612  // Data members
613  protected:
614  int m_verbose;
631  // Optimizer figures-of-merit computation
635  uint64_t**** m4p_FOMNbBins;
637  // Image update statistics
646  //int m_penaltyEnergyFunctionDerivativesOrder; /*!< The penalty derivatives order accepted by the specific optimizer (0 if none) */
647 };
648 
649 
650 // ----------------------------------------------------------------------
651 // Part of code that manages the auto declaration of children classes
652 // ----------------------------------------------------------------------
653 
654 // Macro for the function that creates the object
655 #define FUNCTION_OPTIMIZER(CLASS) \
656  static vOptimizer *make_optimizer() { return new CLASS(); };
657 
658 // Macro for the class that links the appropriate function to the map of objects
659 #define CLASS_OPTIMIZER(NAME,CLASS) \
660  class NAME##OptimizerCreator \
661  { \
662  public: \
663  NAME##OptimizerCreator() \
664  { sAddonManager::GetInstance()->mp_listOfOptimizers[#NAME] = CLASS::make_optimizer; } \
665  }; \
666  static NAME##OptimizerCreator OptimizerCreator##NAME;
667 
668 #endif
FLTNB * mp_imageStatMax
Definition: vOptimizer.hh:641
virtual int ImageUpdateStep(int a_iteration, int a_nbSubsets)
A public function used to perform the image update step of the optimizer.
Definition: vOptimizer.cc:825
This header file is mainly used to declare some macro definitions and all includes needed from the st...
Declaration of class oImageDimensionsAndQuantification.
#define FLTNB
Definition: gVariables.hh:81
FLTNB m_initialValue
Definition: vOptimizer.hh:619
bool m_listmodeCompatibility
Definition: vOptimizer.hh:620
virtual int DataStep6Optional(oProjectionLine *ap_Line, vEvent *ap_Event, int a_bed, int a_timeFrame, int a_respGate, int a_cardGate, int a_iteration, int a_thread)
A public function which does nothing but being virtual.
Definition: vOptimizer.cc:701
virtual int PreDataUpdateSpecificStep(int a_iteration, int a_nbIterations, int a_subset, int *ap_nbSubsets)
A private function used to perform any step required by the child optimizer, before the loop on event...
Definition: vOptimizer.cc:431
void SetFOMFlag(bool a_optimizerFOMFlag)
Set the FOM flag specifying if figures-of-merit will be computed or not.
Definition: vOptimizer.hh:537
FLTNB * mp_imageStatMin
Definition: vOptimizer.hh:640
#define HPFLTNB
Definition: gVariables.hh:83
HPFLTNB **** m4p_FOMNbData
Definition: vOptimizer.hh:636
virtual int ReadConfigurationFile(const string &a_configurationFile)=0
A function used to read options from a configuration file.
oImageDimensionsAndQuantification * mp_ImageDimensionsAndQuantification
Definition: vOptimizer.hh:625
virtual int CheckSpecificParameters()=0
A private function used to check the parameters settings specific to the child optimizer.
vOptimizer()
The constructor of vOptimizer.
Definition: vOptimizer.cc:38
void SetImageDimensionsAndQuantification(oImageDimensionsAndQuantification *ap_ImageDimensionsAndQuantification)
Set the pointer to the image dimensions in use.
Definition: vOptimizer.hh:487
FLTNB ForwardProject(oProjectionLine *ap_Line, FLTNB *ap_image=NULL)
A function used to forward project the provided image (or 1 if NULL), based on the provided oProjecti...
Definition: vOptimizer.cc:988
virtual int DataStep4Optional(oProjectionLine *ap_Line, vEvent *ap_Event, int a_bed, int a_timeFrame, int a_respGate, int a_cardGate, int a_iteration, int a_thread)
A public function which does nothing but being virtual.
Definition: vOptimizer.cc:652
uint64_t **** m4p_FOMNbBins
Definition: vOptimizer.hh:635
int PostDataUpdateStep(int a_iteration, int a_nbIterations, int a_subset, int *ap_nbSubsets)
A public function used to do stuff that need to be done at the beginning of a subset (before the data...
Definition: vOptimizer.cc:442
HPFLTNB * mp_correctionStatMean
Definition: vOptimizer.hh:644
virtual int ReadOptionsList(const string &a_optionsList)=0
A function used to read options from a list of options.
FLTNB **** m4p_FOMRMSE
Definition: vOptimizer.hh:634
int m_dataMode
Definition: vOptimizer.hh:627
virtual int DataSpaceSpecificOperations(FLTNB a_data, FLTNB a_forwardModel, FLTNB *ap_backwardValues, FLTNB a_multiplicativeCorrections, FLTNB a_additiveCorrections, FLTNB a_blankValue, FLTNB a_quantificationFactor, oProjectionLine *ap_Line)=0
A private function used to compute the correction term in the data space from the provided data...
int m_dataSpec
Definition: vOptimizer.hh:629
bool m_optimizerFOMFlag
Definition: vOptimizer.hh:632
void SetNbTOFBins(int a_nbTOFBins)
Set the number of TOF bins in use.
Definition: vOptimizer.hh:501
void SetDataType(int a_dataType)
Set the data type in use.
Definition: vOptimizer.hh:515
INTNB * mp_imageStatNbVox
Definition: vOptimizer.hh:639
Declaration of class oProjectionLine.
bool m_emissionCompatibility
Definition: vOptimizer.hh:622
int m_nbBackwardImages
Definition: vOptimizer.hh:615
virtual int DataStep3BackwardProjectSensitivity(oProjectionLine *ap_Line, vEvent *ap_Event, int a_bed, int a_timeFrame, int a_respGate, int a_cardGate, int a_thread)
A public function used to back-project the sensitivity terms for the provided event.
Definition: vOptimizer.cc:612
Declaration of class vDataFile.
virtual int InitializeSpecific()=0
A private function used to initialize everything specific to the child optimizer. ...
void BackwardProject(oProjectionLine *ap_Line, FLTNB *ap_image, FLTNB a_value)
A function used to backward project the provided value into the provided image, based on the provided...
Definition: vOptimizer.cc:1003
virtual int DataStep1ForwardProjectModel(oProjectionLine *ap_Line, vEvent *ap_Event, int a_bed, int a_timeFrame, int a_respGate, int a_cardGate, int a_thread)
A public function used to compute the model: forward projection of the provided event.
Definition: vOptimizer.cc:519
FLTNB ** m2p_attenuationImage
Definition: vOptimizer.hh:630
bool m_histogramCompatibility
Definition: vOptimizer.hh:621
bool m_optimizerImageStatFlag
Definition: vOptimizer.hh:638
virtual int DataStep8ComputeFOM(oProjectionLine *ap_Line, vEvent *ap_Event, int a_timeFrame, int a_respGate, int a_cardGate, int a_thread)
A public function used to update the computation of figures-of-merit in the data space.
Definition: vOptimizer.cc:769
void SetImageStatFlag(bool a_optimizerImageStatFlag)
Set the image stat flag specifying if basic statistics about image udpate will be computed or not...
Definition: vOptimizer.hh:544
FLTNB ComputeSensitivity(FLTNB ****a4p_sensitivityImage, int a_timeBasisFunction, int a_respBasisFunction, int a_cardBasisFunction, int a_voxel, int a_nbSubsets)
A function used to compute the sensitivity of a given voxel and a given set of dynamic basis function...
Definition: vOptimizer.cc:1018
FLTNB GetInitialValue()
Get the initial image value (for initialization)
Definition: vOptimizer.hh:558
HPFLTNB * mp_imageStatVariance
Definition: vOptimizer.hh:643
virtual ~vOptimizer()
The destructor of vOptimizer.
Definition: vOptimizer.cc:77
void SetDataSpec(int a_dataSpec)
Set the data physical specificity in use.
Definition: vOptimizer.hh:522
#define INTNB
Definition: gVariables.hh:92
bool m_transmissionCompatibility
Definition: vOptimizer.hh:623
This class is designed to generically described any iterative optimizer.
Definition: vOptimizer.hh:59
void SetAttenuationImage(FLTNB *ap_attenuationImage, int a_thread)
Set the attenuation image corresponding to the current thread and current event.
Definition: vOptimizer.hh:530
int m_nbTOFBins
Definition: vOptimizer.hh:616
This class is designed to manage and store system matrix elements associated to a vEvent...
Declaration of class oImageSpace.
FLTNB **** m4p_FOMLogLikelihood
Definition: vOptimizer.hh:633
int Initialize()
A public function used to initialize the optimizer.
Definition: vOptimizer.cc:322
This class holds all the matrices in the image domain that can be used in the algorithm: image...
Definition: oImageSpace.hh:61
oImageSpace * mp_ImageSpace
Definition: vOptimizer.hh:626
int m_dataType
Definition: vOptimizer.hh:628
Mother class for the Event objects.
Definition: vEvent.hh:43
virtual int DataStep5ComputeCorrections(oProjectionLine *ap_Line, vEvent *ap_Event, int a_bed, int a_timeFrame, int a_respGate, int a_cardGate, int a_thread)
A public function used to compute the correction terms in the data space, for the provided event...
Definition: vOptimizer.cc:665
int PreDataUpdateStep(int a_iteration, int a_nbIterations, int a_subset, int *ap_nbSubsets)
A public function used to do stuff that need to be done at the beginning of a subset (before the data...
Definition: vOptimizer.cc:400
HPFLTNB * mp_imageStatMean
Definition: vOptimizer.hh:642
This class is designed to manage all dimensions and quantification related stuff. ...
virtual int DataStep2Optional(oProjectionLine *ap_Line, vEvent *ap_Event, int a_bed, int a_timeFrame, int a_respGate, int a_cardGate, int a_iteration, int a_thread)
A public function which does nothing but being virtual.
Definition: vOptimizer.cc:599
int GetNbBackwardImages()
Get the number of backward images used by the specific optimizer.
Definition: vOptimizer.hh:551
int UpdateVisitedVoxels()
A public function used to update the 'visited' voxels after each subset.
Definition: vOptimizer.cc:797
virtual int PostDataUpdateSpecificStep(int a_iteration, int a_nbIterations, int a_subset, int *ap_nbSubsets)
A private function used to perform any step required by the child optimizer, after the loop on event ...
Definition: vOptimizer.cc:506
void SetVerbose(int a_verbose)
Set the verbose level.
Definition: vOptimizer.hh:480
virtual void ShowHelpSpecific()=0
A function used to show help about the child module.
virtual int ImageSpaceSpecificOperations(FLTNB a_currentImageValue, FLTNB *ap_newImageValue, FLTNB a_sensitivity, FLTNB *ap_correctionValues, INTNB a_voxel)=0
A private function used to update the image value from the provided data.
virtual int SensitivitySpecificOperations(FLTNB a_data, FLTNB a_forwardModel, FLTNB *ap_weight, FLTNB a_multiplicativeCorrections, FLTNB a_additiveCorrections, FLTNB a_blankValue, FLTNB a_quantificationFactor, oProjectionLine *ap_Line)=0
A private function used to compute the sensitivity weight associated to the provided data...
virtual int DataStep7BackwardProjectCorrections(oProjectionLine *ap_Line, vEvent *ap_Event, int a_bed, int a_timeFrame, int a_respGate, int a_cardGate, int a_thread)
A public function used to back-project the correction terms into the backward correction image...
Definition: vOptimizer.cc:714
void SetDataMode(int a_dataMode)
Set the data mode in use.
Definition: vOptimizer.hh:508
void ShowHelp()
A function used to show help about the optimizer.
Definition: vOptimizer.cc:206
HPFLTNB * mp_correctionStatVariance
Definition: vOptimizer.hh:645
FLTNB ** m2p_forwardValues
Definition: vOptimizer.hh:617
FLTNB *** m3p_backwardValues
Definition: vOptimizer.hh:618
int CheckParameters()
A public function used to check the parameters settings.
Definition: vOptimizer.cc:227
void SetImageSpace(oImageSpace *ap_ImageSpace)
Set the pointer to the image space in use.
Definition: vOptimizer.hh:494