casacore
Measure.h
Go to the documentation of this file.
1 //# Measure.h: Physical quantities within reference frame
2 //# Copyright (C) 1995,1996,1997,1998,1999,2000,2001,2002
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 //#
27 //# $Id$
28 
29 #ifndef MEASURES_MEASURE_H
30 #define MEASURES_MEASURE_H
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/iosfwd.h>
35 #include <casacore/casa/Arrays/ArrayFwd.h>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 //# Forward Declarations
40 class String;
41 class Unit;
42 class MeasValue;
43 class MRBase;
44 template <class T> class Quantum;
45 
46 // <summary>
47 // Physical quantities within reference frame
48 // </summary>
49 
50 // <use visibility=export>
51 
52 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tMeasure" demos="">
53 // </reviewed>
54 
55 // <prerequisite>
56 // <li> <linkto module="Measures">Measures module</linkto> description
57 // <li> <linkto class=Quantum>Quantum</linkto> dimensioned values
58 // <li> <linkto class=MeasValue>MeasValue</linkto> internal measure values
59 // <li> <linkto class=MeasRef>MeasRef</linkto> class to specify reference
60 // frame
61 // <li> <linkto class=MeasConvert>MeasConvert</linkto> class, doing actual conversions
62 // of a measure from one reference frame to another
63 // <li> Some classes if you really want to understand details:
64 // <ul>
65 // <li> <linkto class=MeasBase>MeasBase</linkto> class, the immediate
66 // parent of all specific Measures
67 // <li> <linkto class=MCBase>MCBase</linkto> class, the base class
68 // for all specific conversion routines (like
69 // <linkto class=MCEpoch>MCEpoch</linkto>).
70 // <li> <linkto class=MeasData>MeasData</linkto> class, containing a set
71 // of generally usable constants, and all program data necessary for
72 // conversions.
73 // </ul>
74 // <li> <linkto class=MeasTable>MeasTab;e</linkto> class, containing
75 // the interface for external Tables (like leap-seconds, IERS data,
76 // JPL data).
77 // </prerequisite>
78 //
79 // <etymology>
80 // </etymology>
81 //
82 // <synopsis>
83 // Measure forms the abstract base class for physical quantities within
84 // a reference frame. Examples of derived classes are:
85 // <ul>
86 // <li> <linkto class=MEpoch>MEpoch</linkto>: a moment in time
87 // <li> <linkto class=MDirection>MDirection</linkto>: a direction in space
88 // <li> <linkto class=MPosition>MPosition</linkto>: a position on Earth
89 // <li> <linkto class=MFrequency>MFrequency</linkto>: wave characteristics
90 // <li> <linkto class=MRadialVelocity>MRadialVelocity</linkto>: a space
91 // radial velocity
92 // <li> <linkto class=MDoppler>MDoppler</linkto>: a Doppler velocity
93 // </ul>
94 // Measure is the generic name for the more specific instances like, e.g.,
95 // MEpoch, an instant in time.<br>
96 // A Measure has both a value (specified in some value internal to the specific
97 // Measure, in general called <em>MVMeasure</em> (e.g. MVEpoch)), see
98 // <linkto class=MeasValue>MeasValue</linkto> for general details; and a
99 // reference type and frame specifier (see
100 // <linkto class=MeasRef>MeasRef</linkto> class).<br>
101 // The <linkto class=MeasRef>MeasRef</linkto> specifies the reference type
102 // of the value, e.g. TAI, UTC, LAST. In addition the
103 // <linkto class=MeasRef>MeasRef</linkto> specifies a possible offset (e.g.
104 // the beginning of the year, or today), and, if necessary, Measures necessary
105 // for defining the absolute quantity (e.g. an
106 // <linkto class=MPosition>MPosition</linkto> on Earth for LAST), using a
107 // reference frame specifier (see
108 // <linkto class=MeasFrame>MeasFrame</linkto> class).<br>
109 // The <src>MeasRef</src> class is templated, but typedefs exist
110 // (and should be used) to
111 // easily specify the correct one, e.g. <src>MEpoch::Ref</src>.<br>
112 // A Measure can be converted from one reference frame to another (e.g.
113 // an MDirection can be converted from J2000 to apparent coordinates) by
114 // setting up a measure specific conversion engine (see
115 // <linkto class=MeasConvert>MeasConvert</linkto> class and below).
116 // From an input
117 // <src>MeasRef</src> frame and an output <src>MeasRef</src> frame it
118 // constructs a conversion <em>functional</em>, that can be fed values (with
119 // the <src>() operator</src>).<br>
120 // Some conversions can, in addition to the main type (like TAI), specify
121 // details to completely describe any conversion process (e.g. the type
122 // of nutation calculation) by specifying
123 // <linkto class=Aipsrc>Aipsrc</linkto> keyword/value pairs. <br>
124 // <p>
125 // Measures can in general be constructed from a <src>MeasRef</src> and a
126 // value. The value can be expressed in the internally used units (e.g.
127 // <linkto class=MVEpoch>MVEpoch</linkto> for <src>MEpoch</src>,
128 // <linkto class=MVDirection>MVDirection</linkto> for <src>MDirection</src>), or
129 // as a <src>Quantum</src>, i.e. a value with a dimension (e.g. (20,"km/s"))
130 // (see <linkto class=Quantum>Quantum</linkto> class). The preferred way of
131 // construction is by using the constructor:
132 // <srcblock>
133 // Measure(MVmeasure, Measure::Ref)
134 // </srcblock>
135 // where the reference can be omitted,
136 // defaulting to <src>Measure::DEFAULT</src>), or in simple cases (not needing
137 // additional frame information) be specified directly as a code (e.g.
138 // <src>MEpoch::IAT</src>).<br>
139 // <p>
140 // The value of the <src>Measure</src> can be obtained by a variety of
141 // <src>get</src> functions, returning in general internal or <src>Quantum</src>
142 // values. The preferred way is a <src>getValue(void)</src>, which returns
143 // the specific <src>MVmeasure</src> value, which can then be further formatted
144 // using the appropiate <src>MVmeasure</src> get() functions.<br>
145 // Special formatting (like hh:mm:ss.t, dd.mm.ss.t, yy/mm/dd etc)
146 // are catered for in <em>conversion-type</em> classes like
147 // <linkto class=MVAngle>MVAngle</linkto>,
148 // <linkto class=MVTime>MVTime</linkto>.<br>
149 // <p>
150 // Conversion (within a Measure type) from one reference frame to another
151 // is done by the <linkto class=MeasConvert>MeasConvert</linkto> class. The
152 // class is templated, but has typedefs <src>Measure::Convert</src> (e.g.
153 // MEpoch::Convert) for easy, and recommended, reference.<br>
154 // The basic constructors for a
155 // <src>Measure::Convert</src> are:
156 // <srcblock>
157 // // With a default Measure included
158 // Measure::Convert(Measure val, Measure::Ref outref);
159 // // With only input and output reference frames given
160 // Mesaure::Convert( Measure::Ref inref, Measure::Ref outref);
161 // </srcblock>
162 // The <src>val</src>
163 // is used as a <em>model</em> for subsequent input values into this
164 // <em>conversion engine</em>, including possible units; the <src>outref</src>
165 // specifies the output reference frame wanted. The constructor analyses the
166 // conversion wanted, and sets up a vector of routine calls to be called
167 // in sequence for the conversion. The actual conversion is done
168 // by the <src>() operator</src>.<br>
169 // To aid in using the raw measures, each class has also a Measure::MVType and
170 // Measure::MCType defined. They denote respectively the Measure Value class
171 // of the internal value, and the class with conversion routines.
172 // <p>
173 // <note role=tip> In the member description a number of <em>dummy</em> routines are
174 // present. They are the only way I have found to get <em>cxx2html</em> to
175 // get the belonging text properly present.
176 // </note>
177 // </synopsis>
178 //
179 // <example>
180 // <srcblock>
181 // #include <casacore/measures/Measures.h>
182 // #include <casacore/casa/Measure/MEpoch.h>
183 // // Example is only to show what can be done, not the easiest way
184 // // Set up a simple reference (no offset or secondary Measures). It
185 // // indicates that times are given in MJD TAI.
186 // MEpoch::Ref reftai(MEpoch::TAI);
187 // // Same, but indicating MJD UTC
188 // MEpoch::Ref refutc(MEpoch::UTC);
189 // // Set up an MEpoch (note that no reference is given. In that case a
190 // // default is assumed (for MEpoch UTC). MJD2000 is a provided constant
191 // // of the MJD at 2000.0
192 // MEpoch UTCval(Quantity(MeasData::MJD2000, "d"), reftai);
193 // // Set up, just for fun, an epoch, UTC for B1950.0:
194 // MEpoch val1950(Quantity(MeasData::MJDB1950, "d"));
195 // // and use it as an offset in a reference
196 // MEpoch::Ref ref1950(MEpoch::TAI, val1950);
197 // // An epoch for J2000 with an offset of B1950.0 will than be
198 // MEpoch val20_50(Quantity(MeasData::MJD2000-MeasData::MJDB1950, "d"),
199 // ref1950);
200 // // Set up conversion from TAI(with values in days w.r.t. B1950.0) to UTC:
201 // MEpoch::Convert tai_to_utc(val20_50, refutc);
202 // // And convert a value (in this case the value in val20_50, the model)
203 // // from TAI(relative to B1950.0) to 'absolute' UTC
204 // MEpoch result = tai_to_utc();
205 // // Show result
206 // cout << "Result 1: " << result << endl;
207 // // To convert 10 years since B1950.0
208 // result = tai_to_utc(Quantity(10.,"a"));
209 // cout << "Result 2: " << result << endl;
210 // // To convert any value in years(the last used units of the model) since B1950.0
211 // result = tai_to_utc(12.3);
212 // cout << "Result 3: " << result << endl;
213 // </srcblock>
214 // Which generates the output:
215 // <srcblock>
216 // Result 1: Epoch: 51544::11:59:25.2154
217 // Result 2: Epoch: 36934::10:09:42.1283
218 // Result 3: Epoch: 37774::11:57:41.1085
219 // </srcblock>
220 // </example>
221 //
222 // <motivation>
223 // To be able to specify a physical entity absolutely in any reference frame;
224 // and to be able to convert from one frame to another. E.g. Local Sidereal
225 // Time to Temps Atomic International. A templated version for the MeasRef
226 // and MeasConvert was chosen to be able to check most arguments at
227 // compile time.
228 // </motivation>
229 //
230 // <todo asof='1997/04/15'>
231 // <li> more Measures, e.g. MPlanet
232 // <li> operators on Measures (e.g. MEpoch - MEpoch == MDuration)
233 // </todo>
234 
235 class Measure {
236 
237 public:
238  //# Enumerations
239  // Each derived class should have a <src>Types</src> enumeration, specifying
240  // the recognised frame types. It is formatted as:
241  // <srcblock>
242  // enum Types {
243  // CODE1,
244  // CODE2,
245  // ...,
246  // N_Types, // Number of types
247  // SPEC1 = n, // Possible special manipulator code
248  // .....,
249  // SYNONYM1 = CODEn, // Probable synonyms
250  // ....,
251  // DEFAULT = CODEm};
252  // </srcblock>
253  // Dummy for cxx2html
254  enum Types {N_Types, DEFAULT = 0};
255 
256  //# Typedefs
257  // Each Measure should have typedefs of the form:
258  // <srcblock>
259  // typedef MeasConvert<class a_Measure, class its_MV, its_MC> Convert;
260  // typedef MeasRef<class a_Measure> Ref;
261  // </srcblock>
262  // Dummy for cxx2html
263  typedef void* Convert;
264  //# Friends
265  // Each derived class should have:
266  // <srcblock>
267  // friend class MeasConvert<a_Measure, its_MV, its_MC>;
268  // </srcblock>
269  // Output a Measure
270  friend std::ostream &operator<<(std::ostream &os, const Measure &meas);
271 
272  //# Constructors
273 
274  //# Destructor
275  // Destructor
276  virtual ~Measure();
277 
278  //# Operators
279 
280  //# General Member Functions
281  // Each Measure should have the following set functions (with appropiate
282  // MVs and Ref):
283  // <srcblock>
284  // void set(const MVmeasure &dt);
285  // void set(const Measure::Ref &rf);
286  // void set(const MVmeasure &dt, const Measure::Ref &rf);
287  // </srcblock>
288  // <group>
289  virtual void set(const MeasValue &dt) = 0;
290  virtual Bool putValue(const Vector<Quantum<Double> > &in) = 0;
291  // </group>
292  // Set the offset in the reference (False if non-matching Measure)
293  virtual Bool setOffset(const Measure &in) = 0;
294  //
295  // Check the type of derived Measure entity (e.g. "Epoch")
296  virtual Bool areYou(const String &tp) const = 0;
297  // All should have:
298  // Assert that we are the correct Measure type
299  // <thrown>
300  // <li> AipsError if wrong Measure type
301  // </thrown>
302  // Each Measure should have:
303  // <src> static void assure(const Measure &in); </src>
304  // <group>
305  virtual void assured(const String &tp) const = 0;
306  // </group>
307  // Tell me your Measure type (e.g. "Epoch")
308  virtual const String &tellMe() const = 0;
309 
310  // Each Measure should have the following static methods to give its
311  // name (e.g. Epoch) or reference type (e.g. UTC):<br>
312  // <srcblock>
313  // // Show the Measure type (e.g. "Direction")
314  // static const String &showMe();
315  // // Cast an integer to the appropriate reference type. Avaialable to provide
316  // // a safe cast in cases where Measure type is not explicitly known.
317  // static Measure::Types castType(uInt tp);
318  // // Show the reference type (e.g. MEpoch::showType(MEpoch::IAT) == "TAI")
319  // static const String &showType(uInt tp);
320  // static const String &showType(Measure::Types tp);
321  // </srcblock>
322  // <group>
323  virtual String getRefString() const = 0;
324  // </group>
325  // Tell me if you are a pure model (e.g. a planet)
326  virtual Bool isModel() const;
327  //
328  // Each derived class should have a string-to-code translation routine
329  // for the reference type. The routine returns False if unknown String (and
330  // a default mr), else an appropiate mr reference.
331  // <srcblock>
332  // Bool giveMe(Measure::Ref &mr, const String &in);
333  // static Bool getType(Measure::Types &tp, const String &in);
334  // </srcblock>
335  // <group>
336  // Dummy for cxx2html
337  void dummy_giveMe() const {}
338  // </group>
339  //
340  // Set the reference type to the specified String. False if illegal
341  // string, reference set to DEFAULT.
342  virtual Bool setRefString(const String &in) = 0;
343  // Get the default reference type
344  virtual const String &getDefaultType() const = 0;
345  // Get a list of all known reference codes. nall returns the number in list,
346  // nextra the number of specials (like planets) that should be at
347  // end of list). typ returns the list of corresponding types.
348  // All should have
349  // <srcblock>
350  // static const String* allMyTypes(Int &nall, Int &nextra,
351  // const uInt *&typ);
352  // </srcblock>
353  // <group>
354  virtual const String* allTypes(Int &nall, Int &nextra,
355  const uInt *&typ) const;
356  // </group>
357  //
358  // Check if all internal tables of types (both enum and String) are
359  // complete and correct. This function is called automatically if and when
360  // necessary.
361  // <thrown>
362  // <li> AipsError if a (programming) error in the types.
363  // </thrown>
364  // All should have
365  // <srcblock>
366  // static void checkMyTypes();
367  // </srcblock>
368  // <group>
369  virtual void checkTypes() const = 0;
370  // </group>
371  //
372  // A general string checking routine to be used in derived measures.
373  // Its arguments are the string to be converted (in), an array of
374  // strings to check against (tname), and its length (N_name). The check
375  // is case insensitive and mini-max. A return value less than N_name indicates
376  // success.
377  static uInt giveMe(const String &in, Int N_name,
378  const String tname[]);
379  // Each class should have a function to return its reference:
380  // <srcblock>
381  // Measure::Ref getRef() const;
382  // </srcblock>
383  // <group>
384  // Dummy for cxx2html
385  void dummy_getRef() const {}
386  // </group>
387  //
388  // Each derived class should be able to get its internal value and have:
389  // <srcblock>
390  // const MVmeasure &getValue() const;
391  // </srcblock>
392  // To get dimensioned data, each derived class should contain the
393  // appropiate one of:
394  // <srcblock>
395  // Quantity get(const Unit &unit) const;
396  // Quantum<Vector<Double> > get(const Unit &unit) const;
397  // </srcblock>
398  // <group>
399  void dummy_getValue() const {}
400  // </group>
401  //
402  //
403  // Get unit (only available if Measure generated from a Quantum, else "")
404  virtual const Unit &getUnit() const = 0;
405 
406  // Get data pointer (used by MeasConvert)
407  virtual const MeasValue* getData() const = 0;
408 
409  // Get general reference pointer
410  virtual MRBase *getRefPtr() const = 0;
411 
412  // Print a Measure
413  virtual void print(std::ostream &os) const = 0;
414  // Create a copy
415  // <group>
416  virtual Measure *clone() const = 0;
417  // </group>
418 protected:
419 
420 private:
421  //# Enumerations
422 
423  //# Data
424  // Each class will have the following information:
425  // Actual data
426  // <srcblock>
427  // MVmeasure data;
428  // </srcblock>
429  // Reference frame data
430  // <srcblock>
431  // MeasRef<Measure> ref;
432  // </srcblock>
433  // Possible input units
434  // <srcblock>
435  // Unit unit;
436  // </srcblock>
437  // And maybe later (or somewhere else)
438  // <srcblock>
439  // MeasErr error;
440  // </srcblock>
441  // <group>
442  // Dummy for cxx2html
443  void dummy_data() const {}
444  // </group>
445  //
446  //# Member functions
447  // Clear the measure
448  virtual void clear() = 0;
449 
450 };
451 
452 //# Global functions
453 // <summary> Global functions </summary>
454 // <group name=Output>
455 // Output declaration
456 std::ostream &operator<<(std::ostream &os, const Measure &meas);
457 // </group>
458 
459 
460 } //# NAMESPACE CASACORE - END
461 
462 #endif
virtual const String & tellMe() const =0
Tell me your Measure type (e.g.
virtual Bool setOffset(const Measure &in)=0
Set the offset in the reference (False if non-matching Measure)
void dummy_giveMe() const
Each derived class should have a string-to-code translation routine for the reference type.
Definition: Measure.h:337
virtual ~Measure()
Destructor.
void dummy_getValue() const
Each derived class should be able to get its internal value and have:
Definition: Measure.h:399
virtual Measure * clone() const =0
Create a copy.
virtual const String * allTypes(Int &nall, Int &nextra, const uInt *&typ) const
Get a list of all known reference codes.
virtual void print(std::ostream &os) const =0
Print a Measure.
void * Convert
Each Measure should have typedefs of the form:
Definition: Measure.h:263
virtual MRBase * getRefPtr() const =0
Get general reference pointer.
virtual Bool isModel() const
Tell me if you are a pure model (e.g.
void dummy_getRef() const
Each class should have a function to return its reference:
Definition: Measure.h:385
virtual const MeasValue * getData() const =0
Get data pointer (used by MeasConvert)
virtual void set(const MeasValue &dt)=0
Each Measure should have the following set functions (with appropiate MVs and Ref):
virtual Bool setRefString(const String &in)=0
Set the reference type to the specified String.
virtual const Unit & getUnit() const =0
Get unit (only available if Measure generated from a Quantum, else "")
virtual const String & getDefaultType() const =0
Get the default reference type.
Types
Each derived class should have a Types enumeration, specifying the recognised frame types.
Definition: Measure.h:254
virtual String getRefString() const =0
Each Measure should have the following static methods to give its name (e.g.
friend std::ostream & operator<<(std::ostream &os, const Measure &meas)
Each derived class should have:
virtual void clear()=0
Clear the measure.
virtual Bool areYou(const String &tp) const =0
Check the type of derived Measure entity (e.g.
virtual void assured(const String &tp) const =0
All should have: Assert that we are the correct Measure type.
static uInt giveMe(const String &in, Int N_name, const String tname[])
A general string checking routine to be used in derived measures.
void dummy_data() const
Each class will have the following information: Actual data.
Definition: Measure.h:443
virtual Bool putValue(const Vector< Quantum< Double > > &in)=0
virtual void checkTypes() const =0
Check if all internal tables of types (both enum and String) are complete and correct.
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
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.