Line data    Source code

       1             : #ifndef IMAGEANALYSIS_IMAGETASK_H
       2             : #define IMAGEANALYSIS_IMAGETASK_H
       3             : 
       4             : #include <casacore/casa/Containers/Record.h>
       5             : #include <casacore/lattices/Lattices/Lattice.h>
       6             : #include <imageanalysis/ImageTypedefs.h>
       7             : #include <imageanalysis/IO/OutputDestinationChecker.h>
       8             : #include <imageanalysis/Regions/CasacRegionManager.h>
       9             : 
      10             : #include <memory>
      11             : 
      12             : #include <components/ComponentModels/C11Timer.h>
      13             : 
      14             : namespace casacore{
      15             : 
      16             : template <class T> class ArrayLattice;
      17             : }
      18             : 
      19             : namespace casac {
      20             : class variant;
      21             : }
      22             : 
      23             : namespace casa {
      24             : 
      25             : class LogFile;
      26             : 
      27             : template <class T> class ImageTask {
      28             : 
      29             :     // <summary>
      30             :     // Virtual base class for image analysis tasks.
      31             :     // </summary>
      32             : 
      33             :     // <reviewed reviewer="" date="" tests="" demos="">
      34             :     // </reviewed>
      35             : 
      36             :     // <prerequisite>
      37             :     // </prerequisite>
      38             : 
      39             :     // <etymology>
      40             :     // Image tasking
      41             :     // </etymology>
      42             : 
      43             :     // <synopsis>
      44             :     // Virtual base class for image tasking.
      45             :     // </synopsis>
      46             : 
      47             : public:
      48             : 
      49             :     // verbosity levels
      50             :     enum Verbosity {
      51             :         QUIET,
      52             :         WHISPER,
      53             :         LOW,
      54             :         NORMAL,
      55             :         HIGH,
      56             :         NOISY,
      57             :         DEAFENING
      58             :     };
      59             : 
      60             :     virtual ~ImageTask();
      61             : 
      62             :     virtual casacore::String getClass() const = 0;
      63             : 
      64           0 :     inline void setStretch(const casacore::Bool stretch) { _stretch = stretch;}
      65             : 
      66             :     // tacitly does nothing if <src>lf</src> is the empty string.
      67             :     void setLogfile(const casacore::String& lf);
      68             : 
      69             :     void setLogfileAppend(const casacore::Bool a);
      70             : 
      71             :     void setRegion(const casacore::Record& region);
      72             : 
      73             :     void setMask(const casacore::String& mask) { _mask = mask; }
      74             : 
      75             :     void setVerbosity(Verbosity verbosity) { _verbosity = verbosity; }
      76             : 
      77             :     // <group>
      78             :     // These messages will appear in the product image history upon the call to
      79             :     // _prepareOutputImage(). They will be located immediately after the input
      80             :     // image's copied history. The first value in the pair is the log origin.
      81             :     // The second is the associated message. If this method is called more than once
      82             :     // on the same object, messages from subsequent calls are appended to the
      83             :     // end of messages set in prior calls.
      84             :     void addHistory(const std::vector<std::pair<casacore::String, casacore::String> >& msgs) const;
      85             : 
      86             :     void addHistory(const casacore::LogOrigin& origin, const casacore::String& msg) const;
      87             : 
      88             :     void addHistory(const casacore::LogOrigin& origin, const std::vector<casacore::String>& msgs) const;
      89             : 
      90             :     // This adds standard history messages regarding the task that was run and
      91             :     // input parameters used. The vectors must have the same length
      92             :     void addHistory(
      93             :         const casacore::LogOrigin& origin, const casacore::String& taskname,
      94             :         const std::vector<casacore::String>& paramNames, const std::vector<casac::variant>& paramValues
      95             :     ) const;
      96             :     // </group>
      97             : 
      98             :     // suppress writing the history on _prepareOutputImage() call. Useful for
      99             :     // not writing history to intermediate image products.
     100           0 :     void suppressHistoryWriting(casacore::Bool b) { _suppressHistory = b; }
     101             : 
     102             :     // get the history associated with the task. Does not include the
     103             :     // history of the input image.
     104           0 :     std::vector<std::pair<casacore::String, casacore::String> > getHistory() {return _newHistory;}
     105             : 
     106           0 :     void setDropDegen(casacore::Bool d) { _dropDegen = d; }
     107             : 
     108             : protected:
     109             : 
     110             :     // if <src>outname</src> is empty, no image will be written
     111             :     // if <src>overwrite</src> is True, if image already exists it will be removed
     112             :     // if <src>overwrite</src> is False, if image already exists exception will be thrown
     113             :     ImageTask(
     114             :         const SPCIIT image,
     115             :         const casacore::String& region, const casacore::Record *const &regionPtr,
     116             :         const casacore::String& box, const casacore::String& chanInp,
     117             :         const casacore::String& stokes, const casacore::String& maskInp,
     118             :         const casacore::String& outname, casacore::Bool overwrite
     119             :     );
     120             : 
     121             :     ImageTask(
     122             :         const SPCIIT image, const casacore::Record *const &regionPtr,
     123             :         const casacore::String& mask,
     124             :         const casacore::String& outname, casacore::Bool overwrite
     125             :     );
     126             : 
     127             :     virtual CasacRegionManager::StokesControl _getStokesControl() const = 0;
     128             : 
     129             :     virtual std::vector<OutputDestinationChecker::OutputStruct> _getOutputStruct();
     130             : 
     131             :     // does the lion's share of constructing the object, ie checks validity of
     132             :     // inputs, etc.
     133             : 
     134             :     virtual void _construct(casacore::Bool verbose=true);
     135             : 
     136           0 :     inline const SPCIIT _getImage() const {return _image;}
     137             : 
     138           0 :     inline const casacore::String& _getMask() const {return _mask;}
     139             : 
     140           0 :     inline const casacore::Record* _getRegion() const {return &_regionRecord;}
     141             : 
     142             :     inline void _setStokes(const casacore::String& stokes) { _stokesString = stokes; }
     143             : 
     144             :     inline const casacore::String& _getStokes() const {return _stokesString;}
     145             : 
     146             :     inline const casacore::String& _getChans() const {return _chan;}
     147             : 
     148           0 :     inline const casacore::String& _getOutname() const {return _outname; }
     149             : 
     150             :     // Represents the minimum set of coordinates necessary for the
     151             :     // task to function.
     152             :     virtual std::vector<casacore::Coordinate::Type> _getNecessaryCoordinates() const = 0;
     153             : 
     154             :     // Is the attached image a position-velocity (PV) image?
     155             :     casacore::Bool _isPVImage() const;
     156             : 
     157             :     void _removeExistingOutfileIfNecessary() const;
     158             : 
     159             :     // if warnOnly is true, log a warning message if file exists and
     160             :     // overwrite is true, else throw an exception.
     161             :     void _removeExistingFileIfNecessary(
     162             :         const casacore::String& filename, const casacore::Bool overwrite, casacore::Bool warnOnly=false
     163             :     ) const;
     164             : 
     165             :     casacore::String _summaryHeader() const;
     166             : 
     167           0 :     inline const std::shared_ptr<casacore::LogIO> _getLog() const {return _log;}
     168             : 
     169             :     // by default, derived classes are configured to have no log file
     170             :     // support.
     171           0 :     virtual casacore::Bool _hasLogfileSupport() const {return false;}
     172             : 
     173           0 :     inline casacore::Bool _getStretch() const {return _stretch;}
     174             : 
     175             :     Bool _getSuppressHistory() const { return _suppressHistory; }
     176             : 
     177             :     const std::shared_ptr<LogFile> _getLogFile() const;
     178             : 
     179             :     casacore::Bool _writeLogfile(
     180             :         const casacore::String& output, const casacore::Bool open=true,
     181             :         const casacore::Bool close=true
     182             :     );
     183             : 
     184             :     casacore::Bool _openLogfile();
     185             : 
     186             :     void _closeLogfile() const;
     187             : 
     188           0 :     virtual inline casacore::Bool _supportsMultipleRegions() const {return false;}
     189             : 
     190             :     // does this task support images with multiple beams? false means it never does.
     191             :     // true means it does, but not necessarily in all cases (in which case, the
     192             :     // derived class is responsible for checking for and throwing exceptions in those cases).
     193           0 :     virtual inline casacore::Bool _supportsMultipleBeams() const {return true;}
     194             : 
     195             :     // If outname != NULL, use the value supplied. If is NULL, use the value of _outname.
     196             :     // Create a casacore::TempImage or casacore::PagedImage depending if outname/_outname is empty or not. Generally meant
     197             :     // for the image to be returned to the UI or the final image product that the user will want.
     198             :     // values=0 => the pixel values from the image will be used
     199             :     // mask=0 => the mask attached to the image, if any will be used, outShape=0 => use image shape, coordsys=0 => use image coordinate
     200             :     // system. overwrite is only used if outname != NULL.
     201             : 
     202             :     SPIIT _prepareOutputImage(
     203             :         const casacore::ImageInterface<T>& image, const casacore::Array<T> *const values,
     204             :         const casacore::ArrayLattice<casacore::Bool> *const mask=nullptr,
     205             :         const casacore::IPosition *const outShape=nullptr, const casacore::CoordinateSystem *const coordsys=nullptr,
     206             :         const casacore::String *const outname=nullptr, casacore::Bool overwrite=false, casacore::Bool dropDegen=false
     207             :     ) const;
     208             : 
     209             :     SPIIT _prepareOutputImage(
     210             :         const casacore::ImageInterface<T>& image, casacore::Bool dropDegen=false
     211             :     ) const;
     212             : 
     213             :     // if warnOnly is true, only log a warning message if the file exists and
     214             :     // overwrite is true, else throw an excepction
     215             :     SPIIT _prepareOutputImage(
     216             :         const casacore::ImageInterface<T>& image, const casacore::String& outname,
     217             :         casacore::Bool overwrite, casacore::Bool warnOnly
     218             :     ) const;
     219             : 
     220             :     // data are copied to the output image from the <src>data</src>
     221             :     // lattice. The mask is copied from the input image.
     222             :     SPIIT _prepareOutputImage(
     223             :         const casacore::ImageInterface<T>& image, const casacore::Lattice<T>& data
     224             :     ) const;
     225             : 
     226             :     Verbosity _getVerbosity() const { return _verbosity; }
     227             : 
     228           0 :     casacore::Bool _getOverwrite() const { return _overwrite; }
     229             : 
     230           0 :     virtual casacore::Bool _mustHaveSquareDirectionPixels() const {return false;}
     231             : 
     232           0 :     casacore::Bool _getDropDegen() const { return _dropDegen; }
     233             : 
     234             :     static void _copyMask(casacore::Lattice<casacore::Bool>& mask, const casacore::ImageInterface<T>& image);
     235             : 
     236             :     static void _copyData(casacore::Lattice<T>& data, const casacore::Lattice<T>& image);
     237             : 
     238             :     template <class U> void _doHistory(std::shared_ptr<casacore::ImageInterface<U>>& image) const;
     239             : 
     240             :     void _reportOldNewImageShapes(const ImageInterface<T>& out) const;
     241             :     
     242             :     void _reportOldNewImageShapes(const IPosition& outShape) const;
     243             : 
     244             : private:
     245             :     const SPCIIT _image;
     246             :     mutable std::shared_ptr<casacore::LogIO> _log = std::shared_ptr<casacore::LogIO>(new casacore::LogIO());
     247             :     const casacore::Record *const _regionPtr;
     248             :     casacore::Record _regionRecord;
     249             :     casacore::String _region = "";
     250             :     casacore::String _box = "";
     251             :     casacore::String _chan = "";
     252             :     casacore::String _stokesString = "";
     253             :     casacore::String _mask = "";
     254             :     casacore::String _outname = "";
     255             :     casacore::Bool _overwrite = false;
     256             :     casacore::Bool _stretch = false;
     257             :     casacore::Bool _logfileAppend = false;
     258             :     casacore::Bool _suppressHistory = false;
     259             :     casacore::Bool _dropDegen = false;
     260             :     std::unique_ptr<casacore::FiledesIO> _logFileIO;
     261             :     Verbosity _verbosity = NORMAL;
     262             :     std::shared_ptr<LogFile> _logfile;
     263             :     mutable std::vector<std::pair<casacore::String, casacore::String> > _newHistory;
     264             : 
     265             :     mutable C11Timer _timer;
     266             : };
     267             : 
     268             : }
     269             : 
     270             : #ifndef AIPS_NO_TEMPLATE_SRC
     271             : #include <imageanalysis/ImageAnalysis/ImageTask.tcc>
     272             : #endif
     273             : 
     274             : #endif