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
casacore::CoordinateSystem
Interconvert pixel and world coordinates.
Definition: CoordinateSystem.h:218
casacore::ImageInterface
A base class for astronomical images.
Definition: ImageFITSConverter.h:48
casacore::Slicer
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:290
casacore::IPosition
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:120
casacore::TempImage::removeRegion
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).
casacore::TempImage::cloneII
virtual ImageInterface< T > * cloneII() const
Make a copy of the object (reference semantics).
casacore::RegionHandler::GroupType
GroupType
Define the possible group types (regions or masks).
Definition: RegionHandler.h:99
casacore::TempImage::hasPixelMask
virtual Bool hasPixelMask() const
Does the image object use a pixelmask? This is similar to isMasked().
casacore::TempImage::reopen
virtual void reopen()
If needed, reopen a temporarily closed TempLattice.
casacore::RegionHandler::Any
@ Any
Definition: RegionHandler.h:102
casacore::TempImage::maximumCacheSize
virtual uInt maximumCacheSize() const
Maximum size - not necessarily all used.
casacore::TempImage::set
virtual void set(const T &value)
Function which sets all of the elements in the Lattice to a value.
casacore::TempImage::imageType
virtual String imageType() const
Get the image type (returns name of derived class).
casacore::TempImage::maskPtr_p
Lattice< Bool > * maskPtr_p
Definition: TempImage.h:298
casacore::Functional
Map a domain object into a range object via operator().
Definition: Array.h:53
casacore::TempImage
Temporary astronomical images.
Definition: TempImage.h:98
casacore::TempImage::tempClose
virtual void tempClose()
Close the TempImage temporarily (if it is paged to disk).
casacore::TempImage::TempImage
TempImage(const TiledShape &mapShape, const CoordinateSystem &coordinateInfo, Int maxMemoryInMB=-1)
Construct a temporary Image from shape and coordinate information.
casacore::TempImage::setMaximumCacheSize
virtual void setMaximumCacheSize(uInt howManyPixels)
Set the maximum (allowed) cache size as indicated.
casacore::TempImage::setCacheSizeFromPath
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.
casacore::TempImage::isPaged
virtual Bool isPaged() const
Is the TempImage paged to disk?
casacore::TempImage::getAt
virtual T getAt(const IPosition &where) const
Get or put a single pixel.
casacore::TempImage::putAt
virtual void putAt(const T &value, const IPosition &where)
casacore::LatticeRegion
An optionally strided region in a Lattice.
Definition: LatticeRegion.h:75
casacore::TempImage::apply
virtual void apply(const Functional< T, T > &function)
casacore::TempImage::doGetSlice
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &theSlice)
Function which extracts an array from the map.
casacore::TempImage::applyMaskSpecifier
void applyMaskSpecifier(const MaskSpecifier &)
casacore::TempImage::doGetMaskSlice
virtual Bool doGetMaskSlice(Array< Bool > &buffer, const Slicer &section)
Get a section of the mask.
casacore::TempImage::makeIter
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
casacore::value
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
casacore::Double
double Double
Definition: aipstype.h:55
casacore::LatticeNavigator
Abstract base class to steer lattice iterators.
Definition: LatticeNavigator.h:182
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::TempImage::applyMask
void applyMask(const String &maskName)
casacore::TempImage::showCacheStatistics
virtual void showCacheStatistics(ostream &os) const
Report on cache success.
casacore::TempLattice
A Lattice that can be used for temporary storage.
Definition: LatticeCleaner.h:44
casacore::MaskSpecifier
Class to specify which mask to use in an image.
Definition: MaskSpecifier.h:70
casacore::Int
int Int
Definition: aipstype.h:50
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::TempImage::TempImage
TempImage(const TiledShape &mapShape, const CoordinateSystem &coordinateInfo, Double maxMemoryInMB)
casacore::True
const Bool True
Definition: aipstype.h:43
casacore::TempImage::apply
virtual void apply(T(*function)(T))
Replace every element, x, of the lattice with the result of f(x).
casacore::TempImage::doPutSlice
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Function to replace the values in the map with soureBuffer.
casacore::TempImage::~TempImage
~TempImage()
Destructor.
casacore::TempImage::pixelMask
virtual const Lattice< Bool > & pixelMask() const
Get access to the pixelmask used.
casacore::TempImage::canReferenceArray
virtual Bool canReferenceArray() const
Can the lattice data be referenced as an array section?
casacore::TempImage::mapPtr_p
TempLattice< T > * mapPtr_p
Definition: TempImage.h:297
casacore::TempImage::ok
virtual Bool ok() const
Check for symmetry in data members.
casacore::mask
LatticeExprNode mask(const LatticeExprNode &expr)
This function returns the mask of the given expression.
casacore::Lattice< Bool >
casacore::TempImage::advisedMaxPixels
virtual uInt advisedMaxPixels() const
Returns the maximum recommended number of pixels for a cursor.
casacore::Array< Bool >
casacore::TempImage::getRegionPtr
virtual const LatticeRegion * getRegionPtr() const
Get the region used (it always returns 0).
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::TempImage::pixelMask
virtual Lattice< Bool > & pixelMask()
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::TempImage::doNiceCursorShape
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Help the user pick a cursor for most efficient access.
casacore::TempImage::flush
virtual void flush()
Flush the data.
casacore::TempImage::isMasked
virtual Bool isMasked() const
It a mask attached to the image?
casacore::TempImage::isWritable
virtual Bool isWritable() const
Is the TempImage writable?
casacore::TempImage::setDefaultMask
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).
casacore::TempImage::name
virtual String name(Bool stripPath=False) const
Return the name of the current TempImage object.
casacore::TempImage::useMask
virtual void useMask(MaskSpecifier=MaskSpecifier())
Use the mask as specified.
casacore::TempImage::resize
virtual void resize(const TiledShape &newShape)
Function which changes the shape of the image (N.B.
casacore::TempImage::shape
virtual IPosition shape() const
Return the shape of the image.
casacore::TempImage::operator=
TempImage< T > & operator=(const TempImage< T > &other)
Assignment operator (reference semantics).
casacore::TempImage::TempImage
TempImage(const TempImage< T > &other)
Copy constructor (reference semantics).
casacore::TiledShape
Define the shape and tile shape.
Definition: TiledShape.h:100
casacore::TempImage::TempImage
TempImage()
The default constructor creates an empty image.
casacore::TempImage::setCacheSizeInTiles
virtual void setCacheSizeInTiles(uInt howManyTiles)
Set the actual cache size for this Array to be be big enough for the indicated number of tiles.
casacore::TempImage::attachMask
virtual void attachMask(const Lattice< Bool > &mask)
Attach a mask to the TempImage.
casacore::TempImage::apply
virtual void apply(T(*function)(const T &))
casacore::LatticeIterInterface
A base class for Lattice iterators.
Definition: ImageExpr.h:47
casacore::TempImage::removeMask
void removeMask()
Delete the pixel mask attached to the TempImage.
Definition: TempImage.h:151
casacore::TempImage::clearCache
virtual void clearCache()
Clears and frees up the caches, but the maximum allowed cache size is unchanged from when setCacheSiz...