casacore
ImageExpr.h
Go to the documentation of this file.
1 //# ImageExpr.h: contains expressions involving images
2 //# Copyright (C) 1994,1995,1996,1997,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_IMAGEEXPR_H
29 #define IMAGES_IMAGEEXPR_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/Arrays/ArrayFwd.h>
35 #include <casacore/images/Images/ImageInterface.h>
36 #include <casacore/lattices/LEL/LatticeExpr.h>
37 #include <casacore/casa/Containers/Record.h>
38 #include <casacore/casa/Quanta/Unit.h>
39 
40 namespace casacore { //# NAMESPACE CASACORE - BEGIN
41 
42 //# Forward Declarations
43 class JsonKVMap;
44 class IPosition;
45 class Slicer;
46 class LatticeNavigator;
47 template <class T> class LatticeIterInterface;
48 class String;
49 
50 
51 // <summary>
52 // Hold mathematical expressions involving ImageInterface objects
53 // </summary>
54 //
55 // <use visibility=export>
56 //
57 // <reviewed reviewer="" date="" tests="tImageExpr.cc">
58 // </reviewed>
59 //
60 // <prerequisite>
61 // <li> LatticeExpr
62 // <li> ImageInterface
63 // </prerequisite>
64 //
65 // <etymology>
66 // This class holds a LatticeExpr object but inherits from
67 // ImageInterface hence ImageExpr
68 // </etymology>
69 //
70 // <synopsis>
71 // An ImageExpr object holds a LatticeExpr object which can be used
72 // to evaluate mathematical expressions involving Lattices. ImageExpr
73 // exists so that direct manipulation of LatticeExpr objects by methods
74 // expecting an ImageInterface, rather than a Lattice can occur.
75 //
76 // The ImageExpr object is constructed from a LatticeExpr object, but
77 // only if the latter has true Coordinates associated with it.
78 // The ImageExpr object is not writable, so the ImageExpr object
79 // functions like a read only ImageInterface.
80 // </synopsis>
81 //
82 // <example>
83 // <srcblock>
84 // PagedImage<Float> a("imageB"); // Open PagedImages
85 // PagedImage<Float> b("imageB");
86 //
87 // LatticeExprNode node(a+b); // Create ImageExpr
88 // LatticeExpr<Float> lExpr(node);
89 // ImageExpr<Float> iExpr(lExpr);
90 //
91 // LogOrigin or("imageImpl", "main()", WHERE); // Create statistics object
92 // LogIO logger(or);
93 // ImageStatistics<Float> stats(iExpr, logger);
94 // Bool ok = stats.display(); // Display statistics
95 //
96 // </srcblock>
97 // The ImageExpr object is evaluated during the call to
98 // <src>stats.dislay()</src>. Previously, the expression tree
99 // has been constructed, but not evaluated.
100 // </example>
101 //
102 // <motivation>
103 // This enables one to evaluate expressions but not to have to write them
104 // out to an output image.
105 // </motivation>
106 //
107 // <todo asof="1998/02/09">
108 // </todo>
109 
110 
111 template <class T> class ImageExpr: public ImageInterface<T>
112 {
113 public:
114  // The default constructor
116 
117  // Construct an ImageExpr from a LatticeExpr.
118  // The expr given should be the original expression string.
119  // The fileName argument is meant for ImageOpener.
120  // The coordinates are taken from the expression, usually the first image.
121  // An exception is thrown if the expression has no coordinates.
122  ImageExpr(const LatticeExpr<T>& latticeExpr, const String& expr,
123  const String& fileName = String());
124  ImageExpr(const LatticeExpr<T>& latticeExpr, const String& expr,
125  const String& fileName, const JsonKVMap&);
126 
127  // Same as previous constructor, but the coordinates are taken from the
128  // given LELImageCoord object.
129  ImageExpr(const LatticeExpr<T>& latticeExpr,
130  const String& expr, const String& fileName,
131  const LELImageCoord& imCoord);
132 
133  // Copy constructor (reference semantics)
134  ImageExpr(const ImageExpr<T>& other);
135 
136  // Destructor does nothing
138 
139  // Assignment (reference semantics)
141 
142  // Make a copy of the object (reference semantics).
143  virtual ImageInterface<T>* cloneII() const;
144 
145  // Save the image in an AipsIO file with the given name.
146  // It can be opened by ImageOpener::openExpr.
147  virtual void save (const String& fileName) const;
148 
149  // Set the file name.
150  void setFileName (const String& name)
151  { fileName_p = name; }
152 
153  // Replace the miscinfo in the ImageExpr, which writes the image.expr file.
154  // It can fail if, e.g., the directory to write to is not writable.
155  virtual Bool setMiscInfo (const RecordInterface& newInfo);
156 
157  // Get the image type (returns name of derived class).
158  virtual String imageType() const;
159 
160  // Has the object really a mask?
161  virtual Bool isMasked() const;
162 
163  // Get the region used.
164  virtual const LatticeRegion* getRegionPtr() const;
165 
166  // return the shape of the ImageExpr
167  virtual IPosition shape() const;
168 
169  // Function which changes the shape of the ImageExpr.
170  // Throws an exception as ImageExpr is not writable.
171  virtual void resize(const TiledShape& newShape);
172 
173  // Do the actual get of the mask data.
174  // The return value is always False, thus the buffer does not reference
175  // another array.
176  virtual Bool doGetMaskSlice (Array<Bool>& buffer, const Slicer& section);
177 
178  // Do the actual get of the data.
179  virtual Bool doGetSlice (Array<T>& buffer, const Slicer& theSlice);
180 
181  // putSlice is not possible on an expression, so it throws an exception.
182  virtual void doPutSlice (const Array<T>& sourceBuffer,
183  const IPosition& where,
184  const IPosition& stride);
185 
186  // If the object is persistent, the file name is given.
187  // Otherwise it returns the expression string given in the constructor.
188  virtual String name (Bool stripPath=False) const;
189 
190  // Check class invariants.
191  virtual Bool ok() const;
192 
193  // These are the implementations of the LatticeIterator letters.
194  // <note> not for public use </note>
196  const LatticeNavigator& navigator,
197  Bool useRef) const;
198 
199  // Returns False, as the ImageExpr is not writable.
200  virtual Bool isWritable() const;
201 
202  // Is the lattice persistent and can it be loaded by other processes as well?
203  virtual Bool isPersistent() const;
204 
205  // Help the user pick a cursor for most efficient access if they only want
206  // pixel values and don't care about the order or dimension of the
207  // cursor.
208  virtual IPosition doNiceCursorShape (uInt maxPixels) const;
209 
210  // Handle the (un)locking and syncing.
211  // <group>
212  virtual Bool lock (FileLocker::LockType, uInt nattempts);
213  virtual void unlock();
215  virtual void resync();
216  virtual void tempClose();
217  virtual void reopen();
218  // </group>
219 
220  // Get the lattice expression.
221  const LatticeExpr<T>& expression() const
222  { return latticeExpr_p; }
223 
224 
225 private:
226  void init (const LatticeExpr<T>& latticeExpr, const String& expr,
227  const String& fileName, const JsonKVMap&);
228 
229  //# Data members
234 };
235 
236 
237 
238 
239 } //# NAMESPACE CASACORE - END
240 
241 #ifndef CASACORE_NO_AUTO_TEMPLATES
242 #include <casacore/images/Images/ImageExpr.tcc>
243 #endif //# CASACORE_NO_AUTO_TEMPLATES
244 #endif
LockType
Define the possible lock types.
Definition: FileLocker.h:95
virtual Bool hasLock(FileLocker::LockType) const
virtual String imageType() const
Get the image type (returns name of derived class).
virtual void tempClose()
Temporarily close the lattice.
virtual Bool isPersistent() const
Is the lattice persistent and can it be loaded by other processes as well?
ImageExpr()
The default constructor.
ImageExpr< T > & operator=(const ImageExpr< T > &other)
Assignment (reference semantics)
virtual LatticeIterInterface< T > * makeIter(const LatticeNavigator &navigator, Bool useRef) const
These are the implementations of the LatticeIterator letters.
virtual Bool ok() const
Check class invariants.
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Handle the (un)locking and syncing.
~ImageExpr()
Destructor does nothing.
virtual Bool doGetMaskSlice(Array< Bool > &buffer, const Slicer &section)
Do the actual get of the mask data.
ImageExpr(const LatticeExpr< T > &latticeExpr, const String &expr, const String &fileName, const JsonKVMap &)
ImageExpr(const LatticeExpr< T > &latticeExpr, const String &expr, const String &fileName=String())
Construct an ImageExpr from a LatticeExpr.
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Help the user pick a cursor for most efficient access if they only want pixel values and don't care a...
void setFileName(const String &name)
Set the file name.
Definition: ImageExpr.h:150
virtual void reopen()
Explicitly reopen the temporarily closed lattice.
LatticeExpr< T > latticeExpr_p
Definition: ImageExpr.h:230
virtual Bool isWritable() const
Returns False, as the ImageExpr is not writable.
virtual void unlock()
const LatticeExpr< T > & expression() const
Get the lattice expression.
Definition: ImageExpr.h:221
ImageExpr(const LatticeExpr< T > &latticeExpr, const String &expr, const String &fileName, const LELImageCoord &imCoord)
Same as previous constructor, but the coordinates are taken from the given LELImageCoord object.
virtual ImageInterface< T > * cloneII() const
Make a copy of the object (reference semantics).
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &theSlice)
Do the actual get of the data.
virtual void resync()
Resynchronize the Lattice object with the lattice file.
virtual const LatticeRegion * getRegionPtr() const
Get the region used.
virtual void resize(const TiledShape &newShape)
Function which changes the shape of the ImageExpr.
virtual String name(Bool stripPath=False) const
If the object is persistent, the file name is given.
void init(const LatticeExpr< T > &latticeExpr, const String &expr, const String &fileName, const JsonKVMap &)
virtual Bool setMiscInfo(const RecordInterface &newInfo)
Replace the miscinfo in the ImageExpr, which writes the image.expr file.
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
putSlice is not possible on an expression, so it throws an exception.
ImageExpr(const ImageExpr< T > &other)
Copy constructor (reference semantics)
virtual IPosition shape() const
return the shape of the ImageExpr
virtual void save(const String &fileName) const
Save the image in an AipsIO file with the given name.
virtual Bool isMasked() const
Has the object really a mask?
String: the storage and methods of handling collections of characters.
Definition: String.h:225
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
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42