casacore
TempImage.h
Go to the documentation of this file.
1 //# TempImage.h: Temporary astronomical images
2 //# Copyright (C) 1998,1999,2000,2001,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 Library General Public License as published by
7 //# the Free Software Foundation; either version 2 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 //# $Id$
27 
28 #ifndef IMAGES_TEMPIMAGE_H
29 #define IMAGES_TEMPIMAGE_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/images/Images/ImageInterface.h>
35 #include <casacore/lattices/Lattices/TiledShape.h>
36 #include <casacore/lattices/Lattices/TempLattice.h>
37 
38 
39 namespace casacore { //# NAMESPACE CASACORE - BEGIN
40 
41 // <summary>
42 // Temporary astronomical images.
43 // </summary>
44 
45 // <use visibility=export>
46 
47 // <reviewed reviewer="" date="" tests="tTempImage.cc" demos="">
48 // </reviewed>
49 
50 // <prerequisite>
51 // <li> <linkto class=CoordinateSystem>CoordinateSystem</linkto>
52 // <li> <linkto class=ImageInterface>ImageInterface</linkto>
53 // <li> <linkto class=TempLattice>TempLattice</linkto>
54 // </prerequisite>
55 
56 // <etymology>
57 // The TempImage name comes from its role as the Image class for temporary
58 // storage.
59 // </etymology>
60 
61 // <synopsis>
62 // The class <src>TempImage</src> is useful for storing temporary images
63 // for which it is not known whether they can be held in memory.
64 // It uses class <linkto class=TempLattice>TempLattice</linkto> to
65 // hold the image in memory when it is small enough. Otherwise it is
66 // held in a temporary file. Similarly to <src>TempLattice</src>
67 // one can give the maximum memory to use to control when the image
68 // can be held in memory.
69 // <br>
70 // The other Image information like coordinates, units, and miscinfo
71 // is held in member variables and disappears when the TempImage object
72 // is destructed.
73 // <p>
74 // It is possibly to temporarily close a TempImage, which only takes effect
75 // when it is created as a PagedArray. In this way it is possible to reduce
76 // the number of open files in case a lot of TempImage objects are used.
77 // A temporarily closed TempImage will be reopened automatically when needed.
78 // It can also be reopened explicitly.
79 // </synopsis>
80 
81 // <example>
82 // <srcblock>
83 // </srcblock>
84 // </example>
85 
86 // <motivation>
87 // The size of astronomical data can be very large. The ability to fit an
88 // entire image into random access memory cannot be guaranteed. Paging from
89 // disk pieces of the image appeared to be the way to deal with this problem.
90 // </motivation>
91 
92 //# <todo asof="1998/10/27">
93 //# <li> Maybe move applyMask, maskPtr_p, etc to base class ImageInterface
94 //# </todo>
95 
96 
97 template<class T> class TempImage: public ImageInterface<T>
98 {
99 public:
100  // The default constructor creates an empty image.
102 
103  // Construct a temporary Image from shape and coordinate information.
104  // If the image is sufficiently small, it is kept in memory.
105  // Otherwise it is kept in a temporary disk table. It can
106  // be forced to disk by setting maxMemoryinMB=0.
107  // The algorithm is the same as in class
108  // <linkto class=TempLattice>TempLattice</linkto>.
109  TempImage (const TiledShape& mapShape,
110  const CoordinateSystem& coordinateInfo,
111  Int maxMemoryInMB=-1);
112 
113  TempImage (const TiledShape& mapShape,
114  const CoordinateSystem& coordinateInfo,
115  Double maxMemoryInMB);
116 
117  // Copy constructor (reference semantics).
118  TempImage (const TempImage<T>& other);
119 
120  // Destructor
122 
123  // Assignment operator (reference semantics).
125 
126  // Make a copy of the object (reference semantics).
127  virtual ImageInterface<T>* cloneII() const;
128 
129  // Get the image type (returns name of derived class).
130  virtual String imageType() const;
131 
132  // Is the TempImage paged to disk?
133  virtual Bool isPaged() const;
134 
135  // Can the lattice data be referenced as an array section?
136  virtual Bool canReferenceArray() const;
137 
138  // Is the TempImage writable?
139  virtual Bool isWritable() const;
140 
141  // Set the default pixelmask to the mask with the given name
142  // (which has to exist in the "masks" group).
143  // If the image table is writable, the setting is persistent by writing
144  // the name as a keyword.
145  // If the given regionName is the empty string,
146  // the default pixelmask is unset.
147  virtual void setDefaultMask (const String& maskName);
148 
149  // Delete the pixel mask attached to the TempImage.
150  // Does nothing if there isn't one
151  void removeMask()
152  { setDefaultMask (""); }
153 
154  // Use the mask as specified.
155  // If a mask was already in use, it is replaced by the new one.
156  virtual void useMask (MaskSpecifier = MaskSpecifier());
157 
158  // Remove a region/mask belonging to the image from the given group
159  // (which can be Any).
160  // If a mask removed is the default mask, the image gets unmasked.
161  // <br>Optionally an exception is thrown if the region does not exist.
162  virtual void removeRegion (const String& name,
164  Bool throwIfUnknown = True);
165 
166  // Attach a mask to the TempImage.
167  // It replaces a probably already attached mask.
168  // It has to have the same shape as the image.
169  virtual void attachMask (const Lattice<Bool>& mask);
170 
171  // It a mask attached to the image?
172  virtual Bool isMasked() const;
173 
174  // Does the image object use a pixelmask?
175  // This is similar to <src>isMasked()</src>.
176  virtual Bool hasPixelMask() const;
177 
178  // Get access to the pixelmask used.
179  // An exception is thrown if the image does not use a pixelmask.
180  // <group>
181  virtual const Lattice<Bool>& pixelMask() const;
183  // </group>
184 
185  // Get a section of the mask.
186  // It throws an exception if there is no mask.
187  virtual Bool doGetMaskSlice (Array<Bool>& buffer, const Slicer& section);
188 
189  // Flush the data.
190  virtual void flush();
191 
192  // Close the TempImage temporarily (if it is paged to disk).
193  // Note that a possible mask is not closed.
194  // It'll be reopened automatically when needed or when
195  // <src>reopen</src> is called explicitly.
196  virtual void tempClose();
197 
198  // If needed, reopen a temporarily closed TempLattice.
199  virtual void reopen();
200 
201  // Function which changes the shape of the image (N.B. the data is thrown
202  // away - the Image will be filled with nonsense afterwards)
203  virtual void resize (const TiledShape& newShape);
204 
205  // Return the name of the current TempImage object.
206  // It is always "Temporary_Image"
207  virtual String name (Bool stripPath=False) const;
208 
209  // Return the shape of the image
210  virtual IPosition shape() const;
211 
212  // Function which sets all of the elements in the Lattice to a value.
213  virtual void set (const T& value);
214 
215  // Replace every element, x, of the lattice with the result of f(x).
216  // You must pass in the address of the function -- so the function
217  // must be declared and defined in the scope of your program.
218  // Both versions of apply require a function that accepts a single
219  // argument of type T (the Lattice template actual type) and returns
220  // a result of the same type. The first apply expects a function with
221  // an argument passed by value; the second expects the argument to
222  // be passed by const reference. The first form ought to run faster
223  // for the built-in types, which may be an issue for large images
224  // stored in memory, where disk access is not an issue.
225  // <group>
226  virtual void apply (T (*function)(T));
227  virtual void apply (T (*function)(const T&));
228  virtual void apply (const Functional<T,T>& function);
229  // </group>
230 
231  // Get or put a single pixel.
232  // Note that the function operator () can also be used to get a pixel.
233  // <group>
234  virtual T getAt (const IPosition& where) const;
235  virtual void putAt (const T& value, const IPosition& where);
236  // </group>
237 
238  // This is the implementations of the letters for the envelope Iterator
239  // class <note> Not for public use </note>
241  (const LatticeNavigator& navigator,
242  Bool useRef) const;
243 
244  // Returns the maximum recommended number of pixels for a cursor.
245  // This is the number of pixels in a tile.
246  virtual uInt advisedMaxPixels() const;
247 
248  // Help the user pick a cursor for most efficient access.
249  virtual IPosition doNiceCursorShape (uInt maxPixels) const;
250 
251  // Maximum size - not necessarily all used. In pixels.
252  virtual uInt maximumCacheSize() const;
253 
254  // Set the maximum (allowed) cache size as indicated.
255  virtual void setMaximumCacheSize (uInt howManyPixels);
256 
257  // Set the cache size as to "fit" the indicated path.
258  virtual void setCacheSizeFromPath (const IPosition& sliceShape,
259  const IPosition& windowStart,
260  const IPosition& windowLength,
261  const IPosition& axisPath);
262 
263  // Set the actual cache size for this Array to be be big enough for the
264  // indicated number of tiles. This cache is not shared with PagedArrays
265  // in other rows and is always clipped to be less than the maximum value
266  // set using the setMaximumCacheSize member function.
267  // tiles. Tiles are cached using a first in first out algorithm.
268  virtual void setCacheSizeInTiles (uInt howManyTiles);
269 
270  // Clears and frees up the caches, but the maximum allowed cache size is
271  // unchanged from when setCacheSize was called
272  virtual void clearCache();
273 
274  // Report on cache success.
275  virtual void showCacheStatistics (ostream& os) const;
276 
277  // Check for symmetry in data members.
278  virtual Bool ok() const;
279 
280 protected:
281  // Get the region used (it always returns 0).
282  virtual const LatticeRegion* getRegionPtr() const;
283 
284  // Function which extracts an array from the map.
285  virtual Bool doGetSlice (Array<T>& buffer, const Slicer& theSlice);
286 
287  // Function to replace the values in the map with soureBuffer.
288  virtual void doPutSlice (const Array<T>& sourceBuffer,
289  const IPosition& where,
290  const IPosition& stride);
291 
292 
293 private:
295  void applyMask (const String& maskName);
296 
299 
300  //# Make members of parent class known.
301 public:
308 protected:
310 };
311 
312 //# Declare extern templates for often used types.
313  extern template class TempImage<Float>;
314  extern template class TempImage<Complex>;
315 
316 } //# NAMESPACE CASACORE - END
317 
318 #ifndef CASACORE_NO_AUTO_TEMPLATES
319 #include <casacore/images/Images/TempImage.tcc>
320 #endif //# CASACORE_NO_AUTO_TEMPLATES
321 #endif
GroupType
Define the possible group types (regions or masks).
Definition: RegionHandler.h:99
String: the storage and methods of handling collections of characters.
Definition: String.h:225
virtual const LatticeRegion * getRegionPtr() const
Get the region used (it always returns 0).
virtual void removeRegion(const String &name, RegionHandler::GroupType=RegionHandler::Any, Bool throwIfUnknown=True)
Remove a region/mask belonging to the image from the given group (which can be Any).
~TempImage()
Destructor.
virtual void flush()
Flush the data.
virtual void setMaximumCacheSize(uInt howManyPixels)
Set the maximum (allowed) cache size as indicated.
virtual String imageType() const
Get the image type (returns name of derived class).
TempImage()
The default constructor creates an empty image.
virtual void set(const T &value)
Function which sets all of the elements in the Lattice to a value.
TempLattice< T > * mapPtr_p
Definition: TempImage.h:297
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &theSlice)
Function which extracts an array from the map.
virtual T getAt(const IPosition &where) const
Get or put a single pixel.
virtual void reopen()
If needed, reopen a temporarily closed TempLattice.
void removeMask()
Delete the pixel mask attached to the TempImage.
Definition: TempImage.h:151
virtual void attachMask(const Lattice< Bool > &mask)
Attach a mask to the TempImage.
virtual LatticeIterInterface< T > * makeIter(const LatticeNavigator &navigator, Bool useRef) const
This is the implementations of the letters for the envelope Iterator class Note: Not for public use
virtual void setCacheSizeFromPath(const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath)
Set the cache size as to "fit" the indicated path.
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Function to replace the values in the map with soureBuffer.
void applyMaskSpecifier(const MaskSpecifier &)
virtual Bool canReferenceArray() const
Can the lattice data be referenced as an array section?
virtual uInt advisedMaxPixels() const
Returns the maximum recommended number of pixels for a cursor.
virtual void useMask(MaskSpecifier=MaskSpecifier())
Use the mask as specified.
virtual void putAt(const T &value, const IPosition &where)
Put the value of a single element.
virtual Bool doGetMaskSlice(Array< Bool > &buffer, const Slicer &section)
Get a section of the mask.
virtual uInt maximumCacheSize() const
Maximum size - not necessarily all used.
virtual const Lattice< Bool > & pixelMask() const
Get access to the pixelmask used.
TempImage(const TempImage< T > &other)
Copy constructor (reference semantics).
virtual void apply(const Functional< T, T > &function)
virtual void apply(T(*function)(const T &))
virtual Bool isMasked() const
It a mask attached to the image?
virtual void setCacheSizeInTiles(uInt howManyTiles)
Set the actual cache size for this Array to be be big enough for the indicated number of tiles.
virtual Lattice< Bool > & pixelMask()
virtual Bool isWritable() const
Is the TempImage writable?
virtual void clearCache()
Clears and frees up the caches, but the maximum allowed cache size is unchanged from when setCacheSiz...
virtual void apply(T(*function)(T))
Replace every element, x, of the lattice with the result of f(x).
virtual Bool ok() const
Check for symmetry in data members.
virtual Bool hasPixelMask() const
Does the image object use a pixelmask? This is similar to isMasked().
virtual String name(Bool stripPath=False) const
Return the name of the current TempImage object.
virtual IPosition shape() const
Return the shape of the image.
virtual void showCacheStatistics(ostream &os) const
Report on cache success.
TempImage(const TiledShape &mapShape, const CoordinateSystem &coordinateInfo, Double maxMemoryInMB)
Lattice< Bool > * maskPtr_p
Definition: TempImage.h:298
virtual void resize(const TiledShape &newShape)
Function which changes the shape of the image (N.B.
virtual ImageInterface< T > * cloneII() const
Make a copy of the object (reference semantics).
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Help the user pick a cursor for most efficient access.
virtual Bool isPaged() const
Is the TempImage paged to disk?
TempImage(const TiledShape &mapShape, const CoordinateSystem &coordinateInfo, Int maxMemoryInMB=-1)
Construct a temporary Image from shape and coordinate information.
virtual void tempClose()
Close the TempImage temporarily (if it is paged to disk).
TempImage< T > & operator=(const TempImage< T > &other)
Assignment operator (reference semantics).
void applyMask(const String &maskName)
virtual void setDefaultMask(const String &maskName)
Set the default pixelmask to the mask with the given name (which has to exist in the "masks" group).
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
unsigned int uInt
Definition: aipstype.h:51
LatticeExprNode mask(const LatticeExprNode &expr)
This function returns the mask of the given expression.
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
const Bool True
Definition: aipstype.h:43
double Double
Definition: aipstype.h:55