Loading...
Searching...
No Matches
LatticeCleaner.h
Go to the documentation of this file.
//# Cleaner.h: this defines Cleaner a class for doing convolution
//# Copyright (C) 1996,1997,1998,1999,2000,2001,2002,2003
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef LATTICES_LATTICECLEANER_H
#define LATTICES_LATTICECLEANER_H
//# Includes
#include <casacore/casa/aips.h>
#include <casacore/casa/Quanta/Quantum.h>
#include <casacore/lattices/Lattices/TempLattice.h>
#include <casacore/casa/Arrays/IPosition.h>
#include <casacore/casa/Arrays/Vector.h>
#include <casacore/casa/Containers/Block.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
//# Forward Declarations
class LatticeCleanProgress;
template <class T> class TempLattice;
// <summary>Lists the different types of Convolutions that can be done</summary>
// <synopsis>This enumerator is brought out as a separate class because g++
// currently cannot handle enumerators in a templated class. When it can this
// class will go away and this enumerator moved into the Cleaner
// class</synopsis>
class CleanEnums {
public:
enum CleanType {
// Hogbom
HOGBOM,
// Multi-scale
MULTISCALE,
// Clark
CLARK
};
};
// <summary>A class for doing multi-dimensional cleaning</summary>
// <use visibility=export>
// <reviewed reviewer="" date="yyyy/mm/dd" tests="tLatticeCleaner">
// </reviewed>
// <prerequisite>
// <li> The mathematical concept of deconvolution
// </prerequisite>
//
// <etymology>
// The LatticeCleaner class will deconvolve Lattices.
// </etymology>
//
// <synopsis>
// This class will perform various types of Clean deconvolution
// on Lattices.
//
// </synopsis>
//
// <example>
// <srcblock>
// </srcblock>
// </example>
//
// <motivation>
// </motivation>
//
// <thrown>
// <li> AipsError: if psf has more dimensions than the model.
// </thrown>
//
// <todo asof="yyyy/mm/dd">
// <li> Allow the psf to be specified with a
// <linkto class=Function>Function</linkto>.
// </todo>
template<class T> class LatticeCleaner
{
public:
// Create a cleaner : default constructor
LatticeCleaner();
// Create a cleaner for a specific dirty image and PSF
LatticeCleaner(const Lattice<T> & psf, const Lattice<T> & dirty);
// The copy constructor uses reference semantics
LatticeCleaner(const LatticeCleaner<T> & other);
// The assignment operator also uses reference semantics
LatticeCleaner<T> & operator=(const LatticeCleaner<T> & other);
// The destructor does nothing special.
~LatticeCleaner();
// Update the dirty image only
void update(const Lattice<T> & dirty);
// Set a number of scale sizes. The units of the scale are pixels.
Bool setscales(const Int nscales, const Float scaleInc=1.0);
// Set a specific set of scales
Bool setscales(const Vector<Float> & scales);
// Set up control parameters
// cleanType - type of the cleaning algorithm to use (HOGBOM, MULTISCALE)
// niter - number of iterations
// gain - loop gain used in cleaning (a fraction of the maximum
// subtracted at every iteration)
// aThreshold - absolute threshold to stop iterations
// fThreshold - fractional threshold (i.e. given w.r.t. maximum residual)
// to stop iterations. This parameter is specified as
// Quantity so it can be given in per cents.
// choose - unused at the moment, specify False. Original meaning is
// to allow interactive decision on whether to continue iterations.
// This method always returns True.
Bool setcontrol(CleanEnums::CleanType cleanType, const Int niter,
const Float gain, const Quantity& aThreshold,
const Quantity& fThreshold,
const Bool choose=True);
// This version of the method disables stopping on fractional threshold
Bool setcontrol(CleanEnums::CleanType cleanType, const Int niter,
const Float gain, const Quantity& threshold,
const Bool choose=True);
// return how many iterations we did do
Int iteration() const { return itsIteration; }
Int numberIterations() const { return itsIteration; }
// what iteration number to start on
void startingIteration(const Int starting = 0) {itsStartingIter = starting; }
// Clean an image.
//return value gives you a hint of what's happening
// 1 = converged
// 0 = not converged but behaving normally
// -1 = not converged and stopped on cleaning consecutive smallest scale
// -2 = not converged and either large scale hit negative or diverging
// -3 = clean is diverging rather than converging
Int clean(Lattice<T> & model, LatticeCleanProgress* progress=0);
// Set the mask
// mask - input mask lattice
// maskThreshold - if positive, the value is treated as a threshold value to determine
// whether a pixel is good (mask value is greater than the threshold) or has to be
// masked (mask value is below the threshold). Negative threshold switches mask clipping
// off. The mask value is used to weight the flux during cleaning. This mode is used
// to implement cleaning based on the signal-to-noise as opposed to the standard cleaning
// based on the flux. The default threshold value is 0.9, which ensures the behavior of the
// code is exactly the same as before this parameter has been introduced.
void setMask(const Lattice<T> & mask, const T& maskThreshold = T(0.9));
// Tell the algorithm to NOT clean just the inner quarter
// (This is useful when multiscale clean is being used
// inside a major cycle for MF or WF algorithms)
// if True, the full image deconvolution will be attempted
void ignoreCenterBox(Bool huh) { itsIgnoreCenterBox = huh; }
// Consider the case of a point source:
// the flux on all scales is the same, and the first scale will be chosen.
// Now, consider the case of a point source with a *little* bit of extended structure:
// thats right, the largest scale will be chosen. In this case, we should provide some
// bias towards the small scales, or against the large scales. We do this in
// an ad hoc manner, multiplying the maxima found at each scale by
// 1.0 - itsSmallScaleBias * itsScaleSizes(scale)/itsScaleSizes(nScalesToClean-1);
// Typical bias values range from 0.2 to 1.0.
void setSmallScaleBias(const Float x=0.5) { itsSmallScaleBias = x; }
// During early iterations of a cycled MS Clean in mosaicing, it common
// to come across an ocsilatory pattern going between positive and
// negative in the large scale. If this is set, we stop at the first
// negative in the largest scale.
void stopAtLargeScaleNegative() {itsStopAtLargeScaleNegative = True; }
// Some algorithms require that the cycles be terminated when the image
// is dominated by point sources; if we get nStopPointMode of the
// smallest scale components in a row, we terminate the cycles
void stopPointMode(Int nStopPointMode) {itsStopPointMode = nStopPointMode; }
// After completion of cycle, querry this to find out if we stopped because
// of stopPointMode
Bool queryStopPointMode() const {return itsDidStopPointMode; }
// speedup() will speed the clean iteration by raising the
// threshold. This may be required if the threshold is
// accidentally set too low (ie, lower than can be achieved
// given errors in the approximate PSF).
//
// threshold(iteration) = threshold(0)
// * ( exp( (iteration - startingiteration)/Ndouble )/ 2.718 )
// If speedup() is NOT invoked, no effect on threshold
void speedup(const Float Ndouble);
// Look at what WE think the residuals look like
// Assumes the first scale is zero-sized
Lattice<T>* residual() { return itsDirtyConvScales[0]; }
// Method to return threshold, including any speedup factors
Float threshold() const;
// Method to return the strength optimum achieved at the last clean iteration
// The output of this method makes sense only if it is called after clean
T strengthOptimum() const { return itsStrengthOptimum; }
// Helper function to optimize adding
static void addTo(Lattice<T>& to, const Lattice<T>& add);
protected:
// Make sure that the peak of the Psf is within the image
Bool validatePsf(const Lattice<T> & psf);
// Make an lattice of the specified scale
void makeScale(Lattice<T>& scale, const Float& scaleSize);
// Make Spheroidal function for scale images
Float spheroidal(Float nu);
// Find the Peak of the Lattice
static Bool findMaxAbsLattice(const Lattice<T>& lattice,
T& maxAbs, IPosition& posMax);
// Find the Peak of the lattice, applying a mask
Bool findMaxAbsMaskLattice(const Lattice<T>& lattice, const Lattice<T>& mask,
T& maxAbs, IPosition& posMax);
// Helper function to reduce the box sizes until the have the same
// size keeping the centers intact
static void makeBoxesSameSize(IPosition& blc1, IPosition& trc1,
IPosition &blc2, IPosition& trc2);
CleanEnums::CleanType itsCleanType;
Float itsGain;
Int itsMaxNiter; // maximum possible number of iterations
Quantum<Double> itsThreshold;
TempLattice<T>* itsMask;
IPosition itsPositionPeakPsf;
private:
//# The following functions are used in various places in the code and are
//# documented in the .cc file. Static functions are used when the functions
//# do not modify the object state. They ensure that implicit assumptions
//# about the current state and implicit side-effects are not possible
//# because all information must be supplied in the input arguments
TempLattice<T>* itsDirty;
TempLattice<Complex>* itsXfr;
Int itsNscales;
Vector<Float> itsScaleSizes;
PtrBlock<TempLattice<T>* > itsScales;
PtrBlock<TempLattice<Complex>* > itsScaleXfrs;
PtrBlock<TempLattice<T>* > itsPsfConvScales;
PtrBlock<TempLattice<T>* > itsDirtyConvScales;
PtrBlock<TempLattice<T>* > itsScaleMasks;
Bool itsScalesValid;
Int itsIteration; // what iteration did we get to?
Int itsStartingIter; // what iteration did we get to?
Quantum<Double> itsFracThreshold;
Float itsMaximumResidual;
T itsStrengthOptimum;
Vector<Float> itsTotalFluxScale;
Float itsTotalFlux;
// Memory to be allocated per TempLattice
Double itsMemoryMB;
// Let the user choose whether to stop
Bool itsChoose;
// Threshold speedup factors:
Bool itsDoSpeedup; // if false, threshold does not change with iteration
Float itsNDouble;
//# Stop now?
//#// Bool stopnow(); Removed on 8-Apr-2004 by GvD
// Calculate index into PsfConvScales
Int index(const Int scale, const Int otherscale);
Bool destroyScales();
Bool destroyMasks();
Bool makeScaleMasks();
Bool itsIgnoreCenterBox;
Float itsSmallScaleBias;
Bool itsStopAtLargeScaleNegative;
Int itsStopPointMode;
Bool itsDidStopPointMode;
Bool itsJustStarting;
// threshold for masks. If negative, mask values are used as weights and no pixels are
// discarded (although effectively they would be discarded if the mask value is 0.)
T itsMaskThreshold;
};
} //# NAMESPACE CASACORE - END
#ifndef CASACORE_NO_AUTO_TEMPLATES
#include <casacore/lattices/LatticeMath/LatticeCleaner.tcc>
#endif //# CASACORE_NO_AUTO_TEMPLATES
#endif
casacore::CleanEnums
Definition LatticeCleaner.h:49
casacore::CleanEnums::CleanType
CleanType
Definition LatticeCleaner.h:51
casacore::CleanEnums::MULTISCALE
@ MULTISCALE
Multi-scale.
Definition LatticeCleaner.h:55
casacore::CleanEnums::HOGBOM
@ HOGBOM
Hogbom.
Definition LatticeCleaner.h:53
casacore::CleanEnums::CLARK
@ CLARK
Clark.
Definition LatticeCleaner.h:57
casacore::IPosition
Definition IPosition.h:117
casacore::LatticeCleanProgress
Definition LatticeCleanProgress.h:87
casacore::LatticeCleaner::findMaxAbsMaskLattice
Bool findMaxAbsMaskLattice(const Lattice< T > &lattice, const Lattice< T > &mask, T &maxAbs, IPosition &posMax)
Find the Peak of the lattice, applying a mask.
casacore::LatticeCleaner::itsScales
PtrBlock< TempLattice< T > * > itsScales
Definition LatticeCleaner.h:277
casacore::LatticeCleaner::itsMaskThreshold
T itsMaskThreshold
threshold for masks.
Definition LatticeCleaner.h:326
casacore::LatticeCleaner::itsJustStarting
Bool itsJustStarting
Definition LatticeCleaner.h:322
casacore::LatticeCleaner::makeScaleMasks
Bool makeScaleMasks()
casacore::LatticeCleaner::itsScaleSizes
Vector< Float > itsScaleSizes
Definition LatticeCleaner.h:275
casacore::LatticeCleaner::itsStartingIter
Int itsStartingIter
Definition LatticeCleaner.h:286
casacore::LatticeCleaner::~LatticeCleaner
~LatticeCleaner()
The destructor does nothing special.
casacore::LatticeCleaner::itsSmallScaleBias
Float itsSmallScaleBias
Definition LatticeCleaner.h:318
casacore::LatticeCleaner::itsChoose
Bool itsChoose
Let the user choose whether to stop.
Definition LatticeCleaner.h:300
casacore::LatticeCleaner::itsDidStopPointMode
Bool itsDidStopPointMode
Definition LatticeCleaner.h:321
casacore::LatticeCleaner::stopPointMode
void stopPointMode(Int nStopPointMode)
Some algorithms require that the cycles be terminated when the image is dominated by point sources; i...
Definition LatticeCleaner.h:202
casacore::LatticeCleaner::itsGain
Float itsGain
Definition LatticeCleaner.h:257
casacore::LatticeCleaner::clean
Int clean(Lattice< T > &model, LatticeCleanProgress *progress=0)
Clean an image.
casacore::LatticeCleaner::itsScalesValid
Bool itsScalesValid
Definition LatticeCleaner.h:283
casacore::LatticeCleaner::setscales
Bool setscales(const Vector< Float > &scales)
Set a specific set of scales.
casacore::LatticeCleaner::LatticeCleaner
LatticeCleaner(const Lattice< T > &psf, const Lattice< T > &dirty)
Create a cleaner for a specific dirty image and PSF.
casacore::LatticeCleaner::itsMemoryMB
Double itsMemoryMB
Memory to be allocated per TempLattice.
Definition LatticeCleaner.h:297
casacore::LatticeCleaner::setcontrol
Bool setcontrol(CleanEnums::CleanType cleanType, const Int niter, const Float gain, const Quantity &aThreshold, const Quantity &fThreshold, const Bool choose=True)
Set up control parameters cleanType - type of the cleaning algorithm to use (HOGBOM,...
casacore::LatticeCleaner::itsPositionPeakPsf
IPosition itsPositionPeakPsf
Definition LatticeCleaner.h:261
casacore::LatticeCleaner::addTo
static void addTo(Lattice< T > &to, const Lattice< T > &add)
Helper function to optimize adding.
casacore::LatticeCleaner::makeScale
void makeScale(Lattice< T > &scale, const Float &scaleSize)
Make an lattice of the specified scale.
casacore::LatticeCleaner::itsDirtyConvScales
PtrBlock< TempLattice< T > * > itsDirtyConvScales
Definition LatticeCleaner.h:280
casacore::LatticeCleaner::itsFracThreshold
Quantum< Double > itsFracThreshold
Definition LatticeCleaner.h:287
casacore::LatticeCleaner::setcontrol
Bool setcontrol(CleanEnums::CleanType cleanType, const Int niter, const Float gain, const Quantity &threshold, const Bool choose=True)
This version of the method disables stopping on fractional threshold.
casacore::LatticeCleaner::numberIterations
Int numberIterations() const
Definition LatticeCleaner.h:152
casacore::LatticeCleaner::itsMaxNiter
Int itsMaxNiter
Definition LatticeCleaner.h:258
casacore::LatticeCleaner::findMaxAbsLattice
static Bool findMaxAbsLattice(const Lattice< T > &lattice, T &maxAbs, IPosition &posMax)
Find the Peak of the Lattice.
casacore::LatticeCleaner::setscales
Bool setscales(const Int nscales, const Float scaleInc=1.0)
Set a number of scale sizes.
casacore::LatticeCleaner::validatePsf
Bool validatePsf(const Lattice< T > &psf)
Make sure that the peak of the Psf is within the image.
casacore::LatticeCleaner::speedup
void speedup(const Float Ndouble)
speedup() will speed the clean iteration by raising the threshold.
casacore::LatticeCleaner::itsScaleXfrs
PtrBlock< TempLattice< Complex > * > itsScaleXfrs
Definition LatticeCleaner.h:278
casacore::LatticeCleaner::ignoreCenterBox
void ignoreCenterBox(Bool huh)
Tell the algorithm to NOT clean just the inner quarter (This is useful when multiscale clean is being...
Definition LatticeCleaner.h:181
casacore::LatticeCleaner::itsIteration
Int itsIteration
Definition LatticeCleaner.h:285
casacore::LatticeCleaner::threshold
Float threshold() const
Method to return threshold, including any speedup factors.
casacore::LatticeCleaner::operator=
LatticeCleaner< T > & operator=(const LatticeCleaner< T > &other)
The assignment operator also uses reference semantics.
casacore::LatticeCleaner::startingIteration
void startingIteration(const Int starting=0)
what iteration number to start on
Definition LatticeCleaner.h:155
casacore::LatticeCleaner::setMask
void setMask(const Lattice< T > &mask, const T &maskThreshold=T(0.9))
Set the mask mask - input mask lattice maskThreshold - if positive, the value is treated as a thresho...
casacore::LatticeCleaner::itsMask
TempLattice< T > * itsMask
Definition LatticeCleaner.h:260
casacore::LatticeCleaner::setSmallScaleBias
void setSmallScaleBias(const Float x=0.5)
Consider the case of a point source: the flux on all scales is the same, and the first scale will be ...
Definition LatticeCleaner.h:191
casacore::LatticeCleaner::LatticeCleaner
LatticeCleaner()
Create a cleaner : default constructor.
casacore::LatticeCleaner::itsCleanType
CleanEnums::CleanType itsCleanType
Definition LatticeCleaner.h:256
casacore::LatticeCleaner::update
void update(const Lattice< T > &dirty)
Update the dirty image only.
casacore::LatticeCleaner::destroyScales
Bool destroyScales()
casacore::LatticeCleaner::residual
Lattice< T > * residual()
Look at what WE think the residuals look like Assumes the first scale is zero-sized.
Definition LatticeCleaner.h:220
casacore::LatticeCleaner::itsDoSpeedup
Bool itsDoSpeedup
Threshold speedup factors:
Definition LatticeCleaner.h:303
casacore::LatticeCleaner::itsTotalFluxScale
Vector< Float > itsTotalFluxScale
Definition LatticeCleaner.h:293
casacore::LatticeCleaner::strengthOptimum
T strengthOptimum() const
Method to return the strength optimum achieved at the last clean iteration The output of this method ...
Definition LatticeCleaner.h:227
casacore::LatticeCleaner::itsIgnoreCenterBox
Bool itsIgnoreCenterBox
Definition LatticeCleaner.h:317
casacore::LatticeCleaner::index
Int index(const Int scale, const Int otherscale)
Calculate index into PsfConvScales.
casacore::LatticeCleaner::queryStopPointMode
Bool queryStopPointMode() const
After completion of cycle, querry this to find out if we stopped because of stopPointMode.
Definition LatticeCleaner.h:206
casacore::LatticeCleaner::makeBoxesSameSize
static void makeBoxesSameSize(IPosition &blc1, IPosition &trc1, IPosition &blc2, IPosition &trc2)
Helper function to reduce the box sizes until the have the same size keeping the centers intact.
casacore::LatticeCleaner::itsXfr
TempLattice< Complex > * itsXfr
Definition LatticeCleaner.h:272
casacore::LatticeCleaner::destroyMasks
Bool destroyMasks()
casacore::LatticeCleaner::itsStrengthOptimum
T itsStrengthOptimum
Definition LatticeCleaner.h:290
casacore::LatticeCleaner::itsStopPointMode
Int itsStopPointMode
Definition LatticeCleaner.h:320
casacore::LatticeCleaner::itsNDouble
Float itsNDouble
Definition LatticeCleaner.h:304
casacore::LatticeCleaner::spheroidal
Float spheroidal(Float nu)
Make Spheroidal function for scale images.
casacore::LatticeCleaner::itsStopAtLargeScaleNegative
Bool itsStopAtLargeScaleNegative
Definition LatticeCleaner.h:319
casacore::LatticeCleaner::iteration
Int iteration() const
return how many iterations we did do
Definition LatticeCleaner.h:151
casacore::LatticeCleaner::itsThreshold
Quantum< Double > itsThreshold
Definition LatticeCleaner.h:259
casacore::LatticeCleaner::itsTotalFlux
Float itsTotalFlux
Definition LatticeCleaner.h:294
casacore::LatticeCleaner::itsDirty
TempLattice< T > * itsDirty
Definition LatticeCleaner.h:271
casacore::LatticeCleaner::itsPsfConvScales
PtrBlock< TempLattice< T > * > itsPsfConvScales
Definition LatticeCleaner.h:279
casacore::LatticeCleaner::itsScaleMasks
PtrBlock< TempLattice< T > * > itsScaleMasks
Definition LatticeCleaner.h:281
casacore::LatticeCleaner::itsMaximumResidual
Float itsMaximumResidual
Definition LatticeCleaner.h:289
casacore::LatticeCleaner::itsNscales
Int itsNscales
Definition LatticeCleaner.h:274
casacore::LatticeCleaner::LatticeCleaner
LatticeCleaner(const LatticeCleaner< T > &other)
The copy constructor uses reference semantics.
casacore::LatticeCleaner::stopAtLargeScaleNegative
void stopAtLargeScaleNegative()
During early iterations of a cycled MS Clean in mosaicing, it common to come across an ocsilatory pat...
Definition LatticeCleaner.h:197
casacore::Lattice
Definition Lattice.h:230
casacore::PtrBlock
A drop-in replacement for Block<T*>.
Definition Block.h:812
casacore::Quantum
Definition Quantum.h:269
casacore::TempLattice
Definition TempLattice.h:130
casacore::Vector
Definition Vector.h:82
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::mask
LatticeExprNode mask(const LatticeExprNode &expr)
This function returns the mask of the given expression.
casacore::Float
float Float
Definition aipstype.h:52
casacore::Int
int Int
Definition aipstype.h:48
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
casacore::Quantity
Quantum< Double > Quantity
Definition Quantum.h:39
casacore::True
const Bool True
Definition aipstype.h:41
casacore::Double
double Double
Definition aipstype.h:53