casacore
DirectionEngine.h
Go to the documentation of this file.
1 //# DirectionEngine.h: Engine for TaQL UDF Direction conversions
2 //# Copyright (C) 2011
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 MEAS_DIRECTIONENGINE_H
29 #define MEAS_DIRECTIONENGINE_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include<casacore/meas/MeasUDF/MeasEngine.h>
34 #include <casacore/measures/Measures/MDirection.h>
35 #include <casacore/measures/Measures/MCDirection.h>
36 #include <casacore/measures/Measures/MeasConvert.h>
37 
38 namespace casacore {
39 
40  //# Forward declarations
41  class EpochEngine;
42  class PositionEngine;
43 
44 
45  // <summary>
46  // Engine for TaQL UDF Direction conversions
47  // </summary>
48 
49  // <use visibility=export>
50 
51  // <reviewed reviewer="" date="" tests="tMeas.cc">
52  // </reviewed>
53 
54  // <prerequisite>
55  //# Classes you should understand before using this one.
56  // <li> EngineBase
57  // </prerequisite>
58 
59  // <synopsis>
60  // DirectionEngine defines Engines (user defined functions) that can be
61  // used in TaQL to convert Measures for directions.
62  // In this way such derived values appear to be ordinary TaQL functions.
63  //
64  // In TaQL these functions can be called like:
65  // <srcblock>
66  // meas.dir (toref, directions, epochs, positions)
67  // meas.j2000 (directions, epochs, positions)
68  // meas.dircos (toref, directions, epochs, positions)
69  // meas.riset (directions, epochs, positions)
70  // </srcblock>
71  // The first two result in angles, the third in direction cosines, while
72  // the fourth returns the rise/set time of sources as datetimes.
73  // Note that the second form is a shorthand for
74  // <src>meas.dir('j2000', ...)</src>. There are more such functions.
75  // The exact number of arguments depends on how they are specified.
76  // <ul>
77  // <li> <src>toref</src> is a single constant string defining the
78  // reference frame to convert to. Note it should be omitted for
79  // the functions (e.g., meas.j2000) with an implicit destination
80  // reference frame.
81  // <li> <src>directions</src> is one or more directions which can be
82  // given in several ways.
83  // <ul>
84  // <li> An array of directions, each 2 angles or 3 directions cosines.
85  // It can be given as a single list or a multi-dim array. The choice
86  // between angles and direction cosines is based on the size of the
87  // first dimension. If divisible by 2, it is angles, by 3 is
88  // direction cosines, otherwise an error. Thus a list of 6 elements
89  // defines 3 directions with 2 angles each (default in radians).
90  // <br>It can be followed by a string defining the source
91  // reference frame. It defaults to 'J2000'.
92  // <li> If a single constant direction is used, it can be given as
93  // 2 (for angles) or 3 (for direction cosines) scalar values,
94  // followed by the optional source reference frame.
95  // <li> The name of a column in a table or a subset of it such as
96  // <src>DELAY_DIR[0,]</src>. Often this is a TableMeasures column
97  // which is recognized as such, also its source reference frame.
98  // If such a column is given as part of an expression, it will not
99  // be recognized as a TableMeasures column and its reference frame
100  // should be given.
101  // <li> As a list of (case-insensitive) names of known sources
102  // such as 'CasA' or 'SUN'.
103  // </ul>
104  // <li> <src>epochs</src> can be given as shown in class EpochEngine.
105  // <li> <src>positions</src> can be given as shown in class PositionEngine.
106  // </ul>
107  // Note that epochs and positions are only needed if required by the
108  // conversion from source reference frame to destination reference frame.
109  // For example, J2000 to/from APP needs them, but not J2000 to/from B1950.
110  //
111  // The result of the function is an array with shape [2|3,dir,epoch,pos]
112  // where the last 3 elements are the shapes of these arguments. They are
113  // omitted if all of them have length 1.
114  //
115  // Futhermore, it is possible to get the rise/set date/time of a source
116  // given the source direction, date and position on earth. These functions
117  // return data with type double and unit d (day).
118  // If the source is visible all day, the rise time is 0 and set time 1.
119  // If the source is not visible at all, the rise time is 1 and set time 0.
120  // For the sun and the moon it is possible to add a suffix to the name
121  // telling if and which edge and twilight should be used. For the sun and
122  // moon the default is -UR (the upper edge with refraction correction).
123  // </synopsis>
124 
125  // <example>
126  // <srcblock>
127  // // Get rise/set time of the upper edge of the sun in the coming month
128  // // at the WSRT site.
129  // meas.riseset ('SUN', date()+[0:31], 'WSRT')
130  // // Get the apparent coordinates of CasA for the given date and position.
131  // meas.dircos ('APP', 'CasA', 12mar2015, [52deg,5deg])
132  // // Get the J2000 coordinates (in degrees) of CygA.
133  // meas.j2000 ('cyga') deg
134  // </srcblock>
135  // </example>
136 
137  // <motivation>
138  // It makes it possible to easily handle measures in TaQL.
139  // </motivation>
140 
141  class DirectionEngine: public MeasEngine<MDirection>
142  {
143  public:
145 
146  virtual ~DirectionEngine();
147 
148  // Get the values.
149  // The first Bool tells if rise/set times have to be calculated.
150  // The second Bool tells if direction cosines have to be calculated.
152  Bool asDirCos);
153 
154  // Get the directions.
156 
157  // Handle the argument(s) giving the input directions and reference type.
158  // The direction can be a column in a table.
159  void handleDirection (const std::vector<TENShPtr>& args,
160  uInt& argnr, Bool riseSet, Bool asDirCos);
161 
162  // Set the MeasConvert object.
164 
165  // Set the possible epoch engine.
166  // It can be done only once.
167  void setEpochEngine (EpochEngine& engine);
168 
169  // Set the possible position engine.
170  // It can be done only once.
172 
173  private:
174  void handleScalars (const TENShPtr& e1, const TENShPtr& e2,
175  const TENShPtr& e3);
176  void handleNames (const TENShPtr& operand);
177  virtual void handleValues (TableExprNode& operand,
178  const TableExprId& id,
179  Array<MDirection>& directions);
180 
181  // Calucate the rise and set time of a source for a given position and
182  // epoch. Argument <src>h</src> defines the possible edge of sun/moon.
183  void calcRiseSet (const MDirection& dir,
184  const MPosition& pos,
185  const MEpoch& epoch,
186  double h,
187  double& rise, double& set);
188  int fillRiseSet (double epoch,
189  const MDirection& dir,
190  double lat,
191  double h,
192  const MEpoch& off,
193  double* rise, double* set);
194 
195  //# Data members.
196  MeasFrame itsFrame; //# frame used by converter
198  Vector<Double> itsH; //# diff for sun or moon
201  };
202 
203 } //end namespace
204 
205 #endif
void calcRiseSet(const MDirection &dir, const MPosition &pos, const MEpoch &epoch, double h, double &rise, double &set)
Calucate the rise and set time of a source for a given position and epoch.
void setEpochEngine(EpochEngine &engine)
Set the possible epoch engine.
void handleDirection(const std::vector< TENShPtr > &args, uInt &argnr, Bool riseSet, Bool asDirCos)
Handle the argument(s) giving the input directions and reference type.
MDirection::Convert itsConverter
PositionEngine * itsPositionEngine
void handleScalars(const TENShPtr &e1, const TENShPtr &e2, const TENShPtr &e3)
Array< MDirection > getDirections(const TableExprId &id)
Get the directions.
void setConverter(MDirection::Types toType)
Set the MeasConvert object.
Array< Double > getArrayDouble(const TableExprId &id, Bool riseSet, Bool asDirCos)
Get the values.
int fillRiseSet(double epoch, const MDirection &dir, double lat, double h, const MEpoch &off, double *rise, double *set)
void handleNames(const TENShPtr &operand)
void setPositionEngine(PositionEngine &engine)
Set the possible position engine.
virtual void handleValues(TableExprNode &operand, const TableExprId &id, Array< MDirection > &directions)
Let a derive class handle the values.
Types
Types of known MDirections Warning: The order defines the order in the translation matrix FromTo in ...
Definition: MDirection.h:188
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