casacore
Loading...
Searching...
No Matches
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
39namespace 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
97template<class T> class TempImage: public ImageInterface<T>
98{
99public:
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
152 { setDefaultMask (""); }
153
154 // Use the mask as specified.
155 // If a mask was already in use, it is replaced by the new one.
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
280protected:
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
293private:
295 void applyMask (const String& maskName);
296
299
300 //# Make members of parent class known.
301public:
302 using ImageInterface<T>::logger;
308protected:
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
void setCoordsMember(const CoordinateSystem &coords)
Set the coordinate system variable.
LoggerHolder & logger()
Get access to the LoggerHolder.
virtual String getDefaultMask() const
Get the name of the default pixelmask.
virtual ImageRegion * getImageRegionPtr(const String &name, RegionHandler::GroupType=RegionHandler::Any, Bool throwIfUnknown=True) const
Get a region/mask belonging to the image from the given group (which can be Any).
virtual Bool hasRegion(const String &regionName, RegionHandler::GroupType=RegionHandler::Any) const
Does the image have a region with the given name?
virtual Bool setCoordinateInfo(const CoordinateSystem &coords)
Functions to set or replace the coordinate information in the Image Returns False on failure,...
const CoordinateSystem & coordinates() const
GroupType
Define the possible group types (regions or masks).
String: the storage and methods of handling collections of characters.
Definition String.h:225
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.
virtual const LatticeRegion * getRegionPtr() const
Get the region used (it always returns 0).
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 void setCacheSizeFromPath(const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath)
Set the cache size as to "fit" the indicated path.
TempImage< T > & operator=(const TempImage< T > &other)
Assignment operator (reference semantics).
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 Lattice< Bool > & pixelMask()
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.
TempImage(const TempImage< T > &other)
Copy constructor (reference semantics).
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 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 ImageInterface< T > * cloneII() const
Make a copy of the object (reference semantics).
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 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 const Lattice< Bool > & pixelMask() const
Get access to the pixelmask used.
virtual void resize(const TiledShape &newShape)
Function which changes the shape of the image (N.B.
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).
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