TempImage.h

Go to the documentation of this file.
00001 //# TempImage.h: Temporary astronomical images
00002 //# Copyright (C) 1998,1999,2000,2001,2003
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id$
00027 
00028 #ifndef IMAGES_TEMPIMAGE_H
00029 #define IMAGES_TEMPIMAGE_H
00030 
00031 
00032 //# Includes
00033 #include <casacore/casa/aips.h>
00034 #include <casacore/images/Images/ImageInterface.h>
00035 #include <casacore/lattices/Lattices/TiledShape.h>
00036 #include <casacore/lattices/Lattices/TempLattice.h>
00037 
00038 
00039 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00040 
00041 // <summary>
00042 // Temporary astronomical images.
00043 // </summary>
00044 
00045 // <use visibility=export>
00046 
00047 // <reviewed reviewer="" date="" tests="tTempImage.cc" demos="">
00048 // </reviewed>
00049 
00050 // <prerequisite>
00051 //   <li> <linkto class=CoordinateSystem>CoordinateSystem</linkto>
00052 //   <li> <linkto class=ImageInterface>ImageInterface</linkto>
00053 //   <li> <linkto class=TempLattice>TempLattice</linkto>
00054 // </prerequisite>
00055 
00056 // <etymology>
00057 // The TempImage name comes from its role as the Image class for temporary
00058 // storage.
00059 // </etymology>
00060 
00061 // <synopsis> 
00062 // The class <src>TempImage</src> is useful for storing temporary images
00063 // for which it is not known whether they can be held in memory.
00064 // It uses class <linkto class=TempLattice>TempLattice</linkto> to
00065 // hold the image in memory when it is small enough. Otherwise it is
00066 // held in a temporary file. Similarly to <src>TempLattice</src>
00067 // one can give the maximum memory to use to control when the image
00068 // can be held in memory.
00069 // <br>
00070 // The other Image information like coordinates, units, and miscinfo
00071 // is held in member variables and disappears when the TempImage object
00072 // is destructed.
00073 // <p>
00074 // It is possibly to temporarily close a TempImage, which only takes effect
00075 // when it is created as a PagedArray. In this way it is possible to reduce
00076 // the number of open files in case a lot of TempImage objects are used.
00077 // A temporarily closed TempImage will be reopened automatically when needed.
00078 // It can also be reopened explicitly.
00079 // </synopsis> 
00080 
00081 // <example>
00082 // <srcblock>
00083 // </srcblock>
00084 // </example>
00085 
00086 // <motivation>
00087 // The size of astronomical data can be very large.  The ability to fit an 
00088 // entire image into random access memory cannot be guaranteed.  Paging from 
00089 // disk pieces of the image appeared to be the way to deal with this problem.
00090 // </motivation>
00091 
00092 //# <todo asof="1998/10/27">
00093 //#  <li> Maybe move applyMask, maskPtr_p, etc to base class ImageInterface
00094 //# </todo>
00095 
00096 
00097 template<class T> class TempImage: public ImageInterface<T>
00098 {
00099 public: 
00100   // The default constructor creates an empty image.
00101   TempImage();
00102 
00103   // Construct a temporary Image from shape and coordinate information.
00104   // If the image is sufficiently small, it is kept in memory.
00105   // Otherwise it is kept in a temporary disk table. It can
00106   // be forced to disk by setting maxMemoryinMB=0.
00107   // The algorithm is the same as in class
00108   // <linkto class=TempLattice>TempLattice</linkto>.
00109   TempImage (const TiledShape& mapShape,
00110              const CoordinateSystem& coordinateInfo,
00111              Int maxMemoryInMB=-1);
00112 
00113   TempImage (const TiledShape& mapShape,
00114              const CoordinateSystem& coordinateInfo,
00115              Double maxMemoryInMB);
00116 
00117   // Copy constructor (reference semantics).
00118   TempImage (const TempImage<T>& other);
00119 
00120   // Destructor
00121   ~TempImage();
00122 
00123   // Assignment operator (reference semantics).
00124   TempImage<T>& operator= (const TempImage<T>& other);
00125 
00126   // Make a copy of the object (reference semantics).
00127   virtual ImageInterface<T>* cloneII() const;
00128 
00129   // Get the image type (returns name of derived class).
00130   virtual String imageType() const;
00131 
00132   // Is the TempImage paged to disk?
00133   virtual Bool isPaged() const;
00134 
00135   // Can the lattice data be referenced as an array section?
00136   virtual Bool canReferenceArray() const;
00137 
00138   // Is the TempImage writable?
00139   virtual Bool isWritable() const;
00140 
00141   // Set the default pixelmask to the mask with the given name
00142   // (which has to exist in the "masks" group).
00143   // If the image table is writable, the setting is persistent by writing
00144   // the name as a keyword.
00145   // If the given regionName is the empty string,
00146   // the default pixelmask is unset.
00147   virtual void setDefaultMask (const String& maskName);
00148 
00149   // Delete the pixel mask attached to the TempImage.
00150   // Does nothing if there isn't one
00151   void removeMask()
00152     { setDefaultMask (""); }
00153 
00154   // Use the mask as specified.
00155   // If a mask was already in use, it is replaced by the new one.
00156   virtual void useMask (MaskSpecifier = MaskSpecifier());
00157 
00158   // Remove a region/mask belonging to the image from the given group
00159   // (which can be Any).
00160   // If a mask removed is the default mask, the image gets unmasked.
00161   // <br>Optionally an exception is thrown if the region does not exist.
00162   virtual void removeRegion (const String& name,
00163                              RegionHandler::GroupType = RegionHandler::Any,
00164                              Bool throwIfUnknown = True);
00165 
00166   // Attach a mask to the TempImage.
00167   // It replaces a probably already attached mask.
00168   // It has to have the same shape as the image.
00169   virtual void attachMask (const Lattice<Bool>& mask);
00170 
00171   // It a mask attached to the image?
00172   virtual Bool isMasked() const;
00173 
00174   // Does the image object use a pixelmask?
00175   // This is similar to <src>isMasked()</src>.
00176   virtual Bool hasPixelMask() const;
00177 
00178   // Get access to the pixelmask used.
00179   // An exception is thrown if the image does not use a pixelmask.
00180   // <group>
00181   virtual const Lattice<Bool>& pixelMask() const;
00182   virtual Lattice<Bool>& pixelMask();
00183   // </group>
00184 
00185   // Get a section of the mask.
00186   // It throws an exception if there is no mask.
00187   virtual Bool doGetMaskSlice (Array<Bool>& buffer, const Slicer& section);
00188 
00189   // Flush the data.
00190   virtual void flush();
00191 
00192   // Close the TempImage temporarily (if it is paged to disk).
00193   // Note that a possible mask is not closed.
00194   // It'll be reopened automatically when needed or when
00195   // <src>reopen</src> is called explicitly.
00196   virtual void tempClose();
00197 
00198   // If needed, reopen a temporarily closed TempLattice.
00199   virtual void reopen();
00200 
00201   // Function which changes the shape of the image (N.B. the data is thrown 
00202   // away - the Image will be filled with nonsense afterwards)
00203   virtual void resize (const TiledShape& newShape);
00204   
00205   // Return the name of the current TempImage object.
00206   // It is always "Temporary_Image"
00207   virtual String name (Bool stripPath=False) const;
00208 
00209   // Return the shape of the image
00210   virtual IPosition shape() const;
00211 
00212   // Function which sets all of the elements in the Lattice to a value.
00213   virtual void set (const T& value);
00214 
00215   // Replace every element, x, of the lattice with the result of f(x).
00216   // You must pass in the address of the function -- so the function
00217   // must be declared and defined in the scope of your program.  
00218   // Both versions of apply require a function that accepts a single 
00219   // argument of type T (the Lattice template actual type) and returns
00220   // a result of the same type.  The first apply expects a function with
00221   // an argument passed by value; the second expects the argument to
00222   // be passed by const reference.  The first form ought to run faster
00223   // for the built-in types, which may be an issue for large images
00224   // stored in memory, where disk access is not an issue.
00225   // <group>
00226   virtual void apply (T (*function)(T));
00227   virtual void apply (T (*function)(const T&));
00228   virtual void apply (const Functional<T,T>& function);
00229   // </group>
00230     
00231   // Get or put a single pixel.
00232   // Note that the function operator () can also be used to get a pixel.
00233   // <group>
00234   virtual T getAt (const IPosition& where) const;
00235   virtual void putAt (const T& value, const IPosition& where);
00236   // </group>
00237 
00238   // This is the implementations of the letters for the envelope Iterator
00239   // class <note> Not for public use </note>
00240   virtual LatticeIterInterface<T>* makeIter
00241                            (const LatticeNavigator& navigator,
00242                             Bool useRef) const;
00243 
00244   // Returns the maximum recommended number of pixels for a cursor.
00245   // This is the number of pixels in a tile. 
00246   virtual uInt advisedMaxPixels() const;
00247 
00248   // Help the user pick a cursor for most efficient access.
00249   virtual IPosition doNiceCursorShape (uInt maxPixels) const;
00250 
00251   // Maximum size - not necessarily all used. In pixels.
00252   virtual uInt maximumCacheSize() const;
00253 
00254   // Set the maximum (allowed) cache size as indicated.
00255   virtual void setMaximumCacheSize (uInt howManyPixels);
00256 
00257   // Set the cache size as to "fit" the indicated path.
00258   virtual void setCacheSizeFromPath (const IPosition& sliceShape,
00259                                      const IPosition& windowStart,
00260                                      const IPosition& windowLength,
00261                                      const IPosition& axisPath);
00262     
00263   // Set the actual cache size for this Array to be be big enough for the
00264   // indicated number of tiles. This cache is not shared with PagedArrays
00265   // in other rows and is always clipped to be less than the maximum value
00266   // set using the setMaximumCacheSize member function.
00267   // tiles. Tiles are cached using a first in first out algorithm. 
00268   virtual void setCacheSizeInTiles (uInt howManyTiles);
00269 
00270   // Clears and frees up the caches, but the maximum allowed cache size is 
00271   // unchanged from when setCacheSize was called
00272   virtual void clearCache();
00273 
00274   // Report on cache success.
00275   virtual void showCacheStatistics (ostream& os) const;
00276 
00277   // Check for symmetry in data members.
00278   virtual Bool ok() const;
00279 
00280 protected:
00281   // Get the region used (it always returns 0).
00282   virtual const LatticeRegion* getRegionPtr() const;
00283 
00284   // Function which extracts an array from the map.
00285   virtual Bool doGetSlice (Array<T>& buffer, const Slicer& theSlice);
00286   
00287   // Function to replace the values in the map with soureBuffer.
00288   virtual void doPutSlice (const Array<T>& sourceBuffer,
00289                            const IPosition& where,
00290                            const IPosition& stride);
00291 
00292 
00293 private:  
00294   void applyMaskSpecifier (const MaskSpecifier&);
00295   void applyMask (const String& maskName);
00296 
00297   TempLattice<T>* mapPtr_p;
00298   Lattice<Bool>*  maskPtr_p;
00299 
00300   //# Make members of parent class known.
00301 public:
00302   using ImageInterface<T>::logger;
00303   using ImageInterface<T>::coordinates;
00304   using ImageInterface<T>::getDefaultMask;
00305   using ImageInterface<T>::hasRegion;
00306   using ImageInterface<T>::getImageRegionPtr;
00307   using ImageInterface<T>::setCoordinateInfo;
00308 protected:
00309   using ImageInterface<T>::setCoordsMember;
00310 };
00311 
00312 //# Declare extern templates for often used types.
00313 #ifdef AIPS_CXX11
00314   extern template class TempImage<Float>;
00315   extern template class TempImage<Complex>;
00316 #endif
00317 
00318 } //# NAMESPACE CASACORE - END
00319 
00320 #ifndef CASACORE_NO_AUTO_TEMPLATES
00321 #include <casacore/images/Images/TempImage.tcc>
00322 #endif //# CASACORE_NO_AUTO_TEMPLATES
00323 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1