casacore
UVWMachine.h
Go to the documentation of this file.
1 //# UVWMachine.h: Converts UVW coordinates between coordinate systems
2 //# Copyright (C) 1998,2001
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 #ifndef MEASURES_UVWMACHINE_H
28 #define MEASURES_UVWMACHINE_H
29 
30 //# Includes
31 #include <casacore/casa/aips.h>
32 #include <casacore/casa/Arrays/ArrayFwd.h>
33 #include <casacore/measures/Measures.h>
34 #include <casacore/measures/Measures/MCDirection.h>
35 #include <casacore/casa/Quanta/MVPosition.h>
36 #include <casacore/casa/Quanta/RotMatrix.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 //# Forward Declarations
41 class MeasFrame;
42 
43 // <summary> Converts UVW coordinates between coordinate systems </summary>
44 
45 // <use visibility=export>
46 
47 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tUVWMachine.cc" demos="">
48 // </reviewed>
49 
50 // <prerequisite>
51 // <li> <linkto class=MDirection>MDirection</linkto> class
52 // </prerequisite>
53 //
54 // <etymology>
55 // From UVW coordinates and machinery
56 // </etymology>
57 //
58 // <synopsis>
59 // The construction of a UVWMachine class object creates a machine that can
60 // convert UVW coordinates from one coordinate system to another. In addition
61 // it can also supply the phase rotation necessary to move to a new position.
62 //
63 // The constructors need an input
64 // <linkto class=MDirection>MDirection</linkto> to specify the input UVW
65 // coordinates reference direction and coordinate system.
66 // An EW flag can be specified to indicate the different type of UVW
67 // coordinates. I.e. projection along polar axis rather than towards
68 // observing direction (not implemented yet).
69 // A project flag, if set, will re-project the resulting UV plane onto the
70 // in-direction reference plane.
71 //
72 // The constructors also need an output coordinate system
73 // (<linkto class=MeasRef>MDirection::Ref</linkto>) or an output
74 // MDirection (including the reference coordinate system). The first case
75 // indicates that the real position on the sky does not change (only the
76 // coordinate system used); the second indicates that the UVW should be
77 // for a new position on the sky (in addition to maybe a different
78 // coordinate system). In the first case only the UVW coordinates will change,
79 // in the second the UVW positions will change, but also the phase of the
80 // observed data will have to change. For some conversions a reference
81 // <linkto class=MeasFrame>frame</linkto> is needed (to indicate e.g. the
82 // position or time). This frame can be part of one of the constructor
83 // references, but can also be specified separately in the constructor. A
84 // change in the frame parameter can be made outside the UVWMachine
85 // by e.g. <em>frame.reset(anMEpoch)</em>.
86 // <note role=caution>
87 // If the frame is changed by the user of the conversion machine, the
88 // machine has to be reinitialised before using it for output by using
89 // <tt>reCalculate()</tt>.
90 //
91 // Projection entails a rotation. For changes to a fixed frame (i.e. not
92 // changing with e.g. time), the rotation matrix is calculated only once. In
93 // other cases it has to be calculated per series of uvw conversions. The
94 // latter case can hence be time consuming.
95 // </note>
96 // <note role=tip>
97 // If either the input or output direction/reference specifies a planet, action
98 // is special. Planets are assumed to be in J2000 positions, since that is
99 // the only way to carry them from conversion to conversion (and also have a
100 // variable phase-center; which can, btw, always be obtained by the
101 // phaseCenter() member).</note>
102 // Note that a reCalculate() is necessary between calls of the engine,
103 // since the planetary position will change from time to time (i.e. with
104 // the Frame).
105 //
106 // If no explicit output coordinate is given (i.e. no phase shift necessary),
107 // and the conversion from input to output is an essential NOP, and no
108 // reprojection to the input plane is required, the machine will bypass all
109 // calculations. This state can be inspected by the <src>isNOP()</src> method.
110 //
111 // If you want to convert to say an azimuth/elevation map of the Sun, this
112 // can be done to have either two conversion engines (original to Sun, then
113 // Sun to AzEl), or by conversion of the Sun to AzEl before entering the
114 // engine.
115 // <note role=tip>
116 // The output of the machine is either a set of rotation matrices that can
117 // be used to convert UVW coordinates (and, if necessary, phases); or the
118 // UVW conversion and actual phase can be calculated from a given
119 // UVW coordinate (or set of coordinates).
120 // </note>
121 // <note role=tip> Since e.g. in an EW interferometer (or any set of baselines
122 // on a line) the phase correction and UVW transform scales with the length
123 // of the baseline, conversion of a nominal (say 1m) baseline suffices to
124 // easily calculate others. The same is true for baselines in a plane,
125 // where a conversion of two orthogonal baselines in that plane will suffice.
126 // </note>
127 // </synopsis>
128 //
129 // <example>
130 // <srcblock>
131 // // Given a current phase stopping Center
132 // MDirection indir(Quantity(3.25745692, "rad"),
133 // Quantity(0.040643336,"rad"),
134 // MDirection::Ref(MDirection::B1950));
135 // // Conversion to J2000 is set by:
136 // UVWMachine uvm(MDirection::Ref(MDirection::J2000), indir);
137 // // The rotation matrix to go to new UVW is obtained by:
138 // RotMatrix rm(uvm.rotationUVM());
139 // // If an UVW specified:
140 // MVPosition uvw(-739.048461, -1939.10604, 1168.62562);
141 // // This can be converted by e.g.:
142 // uvw *= rm;
143 // // Or, alternatively, by e.g.:
144 // uvm.convertUVW(uvw);
145 // </srcblock>
146 // </example>
147 //
148 // <motivation>
149 // To aid making maps in different coordinate systems
150 // </motivation>
151 //
152 // <todo asof="1998/01/21">
153 // <li> add EW UVW coordinates
154 // <li> check if non right-handed coordinates systems (like AzEl) are
155 // handled correctly
156 // <li> provide a MVuvw and Muvw class to cater for second order effects
157 // appropiately
158 // </todo>
159 
160 class UVWMachine {
161  public:
162  //# Constructors
163  // Constructors have an EW flag, which will give a projection parallel to
164  // the polar axis rather than in the direction of the fieldcenter, and a
165  // project flag. The last will correct the UV coordinates to re-project
166  // them onto the plane specified by the in direction
167  // <group>
168  // Construct a UVW conversion machine from the in coordinate and its
169  // system to the out coordinate system (output absolute direction
170  // remains the same)
171  UVWMachine(const MDirection::Ref &out, const MDirection &in,
172  Bool EW=False, Bool project=False);
173  // Construct a UVW conversion machine from the in coordinate and its
174  // system to the out coordinate and its system
175  UVWMachine(const MDirection &out, const MDirection &in,
176  Bool EW=False, Bool project=False);
177  // Construct UVW conversion machine with an explicitly given frame
178  // <group>
179  UVWMachine(const MDirection::Ref &out, const MDirection &in,
180  const MeasFrame &frame, Bool EW=False, Bool project=False);
181  UVWMachine(const MDirection &out, const MDirection &in,
182  const MeasFrame &frame, Bool EW=False, Bool project=False);
183  // </group>
184  // </group>
185  // Copy constructor
186  UVWMachine(const UVWMachine &other);
187  // Copy assignments
189 
190  //# Destructor
192 
193  //# Operators
194  // Return converted UVW coordinates
195  // <group>
198  MVPosition operator()(const MVPosition &uv) const;
200  // </group>
201 
202  //# Member functions
203  // Return the new phase center coordinates
204  const MDirection &phaseCenter() const;
205  // Return if the engine is an effective NOP
206  Bool isNOP() { return nop_p; }
207  // Return a rotation matrix that can be used to convert UVW coordinates:
208  // UVW(new) = UVW(old) * rotationUVW()
209  const RotMatrix &rotationUVW() const;
210  // Return a position vector that can produce the phase correction:
211  // dPhase = rotationPhase * UVW(new)
212  const MVPosition &rotationPhase() const;
213  // replace UVW with converted values
214  // <group>
215  void convertUVW(Vector<Double> &uv) const;
216  void convertUVW(Vector<Vector<Double> > &uv) const;
217  void convertUVW(MVPosition &uv) const;
219  // </group>
220  // Get phase shift (in implied units of UVW), and change input uvw as well
221  // <group>
226  // </group>
227  // Replace UVW with converted, and return phase
228  // <group>
231  void convertUVW(Double &phase, MVPosition &uv) const;
233  // </group>
234 
235  // Recalculate the parameters for the machine after e.g. a frame change
236  void reCalculate();
237 
238  private:
239 
240  //# Data
241  // EW flag
243  // Projection flag
245  // Zero phase flag (for speed)
247  // No conversion necessary flag
249  // Old phase center
251  // New coordinate reference
253  // Old phase center in new coordinates
255  // New phase center
257  // Rotation Matrix to go from input UVW to coordinate system
259  // Rotation matrix to go from old system to new system
261  // Rotation Matrix to go from new coordinate system to output UVW
263  // Rotation Matrix to project UV-plane onto
265  // UVW rotation
267  // UVW rotation including projection
269  // Phase rotation
271  // Conversion engine
273 
274  //# Constructors
275  // default constructor: not implemented
277 
278  //# Private Member Functions
279  // Initialise machinery
280  void init();
281  // Planet handling
282  void planetinit();
283  // Copy data members
284  void copy(const UVWMachine &other);
285 };
286 
287 
288 } //# NAMESPACE CASACORE - END
289 
290 #endif
291 
292 
UVWMachine(const MDirection &out, const MDirection &in, Bool EW=False, Bool project=False)
Construct a UVW conversion machine from the in coordinate and its system to the out coordinate and it...
UVWMachine(const UVWMachine &other)
Copy constructor.
UVWMachine & operator=(const UVWMachine &other)
Copy assignments.
RotMatrix rot4_p
Rotation Matrix to project UV-plane onto.
Definition: UVWMachine.h:264
MVPosition operator()(const MVPosition &uv) const
void convertUVW(Vector< MVPosition > &uv) const
RotMatrix uvrot_p
UVW rotation.
Definition: UVWMachine.h:266
Vector< Double > getPhase(Vector< Vector< Double > > &uv) const
Vector< Double > operator()(const Vector< Double > &uv) const
Return converted UVW coordinates.
MVPosition phrot_p
Phase rotation.
Definition: UVWMachine.h:270
void convertUVW(Double &phase, Vector< Double > &uv) const
Replace UVW with converted, and return phase.
void planetinit()
Planet handling.
Double getPhase(Vector< Double > &uv) const
Get phase shift (in implied units of UVW), and change input uvw as well.
void convertUVW(Vector< Vector< Double > > &uv) const
RotMatrix rot3_p
Rotation Matrix to go from new coordinate system to output UVW.
Definition: UVWMachine.h:262
Vector< Double > getPhase(Vector< MVPosition > &uv) const
MDirection outin_p
Old phase center in new coordinates.
Definition: UVWMachine.h:254
void convertUVW(Double &phase, MVPosition &uv) const
UVWMachine(const MDirection::Ref &out, const MDirection &in, const MeasFrame &frame, Bool EW=False, Bool project=False)
Construct UVW conversion machine with an explicitly given frame.
Bool proj_p
Projection flag.
Definition: UVWMachine.h:244
UVWMachine(const MDirection &out, const MDirection &in, const MeasFrame &frame, Bool EW=False, Bool project=False)
RotMatrix rot1_p
Rotation Matrix to go from input UVW to coordinate system.
Definition: UVWMachine.h:258
Bool ew_p
EW flag.
Definition: UVWMachine.h:242
const MDirection & phaseCenter() const
Return the new phase center coordinates.
void convertUVW(Vector< Double > &phase, Vector< MVPosition > &uv) const
MDirection::Ref outref_p
New coordinate reference.
Definition: UVWMachine.h:252
Vector< Vector< Double > > operator()(const Vector< Vector< Double > > &uv) const
Bool isNOP()
Return if the engine is an effective NOP.
Definition: UVWMachine.h:206
void init()
Initialise machinery.
void convertUVW(Vector< Double > &uv) const
replace UVW with converted values
void convertUVW(MVPosition &uv) const
Bool nop_p
No conversion necessary flag.
Definition: UVWMachine.h:248
void convertUVW(Vector< Double > &phase, Vector< Vector< Double > > &uv) const
const RotMatrix & rotationUVW() const
Return a rotation matrix that can be used to convert UVW coordinates: UVW(new) = UVW(old) * rotationU...
Bool zp_p
Zero phase flag (for speed)
Definition: UVWMachine.h:246
Double getPhase(MVPosition &uv) const
const MVPosition & rotationPhase() const
Return a position vector that can produce the phase correction: dPhase = rotationPhase * UVW(new)
MDirection in_p
Old phase center.
Definition: UVWMachine.h:250
MDirection out_p
New phase center.
Definition: UVWMachine.h:256
void reCalculate()
Recalculate the parameters for the machine after e.g.
void copy(const UVWMachine &other)
Copy data members.
UVWMachine()
default constructor: not implemented
MDirection::Convert conv_p
Conversion engine.
Definition: UVWMachine.h:272
RotMatrix rot2_p
Rotation matrix to go from old system to new system.
Definition: UVWMachine.h:260
UVWMachine(const MDirection::Ref &out, const MDirection &in, Bool EW=False, Bool project=False)
Constructors have an EW flag, which will give a projection parallel to the polar axis rather than in ...
Vector< MVPosition > operator()(const Vector< MVPosition > &uv) const
RotMatrix uvproj_p
UVW rotation including projection.
Definition: UVWMachine.h:268
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
TableExprNode phase(const TableExprNode &node)
The phase (i.e.
Definition: ExprNode.h:1448
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
double Double
Definition: aipstype.h:55