casacore
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>
34#include <casacore/lattices/Lattices/MaskedLattice.h>
35#include <casacore/lattices/LEL/LatticeExprNode.h>
36#include <casacore/lattices/LRegions/LatticeRegion.h>
37#include <casacore/casa/Arrays/Slicer.h>
38#include <casacore/casa/Arrays/ArrayFwd.h>
39
40namespace casacore { //# NAMESPACE CASACORE - BEGIN
41
42//# Forward Declarations
43template <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
142template <class T> class LatticeExpr : public MaskedLattice<T>
143{
144public:
145
146 // Default constructor
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.
156 LatticeExpr (const LatticeExprNode& expr, const IPosition& latticeShape);
157
158 // Copy constructor (reference semantics)
160
161 // Destructor, does nothing
162 virtual ~LatticeExpr();
163
164 // Assignment (reference semantics)
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();
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.
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
232private:
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
244template<> 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
LockType
Define the possible lock types.
Definition: FileLocker.h:95
virtual void resync()
Resynchronize the Lattice object with the lattice file.
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 MaskedLattice< T > * cloneML() const
Make a copy of the derived object (reference semantics).
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 Bool doGetSlice(Array< T > &buffer, const Slicer &section)
Do the actual get of the data.
virtual void copyDataTo(Lattice< T > &to) const
Copy the data from this lattice to the given lattice.
LELArray< T > * lastChunkPtr_p
Definition: LatticeExpr.h:239
virtual ~LatticeExpr()
Destructor, does nothing.
virtual Bool isWritable() const
Returns False, as the LatticeExpr lattice is not writable.
LatticeExpr(const LatticeExpr< T > &other)
Copy constructor (reference semantics)
LatticeExpr(const LatticeExprNode &expr)
Constructor from an arbitrary LatticeExprNode expression object.
virtual LELCoordinates lelCoordinates() const
Returns the coordinates of the lattice expression.
LatticeExpr(const LatticeExprNode &expr, const IPosition &latticeShape)
LatticeExprNode expr_p
Definition: LatticeExpr.h:237
LatticeExpr< T > & operator=(const LatticeExpr< T > &other)
Assignment (reference semantics)
virtual Bool hasLock(FileLocker::LockType) const
virtual Bool isMasked() const
Has the object really a mask?
virtual IPosition shape() const
Returns the shape of the Lattice including all degenerate axes (i.e.
void init(const LatticeExprNode &expr)
Initialize the object from the expression.
virtual void handleMathTo(Lattice< T > &to, int oper) const
Handle the Math operators (+=, -=, *=, /=).
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Handle locking of the LatticeExpr which is delegated to all of its parts.
LatticeExpr()
Default constructor.
virtual const LatticeRegion * getRegionPtr() const
Get the region used (always returns 0).
virtual void unlock()
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42