Line data    Source code

       1             : //# MatrixNACleaner.h: this defines Cleaner a class for doing deconvolution
       2             : //# Copyright (C) 1996,1997,1998,1999,2000,2001,2002,2003
       3             : //# Associated Universities, Inc. Washington DC, USA.
       4             : //#
       5             : //# This library is free software; you can redistribute it and/or modify it
       6             : //# under the terms of the GNU General Public License as published by
       7             : //# the Free Software Foundation; either version 3 of the License, or (at your
       8             : //# option) any later version.
       9             : //#
      10             : //# This library is distributed in the hope that it will be useful, but WITHOUT
      11             : //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
      12             : //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
      13             : //# License for more details.
      14             : //#
      15             : //# You should have received a copy of the GNU Library General Public License
      16             : //# along with this library; if not, write to the Free Software Foundation,
      17             : //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
      18             : //#
      19             : //# Correspondence concerning AIPS++ should be addressed as follows:
      20             : //#        Internet email: aips2-request@nrao.edu.
      21             : //#        Postal address: AIPS++ Project Office
      22             : //#                        National Radio Astronomy Observatory
      23             : //#                        520 Edgemont Road
      24             : //#                        Charlottesville, VA 22903-2475 USA
      25             : //#
      26             : //#
      27             : 
      28             : 
      29             : #ifndef SYNTHESIS_MATRIXNACLEANER_H
      30             : #define SYNTHESIS_MATRIXNACLEANER_H
      31             : 
      32             : //# Includes
      33             : #include <casacore/casa/aips.h>
      34             : #include <casacore/casa/Quanta/Quantum.h>
      35             : #include <casacore/casa/Arrays/IPosition.h>
      36             : #include <casacore/casa/Arrays/Vector.h>
      37             : #include <casacore/casa/Containers/Block.h>
      38             : #include <casacore/casa/Arrays/ArrayFwd.h>
      39             : 
      40             : namespace casa { //# NAMESPACE CASA - BEGIN
      41             : 
      42             : //# Forward Declarations
      43             : 
      44             : // <summary>A simple deconvolver that masks by memory of previous peaks</summary>
      45             : // <synopsis> Evolution of a simple cleaner 
      46             : // 
      47             : // </synopsis>
      48             : 
      49             : // <summary>A class for doing multi-dimensional cleaning</summary>
      50             : 
      51             : // <use visibility=export>
      52             : 
      53             : // <reviewed reviewer="" date="yyyy/mm/dd" tests="Mulouktanee">
      54             : // </reviewed>
      55             : 
      56             : // <prerequisite>
      57             : //  <li> The mathematical concept of deconvolution
      58             : // </prerequisite>
      59             : //
      60             : // <etymology>
      61             : 
      62             : // The MatrixNACleaner Uses the matrix class and cleaner is for deconvolver by CLEAN
      63             : // NA stands for Non Amnesiac...i.e remember where past peaks were to search in these region preferentially ...i.e no need to mask 
      64             : 
      65             : // </etymology>
      66             : //
      67             : // <synopsis>
      68             : // This class will perform various types of Clean deconvolution
      69             : // on Lattices.
      70             : //
      71             : // </synopsis>
      72             : //
      73             : // <example>
      74             : // <srcblock>
      75             : // </srcblock> 
      76             : // </example>
      77             : //
      78             : // <motivation>
      79             : // </motivation>
      80             : //
      81             : // <thrown>
      82             : // <li> casacore::AipsError: if psf has more dimensions than the model. 
      83             : // </thrown>
      84             : //
      85             : // <todo asof="yyyy/mm/dd">
      86             : // </todo>
      87             : 
      88             : class MatrixNACleaner
      89             : {
      90             : public:
      91             : 
      92             :   // Create a cleaner : default constructor
      93             :   MatrixNACleaner();
      94             : 
      95             :   // Create a cleaner for a specific dirty image and PSF
      96             :   MatrixNACleaner(const casacore::Matrix<casacore::Float> & psf, const casacore::Matrix<casacore::Float> & dirty, const casacore::Int memtype=2, const casacore::Float numSigma=5.0);
      97             : 
      98             :   // The copy constructor uses reference semantics
      99             :   MatrixNACleaner(const MatrixNACleaner& other);
     100             : 
     101             :   // The assignment operator also uses reference semantics
     102             :   MatrixNACleaner & operator=(const MatrixNACleaner & other); 
     103             : 
     104             :   // The destructor does nothing special.
     105             :   ~MatrixNACleaner();
     106             :  
     107             :   
     108             :   
     109             :   //Set the dirty image without calculating convolutions..
     110             :   //can be done by calling  makeDirtyScales or setscales if one want to redo the 
     111             :   //psfscales too.
     112             :   void setDirty(const casacore::Matrix<casacore::Float>& dirty);
     113             :   
     114             :   
     115             : 
     116             :   //change the psf
     117             :   //don't forget to redo the setscales or run makePsfScales, 
     118             :   //followed by makeDirtyScales 
     119             :   void setPsf(const casacore::Matrix<casacore::Float>& psf);
     120             :  
     121             :  
     122             :  
     123             :   // niter - number of iterations
     124             :   // gain - loop gain used in cleaning (a fraction of the maximum 
     125             :   //        subtracted at every iteration)
     126             :   // aThreshold - absolute threshold to stop iterations
     127             :  
     128             :   void setcontrol(const casacore::Int niter,
     129             :                   const casacore::Float gain, const casacore::Quantity& aThresho, const casacore::Int masksupport=3 , const casacore::Int memType=2, const casacore::Float numsigma=5.0);
     130             : 
     131             :  
     132             : 
     133             :   // return how many iterations we did do
     134           0 :   casacore::Int iteration() const { return itsIteration; }
     135             :  
     136             : 
     137             :  
     138             :  //Total flux accumulated so far
     139             :   casacore::Float totalFlux() const {return itsTotalFlux;}
     140             : 
     141             : 
     142             :   // Clean an image.
     143             :  
     144             :   casacore::Int clean(casacore::Matrix<casacore::Float> & model);
     145             : 
     146             :   // Set the mask
     147             :   // mask - input mask lattice
     148             :   
     149             :   void setMask(casacore::Matrix<casacore::Float> & mask);
     150             :  
     151             : 
     152             :   void setPixFlag(const casacore::Matrix<casacore::Bool>& bitpix);
     153             : 
     154             :   // remove the mask;
     155             :   // useful when keeping object and sending a new dirty image to clean 
     156             :   // one can set another mask then 
     157             :   void unsetMask();
     158             : 
     159             :   void getMask(casacore::Matrix<casacore::Float>& mask);
     160             : 
     161             :   
     162             : 
     163             :   // Look at what WE think the residuals look like
     164             :   casacore::Matrix<casacore::Float>  getResidual() { return *itsResidual; }
     165             : 
     166             :   // Method to return threshold
     167             :   casacore::Float threshold() const;
     168             : 
     169             :   
     170           0 :   casacore::Float maxResidual() {return itsMaximumResidual;};
     171             :   // Helper function to optimize adding
     172             :   //static void addTo(casacore::Matrix<casacore::Float>& to, const casacore::Matrix<casacore::Float> & add);
     173             : 
     174             : protected:
     175             :   // Make sure that the peak of the Psf is within the image
     176             :   casacore::Bool validatePsf(const casacore::Matrix<casacore::Float> & psf);
     177             : 
     178             :  
     179             :   // Find the Peak of the lattice, applying a mask
     180             :   casacore::Bool findMaxAbsMask(const casacore::Matrix<casacore::Float>& lattice,  casacore::Matrix<casacore::Float>& mask,
     181             :                       casacore::Float& maxAbs, casacore::IPosition& posMax, const casacore::Int support=5);
     182             : 
     183             :   // Helper function to reduce the box sizes until the have the same   
     184             :   // size keeping the centers intact  
     185             :   static void makeBoxesSameSize(casacore::IPosition& blc1, casacore::IPosition& trc1,                               
     186             :      casacore::IPosition &blc2, casacore::IPosition& trc2);
     187             : 
     188             : 
     189             :   casacore::Float itsGain;
     190             :   casacore::Int itsMaxNiter;      // maximum possible number of iterations
     191             :   casacore::Quantum<casacore::Double> itsThreshold;
     192             :   
     193             : 
     194             : private:
     195             : 
     196             :   //# The following functions are used in various places in the code and are
     197             :   //# documented in the .cc file. Static functions are used when the functions
     198             :   //# do not modify the object state. They ensure that implicit assumptions
     199             :   //# about the current state and implicit side-effects are not possible
     200             :   //# because all information must be supplied in the input arguments
     201             : 
     202             :   std::shared_ptr<casacore::Matrix<casacore::Float> > itsMask;
     203             :   std::shared_ptr<casacore::Matrix<casacore::Float> > itsDirty;
     204             :   std::shared_ptr<casacore::Matrix<casacore::Float> > itsPsf;
     205             :   std::shared_ptr<casacore::Matrix<casacore::Float> >itsResidual;
     206             :   std::shared_ptr<casacore::Matrix<casacore::Bool> > itsBitPix;
     207             : 
     208             :   casacore::Float amnesiac(const casacore::Float& val);
     209             :   casacore::Float weak(const casacore::Float& v);
     210             :   casacore::Float medium(const casacore::Float& v);
     211             :   casacore::Float strong(const casacore::Float& v);
     212             : 
     213             :   casacore::Float itsMaximumResidual;
     214             :   casacore::Int itsIteration;   // what iteration did we get to?
     215             :   casacore::Int itsStartingIter;        // what iteration did we get to?
     216             :   casacore::Float itsTotalFlux;
     217             :   casacore::Int itsSupport;
     218             :   casacore::IPosition psfShape_p;
     219             :   casacore::IPosition itsPositionPeakPsf;
     220             :   casacore::Float itsRms;
     221             :   casacore::Int typeOfMemory_p;  //0 nomemory, 1 weak, 2 medium, 3 strong
     222             :   casacore::Float numSigma_p;
     223             :   std::function<casacore::Float(const casacore::Float&)> f_p;
     224             : };
     225             : 
     226             : } //# NAMESPACE CASA - END
     227             : 
     228             : #endif