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