casacore
Loading...
Searching...
No Matches
ImageExprParse.h
Go to the documentation of this file.
1//# ImageExprParse.h: Classes to hold results from image expression parser
2//# Copyright (C) 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 IMAGES_IMAGEEXPRPARSE_H
29#define IMAGES_IMAGEEXPRPARSE_H
30
31
32//# Includes
33#include <casacore/casa/aips.h>
34#include <casacore/lattices/LEL/LatticeExpr.h>
35#include <casacore/casa/BasicSL/Complex.h>
36#include <casacore/casa/BasicSL/String.h>
37#include <casacore/casa/Utilities/DataType.h>
38#include <casacore/casa/stdvector.h>
39#include <casacore/casa/Utilities/CountedPtr.h>
40#include <casacore/casa/HDF5/HDF5File.h>
41
42namespace casacore { //# NAMESPACE CASACORE - BEGIN
43
44//# Forward Declarations
45template<class T> class Block;
46template<class T> class PtrBlock;
47class ImageRegion;
48class Table;
49class Slice;
50
51
52// <summary>
53// Class to hold values from image expression parser
54// </summary>
55
56// <use visibility=export>
57
58// <reviewed reviewer="" date="" tests="">
59// </reviewed>
60
61// <prerequisite>
62//# Classes you should understand before using this one.
63// <li> <linkto class=LatticeExpr>LatticeExpr</linkto>
64// </prerequisite>
65
66// <etymology>
67// ImageExprParse is the class used to parse an image expression command.
68// </etymology>
69
70// <synopsis>
71// ImageExprParse is used by the parser of image expression statements.
72// The parser is written in Bison and Flex in files ImageExprGram.y and .l.
73// The statements in there use the routines in this file to act
74// upon a reduced rule.
75// <p>
76// The main function (and the only function to be used by a user) is the
77// static function ImageExprParse::command which parses an expression command.
78// It returns a <linkto class=LatticeExprNode>LatticeExprNode</linkto>
79// object containing the expression represented as a tree.
80// The object can be used as a <src>Lattice(Expr)<T></src> in other operations.
81// <p>
82// The syntax of the command is similar to that of expressions in C++.
83// E.g.
84// <srcblock>
85// min(img1, img2) + sin(img3)
86// </srcblock>
87// The following items can be used in an expression:
88// <ul>
89// <li> Binary operators +, -, *, /, % (modulo), and ^ (power).
90// <li> Unary operators + and -.
91// <li> Comparison operators ==, >, >=, <, <=, and !=.
92// <li> Logical operators &&, ||, and !.
93// <li> Constant single and double precision values.
94// <br>No exponent or exponent "e" results in single precision (Float),
95// while "d" results in double precision (Double).
96// <li> The imaginary part of a complex value can be given by the suffix "i".
97// A full complex number can be given by addition. E.g. "3+4i".
98// The complex is single (Complex) or double (DComplex) precision
99// depending on the constituting parts.
100// <li> The special constants pi and e can be given as a double precision
101// value by means of the functions pi() and e().
102// <li> Boolean constants T and F can be given.
103// <li> A lot of functions are available.
104// They are the same as the ones supported by class
105// <linkto class=LatticeExprNode>LatticeExprNode</linkto>.
106// <li> Explicit conversion functions float, double, complex and dcomplex
107// are available. Conversions are automatically done where needed,
108// but for performance reasons it may sometimes be better to do
109// explicit conversions. See also below in the first example.
110// <li> An image can to be given using its file name. The file name
111// can contain environment variables and user home directories
112// using the standard UNIX syntax $ENVVAR and ~username.
113// There are 3 ways to specify a file name:
114// <ol>
115// <li> When the name contains no other special characters than
116// $, ~, and . it can be given as such.
117// <li> Backslashes can be used to escape individual special characters.
118// <li> The full name can be enclosed in quotes (single or double)
119// to escape the entire name. Adjacent quoted parts
120// are combined to one name, which can be used to use quotes
121// in the file name.
122// </ol>
123// Note that escaping has to be used too for the file name
124// T or F (otherwise it is the boolean constant).
125// E.g.
126// <srcblock>
127// image.data
128// "~noordam/data/image.data"
129// "~/image.data"
130// "$HOME/image.data"
131// $HOME\/image.data
132// "ab'c"'d"e' results in ab'cd"e
133// </srcblock>
134// Only input images with data type Float and Complex are supported,
135// because those data types are the only ones used so far.
136// Support of Bool, Double, and DComplex is very simple to build in.
137// The resulting lattice can be of type Bool, Float, Double,
138// Complex, and DComplex.
139// <li> An image can also be given by means of the <src>$n</src> notation,
140// where <src>n</src> is the sequence number in the
141// <src>tempLattices</src> argument given to the <src>command</src>
142// function. Note that the sequence numbers start counting at 1
143// (to be compliant with glish indexing).
144// <br>It can, for instance, be used to use non-persistent lattices
145// in an expression.
146// </ul>
147// When the expression is parsed, it is checked if the images and lattices
148// involved have conforming shapes and coordinates. Note, however, that
149// some functions (e.g. mean) reduce an image to a scalar. Such an image
150// can have a different shape and coordinates.
151// <p>
152// The data types of the images and constants involved can be different.
153// The data type of a subexpression is the common data type (e.g.
154// Float and Double result in Double; Complex and Double result in DComplex).
155// Automatic implicit conversions are done where needed. However, for
156// performance reasons it may sometimes be better to convert explicitly.
157// See below in the first example.
158// <p>
159// The expression evaluator (which is not part of the parser) evaluates
160// the expression in chunks to avoid having to keep large temporary
161// results. A scalar subexpression is evaluated only once to avoid
162// unnecessary (possibly expensive) calculations.
163// <p>
164// Some examples:
165// <dl>
166// <dt> <src> img1 + min(float(pi()), mean(img2)) </src>
167// <dd> Suppose img1 and img2 are images with single precision data.
168// They do not need to have conforming shapes and coordinates,
169// because only the mean of img2 is used.
170// <br>Note that pi is explicitly converted to single precision,
171// because pi() results in a Double. If that was not done,
172// the expression result would be a Double with the effect that
173// all data of img1 had to be converted to Double.
174// <dt> <src> min(img1, (min(img1)+max(img1))/2) </src>
175// <dd> This example shows that there are 2 min functions. One with a
176// single argument returning the minimum value of that image.
177// The other with 2 arguments returning a lattice containing
178// img1 data clipped at the value of the 2nd argument.
179// </dl>
180// </synopsis>
181
182// <example>
183// <srcblock>
184// LatticeExpr<Double> expr ("a + sin(b)");
185// ArrayLattice<Double> arr(expr.shape());
186// arr.copyData (expr);
187// </srcblock>
188// Line 1 creates a LatticeExpr object for the given expression. Note that
189// <src>a</src> and <src>b</src> are names of lattice files (e.g. PagedImage).
190// <br> Line 2 creates an ArrayLattice with the same shape as the expression
191// (which is the shape of lattice a (and b)).
192// <br> Line 3 copies the result of the expression to the ArrayLattice.
193// </example>
194
195// <motivation>
196// It is necessary to be able to give an image expression command in ASCII.
197// This can be used in glish to operate on lattices/images.
198// </motivation>
199
200//# <todo asof="$DATE:$">
201//# A List of bugs, limitations, extensions or planned refinements.
202//# </todo>
203
204
206{
207public:
208
209 // Parse the given command.
210 // It will open all lattices needed.
211 // It returns the resulting image expression.
212 // <br>The <src>tempLattices/tempRegions</src> arguments make it possible
213 // to use temporary lattices/images and regions in the expression by means
214 // of the <src>$n</src> notation.
215 // <br> If a directory name is given, it is used instead of the working
216 // directory for relative file names.
217 // <group>
218 static LatticeExprNode command (const String& str,
219 const String& dirName = String());
220 static LatticeExprNode command (const String& str,
221 const Block<LatticeExprNode>& tempLattices,
222 const PtrBlock<const ImageRegion*>& tempRegions,
223 const String& dirName = String());
224 // </group>
225
226 // Construct a literal object for the given type.
227 // <group>
232 ImageExprParse (const Complex& value);
233 ImageExprParse (const DComplex& value);
236 // </group>
237
238 // Make a LatticeExprNode for a function.
239 // <group>
243 const LatticeExprNode& arg2) const;
245 const LatticeExprNode& arg2,
246 const LatticeExprNode& arg3) const;
247 // </group>
248
249 // Make a LatticeExprNode object for the lattice or region name.
251
252 // Make a LatticeExprNode object for the name of constant, lattice,
253 // or region.
255
256 // Make a LatticeExprNode object for the temporary region number.
258
259 // Make a LatticeExprNode object for the literal value.
261
262 // Make a Slice object from 1-3 literals.
263 // <group>
264 static Slice* makeSlice (const ImageExprParse& start);
265 static Slice* makeSlice (const ImageExprParse& start,
266 const ImageExprParse& end);
267 static Slice* makeSlice (const ImageExprParse& start,
268 const ImageExprParse& end,
269 const ImageExprParse& incr);
270 // </group>
271
272 // Make a node for the INDEXIN function.
274 const vector<Slice>& slices);
275
276 // Make an array from a value list.
278 (const Block<LatticeExprNode>& values);
279
280 // Make an IPosition containing the binning values.
281 static IPosition makeBinning (const LatticeExprNode& values);
282
283 // Get the names of the images used in the expression.
284 static const vector<String>& getImageNames()
285 { return theirNames; }
286
287 // Set the static node object (used by the .y file).
288 static void setNode (const LatticeExprNode& node)
289 { theirNode = node; }
290
291 // Keep track of the nodes allocated while parsing the expression.
292 // <group>
293 static void addNode (LatticeExprNode* node);
294 static void addNode (ImageExprParse* node);
295 static void deleteNodes();
296 // </group>
297
298 // A function to test addDir. It first sets the directory.
299 static String setAddDir (const String& dirName, const String& fileName);
300
301private:
302 // If a directory was given, prepend it to the file name if relative.
303 static String addDir (const String& fileName);
304
305 // Try if the name represent a lattice or image.
306 // Return False if not.
307 Bool tryLatticeNode (LatticeExprNode& node, const String& name) const;
308
309 // Make the node from the image name and a mask name.
310 // The mask name can be NOMASK (case insensitive) meaning that no mask
311 // is applied to the image.
313 const String& mask) const;
314
315 // Callback function for RegionHandlerTable to get the table to be used.
316 static Table& getRegionTable (void*, Bool);
317
318 // Callback function for RegionHandlerHDF5 to get the file to be used.
319 static const CountedPtr<HDF5File>& getRegionHDF5 (void*);
320
321 //# A 'global' node object to hold the resulting expression.
323
324 //# The names of the images used in the expression.
325 //# and the level of nesting.
326 static vector<String> theirNames;
328
329 DataType itsType;
330 Bool itsBval; //# boolean literal
331 Int itsIval; //# integer literal
332 Float itsFval; //# Float literal
333 Double itsDval; //# Double literal
334 Complex itsCval; //# Complex literal
335 DComplex itsDCval; //# DComplex literal
336 String itsSval; //# lattice name; function name
337};
338
339
340} //# NAMESPACE CASACORE - END
341
342#endif
simple 1-D array
Definition Block.h:200
Referenced counted pointer for constant data.
Definition CountedPtr.h:81
static String setAddDir(const String &dirName, const String &fileName)
A function to test addDir.
LatticeExprNode makeLRNode() const
Make a LatticeExprNode object for the lattice or region name.
ImageExprParse(Double value)
LatticeExprNode makeLiteralNode() const
Make a LatticeExprNode object for the literal value.
LatticeExprNode makeFuncNode(const LatticeExprNode &arg1, const LatticeExprNode &arg2) const
static Slice * makeSlice(const ImageExprParse &start)
Make a Slice object from 1-3 literals.
static const CountedPtr< HDF5File > & getRegionHDF5(void *)
Callback function for RegionHandlerHDF5 to get the file to be used.
static LatticeExprNode theirNode
static LatticeExprNode makeIndexinNode(const LatticeExprNode &axis, const vector< Slice > &slices)
Make a node for the INDEXIN function.
static LatticeExprNode command(const String &str, const Block< LatticeExprNode > &tempLattices, const PtrBlock< const ImageRegion * > &tempRegions, const String &dirName=String())
static Table & getRegionTable(void *, Bool)
Callback function for RegionHandlerTable to get the table to be used.
static IPosition makeBinning(const LatticeExprNode &values)
Make an IPosition containing the binning values.
LatticeExprNode makeFuncNode(const LatticeExprNode &arg1, const LatticeExprNode &arg2, const LatticeExprNode &arg3) const
LatticeExprNode makeImageNode(const String &name, const String &mask) const
Make the node from the image name and a mask name.
ImageExprParse(const Complex &value)
static Slice * makeSlice(const ImageExprParse &start, const ImageExprParse &end, const ImageExprParse &incr)
ImageExprParse(const String &value)
LatticeExprNode makeRegionNode() const
Make a LatticeExprNode object for the temporary region number.
ImageExprParse(const Char *value)
static Slice * makeSlice(const ImageExprParse &start, const ImageExprParse &end)
static void deleteNodes()
Bool tryLatticeNode(LatticeExprNode &node, const String &name) const
Try if the name represent a lattice or image.
ImageExprParse(Bool value)
Construct a literal object for the given type.
static const vector< String > & getImageNames()
Get the names of the images used in the expression.
static LatticeExprNode makeValueList(const Block< LatticeExprNode > &values)
Make an array from a value list.
static vector< String > theirNames
ImageExprParse(Float value)
ImageExprParse(const DComplex &value)
LatticeExprNode makeFuncNode() const
Make a LatticeExprNode for a function.
static String addDir(const String &fileName)
If a directory was given, prepend it to the file name if relative.
static void addNode(LatticeExprNode *node)
Keep track of the nodes allocated while parsing the expression.
static void setNode(const LatticeExprNode &node)
Set the static node object (used by the.y file).
LatticeExprNode makeLitLRNode() const
Make a LatticeExprNode object for the name of constant, lattice, or region.
static LatticeExprNode command(const String &str, const String &dirName=String())
Parse the given command.
static void addNode(ImageExprParse *node)
LatticeExprNode makeFuncNode(const LatticeExprNode &arg1) const
A drop-in replacement for Block<T*>.
Definition Block.h:814
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
LatticeExprNode mask(const LatticeExprNode &expr)
This function returns the mask of the given expression.
float Float
Definition aipstype.h:54
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.
double Double
Definition aipstype.h:55
char Char
Definition aipstype.h:46