casacore
MeasFrame.h
Go to the documentation of this file.
1 //# MeasFrame.h: Container for Measure frame
2 //# Copyright (C) 1996-2003,2007
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 MEASURES_MEASFRAME_H
29 #define MEASURES_MEASFRAME_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/Arrays/ArrayFwd.h>
34 #include <casacore/casa/Arrays/Vector.h>
35 #include <casacore/measures/Measures/Measure.h>
36 #include <casacore/casa/iosfwd.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 //# Forward Declarations
41 class MVEpoch;
42 class MVPosition;
43 class MVDirection;
44 class MVRadialVelocity;
45 class MeasComet;
46 class FrameRep;
47 class MCFrame;
48 template <class Qtype> class Quantum;
49 
50 // <summary> Container for Measure frame </summary>
51 
52 // <use visibility=export>
53 
54 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tMeasure" demos="">
55 // </reviewed>
56 
57 // <prerequisite>
58 // <li> <linkto class=Measure>Measure</linkto> class
59 // <li> <linkto class=MeasRef>MeasRef</linkto> class
60 // </prerequisite>
61 //
62 // <etymology>
63 // From Measure and Frame
64 // </etymology>
65 //
66 // <synopsis>
67 // Measurements are made in a reference frame (epoch, position, direction,
68 // ...).<br>
69 // The class is a container for the reference frame Measures (MEpoch etc).
70 // Since a frame will possibly be used by many different Measures, it behaves
71 // as a smart pointer, with reference rather than copy characteristics.
72 // Since it caches all its operations, it is advisable to have a 'global'
73 // MeasFrame across an execution, resetting (or setting) its values
74 // when appropriate. The frame can also contain other related information. At
75 // the moment the orbit of a solar system body (MeasComet) can be set.
76 // In future the planetary ephemeris used (e.g. DE205) and environmental
77 // information like refraction data will be added.
78 //
79 // A MeasFrame is constructed by setting the appropriate Measures, either in
80 // a constructor, or with a set(). The input to the constructors and set are
81 // Measures.<br>
82 //
83 // Inside the frames automatic conversion to the most appropriate usage of
84 // its values is done (e.g. time to TBD time, position to astronomical
85 // longitude). These conversions are done only if an explicit
86 // Measure::Convert was used that needed information, e.g. the following
87 // code:
88 // <srcblock>
89 // MeasFrame frame(obser); // obser is an MPosition
90 // MEpoch::Convert conv(MEpoch(12345), MEpoch::Ref(MEpoch::LAST,obser));
91 // MEpoch last = conv();
92 // </srcblock>
93 // will set-up a state machine to convert UTC(default) to LAST in conv; the
94 // next call will do the actual conversion. During this conversion, the
95 // astronomical longitude (among others) will be needed to convert to
96 // local sidereal time. conv will ask (getLong()) this from the frame, which
97 // will calculate it (including possible other conversions) from the
98 // observatory's position specified in a frame. Any calculation done will be
99 // cached (e.g. a Nutation calculation in this case for dpsi), and used in
100 // subsequent conversions using the same frame.<br>
101 // Furthermore, a frame will often be regularly updated (e.g. coordinate
102 // conversion for a series of times). To make use of cached information, and
103 // to speed up as much as possible, <src>reset...()</src> functions are
104 // available. These reset functions accept the same range of input parameter
105 // types as the <linkto class=MeasConvert>MeasConvert</linkto> () operator,
106 // and will keep any determined conversion machines and related information
107 // intact, only recalculating whatever is necessary.<br>
108 // The actual frame calculations and interrogations are done in a separate
109 // <linkto class=MCFrame>MCFrame</linkto> hidden class, which attaches itself
110 // to MeasFrame when and if necessary (see there if you are really curious).<br>.
111 // get...() functions can return frame measures. Only when the frame has been
112 // attached to a calculating machine *MCFrame) are these values available.
113 // This attachment is done if the frame has been actively used by a
114 // Measure::Convert engine, or if explicitly done by the
115 // <src>MCFrame::make(MeasFrame &)</src> static method.
116 // <note role=caution> An explicit (or implicit) call to MCFrame::make will
117 // load the whole conversion machinery (including Tables) into your
118 // linked module).</note><br>
119 // <linkto class=Aipsrc>Aipsrc keywords</linkto> can be used for additional
120 // (highly specialised) additional internal conversion parameters.
121 // </synopsis>
122 //
123 // <example>
124 // <srcblock>
125 // MEpoch my_epoch(Quantity(MeasData::MJDB1950,"d")); // an epoch
126 // MeasFrame frame(my_epoch); // used in a frame
127 // </srcblock>
128 // </example>
129 //
130 // <motivation>
131 // To separate the frame definition from the measure type
132 // </motivation>
133 //
134 // <todo asof="1997/04/16">
135 // </todo>
136 
137 class MeasFrame {
138 
139  public:
140 
141  //# Friends
142  // Output a frame
143  friend ostream &operator<<(ostream &os, MeasFrame &mf);
144  // Machinery
145  // <group>
146  friend class MCFrame;
147  friend Bool MCFrameGetdbl(void *dmf, uInt tp, Double &result);
148  friend Bool MCFrameGetmvdir(void *dmf, uInt tp, MVDirection &result);
149  friend Bool MCFrameGetmvpos(void *dmf, uInt tp, MVPosition &result);
150  friend Bool MCFrameGetuint(void *dmf, uInt tp, uInt &result);
151  // </group>
152 
153  //# Enumerations
154  // Enumeration for the different farme entries possible. This can be used
155  // to find out if a certain conversion needs the frame. It will be
156  // used in a registration/notify environment to enable bypassing of
157  // some new conversion settings.
158  enum FrameTypes {
159  EPOCH = 1,
160  POSITION = 2,
162  VELOCITY = 8,
163  COMET = 16 };
164 
165  //# Constructors
166  // Default constructor
168  // Construct frame with specified measures
169  // <thrown>
170  // <li> AipsError if a non-frame Measure
171  // </thrown>
172  // <group>
173  MeasFrame(const Measure &meas1);
174  MeasFrame(const Measure &meas1, const Measure &meas2);
175  MeasFrame(const Measure &meas1, const Measure &meas2,
176  const Measure &meas3);
177  // </group>
178  // Copy constructor (reference semantics)
179  MeasFrame(const MeasFrame &other);
180  // Copy assignment (reference semantics)
181  MeasFrame &operator=(const MeasFrame &other);
182  // Destructor
184 
185  //# Operators
186  // Comparisons
187  // <group>
188  Bool operator==(const MeasFrame &other) const;
189  Bool operator!=(const MeasFrame &other) const;
190  // </group>
191 
192  //# General member functions
193  // Test if empty (i.e. no measure filled in)
194  Bool empty() const;
195 
196  // Set frame elements
197  // <thrown>
198  // <li> AipsError if a non-frame Measure
199  // <li> AipsError if illegal or non-existant MeasComet given
200  // </thrown>
201  // <group>
202  void set(const Measure &meas1);
203  void set(const Measure &meas1, const Measure &meas2);
204  void set(const Measure &meas1, const Measure &meas2,
205  const Measure &meas3);
206  void set(const MeasComet &meas);
207  // </group>
208  // Reset a frame element and its cached derived values.
209  // <thrown>
210  // <li> AipsError if the specific Measure not yet present in frame
211  // </thrown>
212  // <group>
213  void resetEpoch(Double val);
214  void resetEpoch(const Vector<Double> &val);
215  void resetEpoch(const Quantum<Double> &val);
216  void resetEpoch(const Quantum<Vector<Double> > &val);
217  void resetEpoch(const MVEpoch &val);
218  void resetEpoch(const Measure &val);
219  void resetPosition(const Vector<Double> &val);
221  void resetPosition(const MVPosition &val);
222  void resetPosition(const Measure &val);
223  void resetDirection(const Vector<Double> &val);
225  void resetDirection(const MVDirection &val);
226  void resetDirection(const Measure &val);
230  void resetRadialVelocity(const Measure &val);
231  void resetComet(const MeasComet &val);
232  // </group>
233 
234  // Get the epoch pointer (0 if not present)
235  const Measure* epoch() const;
236  // Get the position pointer (0 if not present)
237  const Measure* position() const;
238  // Get the direction pointer (0 if not present)
239  const Measure* direction() const;
240  // Get the radial velocity pointer (0 if not present)
241  const Measure* radialVelocity() const;
242  // Get the comet pointer (0 if not present)
243  const MeasComet* comet() const;
244  // Get data from frame. Only available if appropriate measures are set,
245  // and the frame is in a calculating state.
246  // <group>
247  // Get TDB in days
248  Bool getTDB(Double &tdb) const;
249  // Get UT1 in days
250  Bool getUT1(Double &tdb) const;
251  // Get TT in days
252  Bool getTT(Double &tdb) const;
253  // Get the ITRF longitude (in rad)
254  Bool getLong(Double &tdb) const;
255  // Get the ITRF latitude (in rad)
256  Bool getLat(Double &tdb) const;
257  // Get the position
258  Bool getITRF(MVPosition &tdb) const;
259  // Get the geocentric position (in m)
260  Bool getRadius(Double &tdb) const;
261  // Get the geodetic latitude
262  Bool getLatGeo(Double &tdb) const;
263  // Get the LAST (in days)
264  Bool getLAST(Double &tdb) const;
265  // Get the LAST (in rad)
266  Bool getLASTr(Double &tdb) const;
267  // Get J2000 coordinates (direction cosines) and its longitude/latitude (rad)
268  // <group>
269  Bool getJ2000(MVDirection &tdb) const;
270  Bool getJ2000Long(Double &tdb) const;
271  Bool getJ2000Lat(Double &tdb) const;
272  // </group>
273  // Get B1950 coordinates (direction cosines)
274  // <group>
275  Bool getB1950(MVDirection &tdb) const;
276  Bool getB1950Long(Double &tdb) const;
277  Bool getB1950Lat(Double &tdb) const;
278  // </group>
279  // Get apparent coordinates (direction cosines)
280  // <group>
281  Bool getApp(MVDirection &tdb) const;
282  Bool getAppLong(Double &tdb) const;
283  Bool getAppLat(Double &tdb) const;
284  // </group>
285  // Get LSR radial velocity (m/s)
286  Bool getLSR(Double &tdb) const;
287  // Get the comet table reference type
288  Bool getCometType(uInt &tdb) const;
289  // Get the comet coordinates
290  Bool getComet(MVPosition &tdb) const;
291  // </group>
292 
293 private:
294 
295  //# Data
296  // Representation of MeasFrame
297  FrameRep *rep;
298 
299  //# Member functions
300  // Create an instance of the MeasFrame class
301  void create();
302  // Fill a MeasFrame element
303  // <group>
304  void fill(const Measure *in);
305  void fill(const MeasComet *in);
306  // </group>
307  // Make full Epoch
308  void makeEpoch();
309  // Make full Position
310  void makePosition();
311  // Make full Direction
313  // Make full RadialVelocity
315  // Make full Comet
316  void makeComet();
317  // Throw reset error
318  void errorReset(const String &txt);
319  // Lock the frame to make sure deletion occurs when needed
320  void lock(uInt &locker);
321  // Unlock the frame
322  void unlock(const uInt locker);
323 };
324 
325 //# Global functions
326 // <summary> Global functions </summary>
327 // <group name=Output>
328 // Output a frame
329 ostream &operator<<(ostream &os, MeasFrame &mf);
330 // </group>
331 
332 
333 } //# NAMESPACE CASACORE - END
334 
335 #endif
Bool getCometType(uInt &tdb) const
Get the comet table reference type.
void resetEpoch(const MVEpoch &val)
MeasFrame & operator=(const MeasFrame &other)
Copy assignment (reference semantics)
Bool getTDB(Double &tdb) const
Get data from frame.
void resetPosition(const Quantum< Vector< Double > > &val)
void resetRadialVelocity(const Measure &val)
void resetEpoch(const Vector< Double > &val)
const Measure * radialVelocity() const
Get the radial velocity pointer (0 if not present)
Bool getJ2000Long(Double &tdb) const
void resetDirection(const Measure &val)
void resetEpoch(const Quantum< Double > &val)
void resetDirection(const MVDirection &val)
Bool getLat(Double &tdb) const
Get the ITRF latitude (in rad)
MeasFrame(const Measure &meas1)
Construct frame with specified measures.
const Measure * direction() const
Get the direction pointer (0 if not present)
void set(const Measure &meas1, const Measure &meas2)
const Measure * epoch() const
Get the epoch pointer (0 if not present)
void makeEpoch()
Make full Epoch.
void resetEpoch(Double val)
Reset a frame element and its cached derived values.
void makeRadialVelocity()
Make full RadialVelocity.
Bool getUT1(Double &tdb) const
Get UT1 in days.
MeasFrame()
Default constructor.
void resetRadialVelocity(const MVRadialVelocity &val)
void resetEpoch(const Quantum< Vector< Double > > &val)
Bool getB1950(MVDirection &tdb) const
Get B1950 coordinates (direction cosines)
void resetDirection(const Vector< Double > &val)
void resetRadialVelocity(const Vector< Double > &val)
void resetRadialVelocity(const Quantum< Vector< Double > > &val)
MeasFrame(const Measure &meas1, const Measure &meas2)
Bool getTT(Double &tdb) const
Get TT in days.
void makeComet()
Make full Comet.
Bool getLAST(Double &tdb) const
Get the LAST (in days)
FrameTypes
Enumeration for the different farme entries possible.
Definition: MeasFrame.h:158
Bool getLatGeo(Double &tdb) const
Get the geodetic latitude.
friend ostream & operator<<(ostream &os, MeasFrame &mf)
Output a frame.
FrameRep * rep
Representation of MeasFrame.
Definition: MeasFrame.h:297
void unlock(const uInt locker)
Unlock the frame.
Bool getLong(Double &tdb) const
Get the ITRF longitude (in rad)
Bool operator==(const MeasFrame &other) const
Comparisons.
void resetEpoch(const Measure &val)
void makeDirection()
Make full Direction.
void resetPosition(const Vector< Double > &val)
Bool getB1950Lat(Double &tdb) const
void errorReset(const String &txt)
Throw reset error.
friend Bool MCFrameGetmvpos(void *dmf, uInt tp, MVPosition &result)
MeasFrame(const Measure &meas1, const Measure &meas2, const Measure &meas3)
void fill(const Measure *in)
Fill a MeasFrame element.
void resetPosition(const MVPosition &val)
Bool getJ2000Lat(Double &tdb) const
const MeasComet * comet() const
Get the comet pointer (0 if not present)
void set(const Measure &meas1, const Measure &meas2, const Measure &meas3)
Bool getComet(MVPosition &tdb) const
Get the comet coordinates.
~MeasFrame()
Destructor.
void lock(uInt &locker)
Lock the frame to make sure deletion occurs when needed.
Bool empty() const
Test if empty (i.e.
Bool getAppLat(Double &tdb) const
void resetComet(const MeasComet &val)
void resetPosition(const Measure &val)
Bool getJ2000(MVDirection &tdb) const
Get J2000 coordinates (direction cosines) and its longitude/latitude (rad)
void set(const Measure &meas1)
Set frame elements.
void makePosition()
Make full Position.
Bool operator!=(const MeasFrame &other) const
MeasFrame(const MeasFrame &other)
Copy constructor (reference semantics)
Bool getRadius(Double &tdb) const
Get the geocentric position (in m)
void fill(const MeasComet *in)
friend Bool MCFrameGetmvdir(void *dmf, uInt tp, MVDirection &result)
Bool getB1950Long(Double &tdb) const
Bool getAppLong(Double &tdb) const
friend Bool MCFrameGetuint(void *dmf, uInt tp, uInt &result)
void set(const MeasComet &meas)
const Measure * position() const
Get the position pointer (0 if not present)
Bool getITRF(MVPosition &tdb) const
Get the position.
Bool getLSR(Double &tdb) const
Get LSR radial velocity (m/s)
void resetDirection(const Quantum< Vector< Double > > &val)
friend Bool MCFrameGetdbl(void *dmf, uInt tp, Double &result)
Bool getApp(MVDirection &tdb) const
Get apparent coordinates (direction cosines)
Bool getLASTr(Double &tdb) const
Get the LAST (in rad)
void create()
Create an instance of the MeasFrame class.
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
unsigned int uInt
Definition: aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
double Double
Definition: aipstype.h:55