casacore
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 
42 namespace casacore { //# NAMESPACE CASACORE - BEGIN
43 
44 //# Forward Declarations
45 template<class T> class Block;
46 template<class T> class PtrBlock;
47 class ImageRegion;
48 class Table;
49 class 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 {
207 public:
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>
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 
301 private:
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;
327  static Int theirLevel;
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.
static Slice * makeSlice(const ImageExprParse &start, const ImageExprParse &end)
LatticeExprNode makeFuncNode(const LatticeExprNode &arg1, const LatticeExprNode &arg2) const
static Table & getRegionTable(void *, Bool)
Callback function for RegionHandlerTable to get the table 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 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)
ImageExprParse(const String &value)
LatticeExprNode makeRegionNode() const
Make a LatticeExprNode object for the temporary region number.
ImageExprParse(const Char *value)
static void deleteNodes()
Bool tryLatticeNode(LatticeExprNode &node, const String &name) const
Try if the name represent a lattice or image.
static const vector< String > & getImageNames()
Get the names of the images used in the expression.
static const CountedPtr< HDF5File > & getRegionHDF5(void *)
Callback function for RegionHandlerHDF5 to get the file to be used.
ImageExprParse(Bool value)
Construct a literal object for the given type.
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 Slice * makeSlice(const ImageExprParse &start, const ImageExprParse &end, const ImageExprParse &incr)
static LatticeExprNode command(const String &str, const String &dirName=String())
Parse the given command.
static Slice * makeSlice(const ImageExprParse &start)
Make a Slice object from 1-3 literals.
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