casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
LatticeExpr.h
Go to the documentation of this file.
1 //# LatticeExpr.h: LatticeExpr.h
2 //# Copyright (C) 1997,1998,1999,2000,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 LATTICES_LATTICEEXPR_H
29 #define LATTICES_LATTICEEXPR_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
39 
40 namespace casacore { //# NAMESPACE CASACORE - BEGIN
41 
42 //# Forward Declarations
43 template <class T> class LELArray;
44 
45 
46 // <summary> Class to allow C++ expressions involving lattices </summary>
47 
48 // <use visibility=export>
49 
50 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
51 // </reviewed>
52 
53 // <prerequisite>
54 // <li> <linkto class="Lattice"> Lattice</linkto>
55 // <li> <linkto class="LatticeExprNode"> LatticeExprNode</linkto>
56 //
57 // </prerequisite>
58 //
59 // <etymology>
60 // The name is derived from the fact that this class provides
61 // an expression interface to the user which s/he may use to
62 // write C++ expressions involving Lattices.
63 // </etymology>
64 //
65 // <synopsis>
66 // This class provides an interface which allows the C++ programmer
67 // to enter expressions such as "sin(a)+b" where "a" and "b"
68 // are Lattices.
69 //
70 // This class is termed an envelope class, and inside it are the
71 // letter classes which do the real work. In reality, the letter
72 // classes are actually accessed via a bridging class called
73 // LatticeExprNode, which exists to handle type conversions.
74 // The letter classes iterate through the Lattices and evaluate the
75 // expression for each chunk of the iteration (usually a tile shape).
76 //
77 // It is in the LatticeExprNode class that all the available expression
78 // operations are defined, so you should look there to see what
79 // functionality is available.
80 //
81 // A description of the implementation details of these classes can
82 // be found in
83 // <a href="../notes/216.html">Note 216</a>
84 // </synopsis>
85 //
86 // <example>
87 // <srcblock>
88 // ArrayLattice<Float> f1(IPosition (2,nx,ny));
89 // ArrayLattice<Float> f2(IPosition (2,nx,ny));
90 // f2.set(2.0);
91 // f1.copyData(2*f2+f2);
92 // </srcblock>
93 //
94 // In this example, the values of the pixels in Lattice f1 are set
95 // to the values resulting from the expression "2*f2 + f2"
96 // I.e. the expression is evaluated for each pixel in the Lattices
97 //
98 // Note that :
99 // 1) the Lattice::copyData function is expecting a Lattice argument.
100 // 2) LatticeExpr inherits from Lattice and therefore a LatticeExpr
101 // object is a valid argument object type
102 // 3) The expression in the copyData call is automatically converted to
103 // a LatticeExprNode by the constructors and operators in LatticeExprNode
104 // 4) The LatticeExprNode object so created is automatically converted
105 // to a LatticeExpr by casting functions in LatticeExprNode.
106 // </example>
107 //
108 // <example>
109 // <srcblock>
110 // ArrayLattice<Float> f1(IPosition (2,nx,ny));
111 // ArrayLattice<Float> f2(IPosition (2,nx,ny));
112 // ArrayLattice<Double> d(IPosition (2,nx,ny));
113 // ArrayLattice<Complex> c(IPosition (2,nx,ny));
114 // ArrayLattice<Bool> b(IPosition (2,nx,ny));
115 //
116 // f2.set(1.0); d.set(2.0); c.set(Complex(2.0,3.0)); b.set(True);
117 // f1.copyData( (3.5*f2) + (cos(d)) - (10/min(d,f2)*(-abs(c))*ntrue(b)) - (C::pi) );
118 // </srcblock>
119 //
120 // In this rather silly example, we fill Lattice "f1" with the result of the
121 // expression. The expression shows the use of constants, unary operations,
122 // binary operations, 1D and 2D functions. It also shows how mixed types can
123 // be handled. The output Lattice is a Float, whereas mixed into the
124 // expression are subexpressions involving Float, Double, Complex and Bool
125 // Lattices.
126 //
127 // </example>
128 //
129 // <motivation>
130 // The Lattice expression classes enable the C++ programmer much simpler
131 // handling of mathematical expressions involving lattices. In addition,
132 // these classes provide the infrastructure on top of which we can build
133 // an image calculator for Glish users
134 // </motivation>
135 
136 // <todo asof="1997/01/15">
137 // <li> masks
138 // <li> regions
139 // </todo>
140 
141 
142 template <class T> class LatticeExpr : public MaskedLattice<T>
143 {
144 public:
145 
146  // Default constructor
147  LatticeExpr();
148 
149  // Constructor from an arbitrary LatticeExprNode expression object.
150  // An exception is thrown if the expression data type cannot be
151  // converted to the template data type.
152  // The shape argument is mandatory if the expression has no shape.
153  // If the expression has a shape and if shape is given, it is checked
154  // if they are equal.
155  LatticeExpr (const LatticeExprNode& expr);
156  LatticeExpr (const LatticeExprNode& expr, const IPosition& latticeShape);
157 
158  // Copy constructor (reference semantics)
159  LatticeExpr (const LatticeExpr<T>& other);
160 
161  // Destructor, does nothing
162  virtual ~LatticeExpr();
163 
164  // Assignment (reference semantics)
165  LatticeExpr<T>& operator=(const LatticeExpr<T>& other);
166 
167  // Make a copy of the derived object (reference semantics).
168  virtual MaskedLattice<T>* cloneML() const;
169 
170  // Has the object really a mask?
171  virtual Bool isMasked() const;
172 
173  // Get the region used (always returns 0).
174  virtual const LatticeRegion* getRegionPtr() const;
175 
176  // Returns False, as the LatticeExpr lattice is not writable.
177  virtual Bool isWritable() const;
178 
179  // Handle locking of the LatticeExpr which is delegated to all of its parts.
180  // <br>hasLock() is True if all parts of the expression return True.
181  // <br>It is strongly recommended to use class
182  // <linkto class=LatticeLocker>LatticeLocker</linkto> to
183  // handle lattice locking. It also contains a more detailed
184  // explanation of the locking process.
185  // <group>
186  virtual Bool lock (FileLocker::LockType, uInt nattempts);
187  virtual void unlock();
188  virtual Bool hasLock (FileLocker::LockType) const;
189  // </group>
190 
191  // Resynchronize the Lattice object with the lattice file.
192  // This function is only useful if no read-locking is used, ie.
193  // if the table lock option is UserNoReadLocking or AutoNoReadLocking.
194  // In that cases the table system does not acquire a read-lock, thus
195  // does not synchronize itself automatically.
196  // <br>By default the function does not do anything at all.
197  virtual void resync();
198 
199  // Returns the shape of the Lattice including all degenerate axes
200  // (i.e. axes with a length of one)
201  virtual IPosition shape() const;
202 
203  // Return the best cursor shape.
204  virtual IPosition doNiceCursorShape (uInt maxPixels) const;
205 
206  // Returns the coordinates of the lattice expression.
207  virtual LELCoordinates lelCoordinates() const;
208 
209  // Do the actual get of the data.
210  // The return value is always False, thus the buffer does not reference
211  // another array.
212  virtual Bool doGetSlice (Array<T>& buffer, const Slicer& section);
213 
214  // Do the actual get of the mask data.
215  // The return value is always False, thus the buffer does not reference
216  // another array.
217  virtual Bool doGetMaskSlice (Array<Bool>& buffer, const Slicer& section);
218 
219  // An expression is not writable so this functions throws an exception.
220  virtual void doPutSlice (const Array<T>& sourceBuffer,
221  const IPosition& where,
222  const IPosition& stride);
223 
224  // Copy the data from this lattice to the given lattice.
225  virtual void copyDataTo (Lattice<T>& to) const;
226 
227  // Handle the Math operators (+=, -=, *=, /=).
228  // They work similarly to copyData(To).
229  // However, they are not defined for Bool types, thus specialized below.
230  virtual void handleMathTo (Lattice<T>& to, int oper) const;
231 
232 private:
233  // Initialize the object from the expression.
234  void init (const LatticeExprNode& expr);
235 
236 
237  LatticeExprNode expr_p; //# its shape can be undefined
238  IPosition shape_p; //# this shape is always defined
241 };
242 
243 
244 template<> inline
246  { throwBoolMath(); }
247 
248 
249 
250 } //# NAMESPACE CASACORE - END
251 
252 #ifndef CASACORE_NO_AUTO_TEMPLATES
253 #include <casacore/lattices/LEL/LatticeExpr.tcc>
254 #endif //# CASACORE_NO_AUTO_TEMPLATES
255 #endif
A Vector of integers, for indexing into Array&lt;T&gt; objects.
Definition: IPosition.h:118
virtual Bool isWritable() const
Returns False, as the LatticeExpr lattice is not writable.
virtual Bool isMasked() const
Has the object really a mask?
This LEL class holds an array with a mask.
Definition: LatticeExpr.h:43
virtual void handleMathTo(Lattice< T > &to, int oper) const
Handle the Math operators (+=, -=, *=, /=).
virtual MaskedLattice< T > * cloneML() const
Make a copy of the derived object (reference semantics).
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Handle locking of the LatticeExpr which is delegated to all of its parts.
Envelope class to handle Lattice Coordinates in LEL.
virtual IPosition shape() const
Returns the shape of the Lattice including all degenerate axes (i.e.
virtual const LatticeRegion * getRegionPtr() const
Get the region used (always returns 0).
A templated, abstract base class for array-like objects with masks.
Definition: ImageConcat.h:46
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Return the best cursor shape.
virtual Bool doGetMaskSlice(Array< Bool > &buffer, const Slicer &section)
Do the actual get of the mask data.
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
An expression is not writable so this functions throws an exception.
virtual LELCoordinates lelCoordinates() const
Returns the coordinates of the lattice expression.
void init(const LatticeExprNode &expr)
Initialize the object from the expression.
A templated, abstract base class for array-like objects.
Definition: Functional.h:37
virtual void copyDataTo(Lattice< T > &to) const
Copy the data from this lattice to the given lattice.
LatticeExpr< T > & operator=(const LatticeExpr< T > &other)
Assignment (reference semantics)
LatticeExprNode expr_p
Definition: LatticeExpr.h:237
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &section)
Do the actual get of the data.
LELArray< T > * lastChunkPtr_p
Definition: LatticeExpr.h:239
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:288
LatticeExpr()
Default constructor.
Bridging class to allow C++ expressions involving lattices.
virtual void resync()
Resynchronize the Lattice object with the lattice file.
An optionally strided region in a Lattice.
Definition: LatticeRegion.h:74
virtual void unlock()
virtual ~LatticeExpr()
Destructor, does nothing.
LockType
Define the possible lock types.
Definition: FileLocker.h:95
virtual Bool hasLock(FileLocker::LockType) const
Class to allow C++ expressions involving lattices.
Definition: WCLELMask.h:47
unsigned int uInt
Definition: aipstype.h:51