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
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40//# Forward Declarations
41class MVEpoch;
42class MVPosition;
43class MVDirection;
44class MVRadialVelocity;
45class MeasComet;
46class FrameRep;
47class MCFrame;
48template <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
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.
159 EPOCH = 1,
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)
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>
214 void resetEpoch(const Vector<Double> &val);
215 void resetEpoch(const Quantum<Double> &val);
217 void resetEpoch(const MVEpoch &val);
218 void resetEpoch(const Measure &val);
221 void resetPosition(const MVPosition &val);
222 void resetPosition(const Measure &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
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>
272 // </group>
273 // Get B1950 coordinates (direction cosines)
274 // <group>
278 // </group>
279 // Get apparent coordinates (direction cosines)
280 // <group>
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
291 // </group>
292
293private:
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
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
329ostream &operator<<(ostream &os, MeasFrame &mf);
330// </group>
332
333} //# NAMESPACE CASACORE - END
334
335#endif
const Measure * epoch() const
Get the epoch pointer (0 if not present)
Bool getCometType(uInt &tdb) const
Get the comet table reference type.
void resetEpoch(const MVEpoch &val)
Bool getTDB(Double &tdb) const
Get data from frame.
void resetPosition(const Quantum< Vector< Double > > &val)
void resetRadialVelocity(const Measure &val)
const Measure * position() const
Get the position pointer (0 if not present)
void resetEpoch(const Vector< Double > &val)
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.
void set(const Measure &meas1, const Measure &meas2)
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)
const Measure * direction() const
Get the direction pointer (0 if not present)
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.
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
void set(const Measure &meas1, const Measure &meas2, const Measure &meas3)
Bool getComet(MVPosition &tdb) const
Get the comet coordinates.
~MeasFrame()
Destructor.
friend ostream & operator<<(ostream &os, MeasFrame &mf)
Output a frame.
const Measure * radialVelocity() const
Get the radial velocity pointer (0 if not present)
const MeasComet * comet() const
Get the comet pointer (0 if not present)
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)
Bool getITRF(MVPosition &tdb) const
Get the position.
Bool getLSR(Double &tdb) const
Get LSR radial velocity (m/s)
MeasFrame & operator=(const MeasFrame &other)
Copy assignment (reference semantics)
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
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
unsigned int uInt
Definition: aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
double Double
Definition: aipstype.h:55
ostream & operator<<(ostream &os, MeasFrame &mf)
Output a frame.