casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 class String;
40 class Unit;
41 class MeasValue;
42 class MRBase;
43 template <class T> class Quantum;
44 template <class T> class Vector;
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  // Get the type (== Register() of derived Measure (faster than Strings)
298  // All should have:
299  // static uInt myType();
300  virtual uInt type() const = 0;
301  // Assert that we are the correct Measure type
302  // <thrown>
303  // <li> AipsError if wrong Measure type
304  // </thrown>
305  // Each Measure should have:
306  // <src> static void assure(const Measure &in); </src>
307  // <group>
308  virtual void assured(const String &tp) const = 0;
309  // </group>
310  // Tell me your Measure type (e.g. "Epoch")
311  virtual const String &tellMe() const = 0;
312 
313  // Each Measure should have the following static methods to give its
314  // name (e.g. Epoch) or reference type (e.g. UTC):<br>
315  // <srcblock>
316  // // Show the Measure type (e.g. "Direction")
317  // static const String &showMe();
318  // // Cast an integer to the appropriate reference type. Avaialable to provide
319  // // a safe cast in cases where Measure type is not explicitly known.
320  // static Measure::Types castType(uInt tp);
321  // // Show the reference type (e.g. MEpoch::showType(MEpoch::IAT) == "TAI")
322  // static const String &showType(uInt tp);
323  // static const String &showType(Measure::Types tp);
324  // </srcblock>
325  // <group>
326  virtual String getRefString() const = 0;
327  // </group>
328  // Tell me if you are a pure model (e.g. a planet)
329  virtual Bool isModel() const;
330  //
331  // Each derived class should have a string-to-code translation routine
332  // for the reference type. The routine returns False if unknown String (and
333  // a default mr), else an appropiate mr reference.
334  // <srcblock>
335  // Bool giveMe(Measure::Ref &mr, const String &in);
336  // static Bool getType(Measure::Types &tp, const String &in);
337  // </srcblock>
338  // <group>
339  // Dummy for cxx2html
340  void dummy_giveMe() const {}
341  // </group>
342  //
343  // Set the reference type to the specified String. False if illegal
344  // string, reference set to DEFAULT.
345  virtual Bool setRefString(const String &in) = 0;
346  // Get the default reference type
347  virtual const String &getDefaultType() const = 0;
348  // Get a list of all known reference codes. nall returns the number in list,
349  // nextra the number of specials (like planets) that should be at
350  // end of list). typ returns the list of corresponding types.
351  // All should have
352  // <srcblock>
353  // static const String* allMyTypes(Int &nall, Int &nextra,
354  // const uInt *&typ);
355  // </srcblock>
356  // <group>
357  virtual const String* allTypes(Int &nall, Int &nextra,
358  const uInt *&typ) const;
359  // </group>
360  //
361  // Check if all internal tables of types (both enum and String) are
362  // complete and correct. This function is called automatically if and when
363  // necessary.
364  // <thrown>
365  // <li> AipsError if a (programming) error in the types.
366  // </thrown>
367  // All should have
368  // <srcblock>
369  // static void checkMyTypes();
370  // </srcblock>
371  // <group>
372  virtual void checkTypes() const = 0;
373  // </group>
374  //
375  // A general string checking routine to be used in derived measures.
376  // Its arguments are the string to be converted (in), an array of
377  // strings to check against (tname), and its length (N_name). The check
378  // is case insensitive and mini-max. A return value less than N_name indicates
379  // success.
380  static uInt giveMe(const String &in, Int N_name,
381  const String tname[]);
382  // Each class should have a function to return its reference:
383  // <srcblock>
384  // Measure::Ref getRef() const;
385  // </srcblock>
386  // <group>
387  // Dummy for cxx2html
388  void dummy_getRef() const {}
389  // </group>
390  //
391  // Each derived class should be able to get its internal value and have:
392  // <srcblock>
393  // const MVmeasure &getValue() const;
394  // </srcblock>
395  // To get dimensioned data, each derived class should contain the
396  // appropiate one of:
397  // <srcblock>
398  // Quantity get(const Unit &unit) const;
399  // Quantum<Vector<Double> > get(const Unit &unit) const;
400  // </srcblock>
401  // <group>
402  void dummy_getValue() const {}
403  // </group>
404  //
405  //
406  // Get unit (only available if Measure generated from a Quantum, else "")
407  virtual const Unit &getUnit() const = 0;
408 
409  // Get data pointer (used by MeasConvert)
410  virtual const MeasValue* getData() const = 0;
411 
412  // Get general reference pointer
413  virtual MRBase *getRefPtr() const = 0;
414 
415  // Print a Measure
416  virtual void print(std::ostream &os) const = 0;
417  // Create a copy
418  // <group>
419  virtual Measure *clone() const = 0;
420  // </group>
421 protected:
422 
423 private:
424  //# Enumerations
425 
426  //# Data
427  // Each class will have the following information:
428  // Actual data
429  // <srcblock>
430  // MVmeasure data;
431  // </srcblock>
432  // Reference frame data
433  // <srcblock>
434  // MeasRef<Measure> ref;
435  // </srcblock>
436  // Possible input units
437  // <srcblock>
438  // Unit unit;
439  // </srcblock>
440  // And maybe later (or somewhere else)
441  // <srcblock>
442  // MeasErr error;
443  // </srcblock>
444  // <group>
445  // Dummy for cxx2html
446  void dummy_data() const {}
447  // </group>
448  //
449  //# Member functions
450  // Clear the measure
451  virtual void clear() = 0;
452 
453 };
454 
455 //# Global functions
456 // <summary> Global functions </summary>
457 // <group name=Output>
458 // Output declaration
459 std::ostream &operator<<(std::ostream &os, const Measure &meas);
460 // </group>
461 
462 
463 } //# NAMESPACE CASACORE - END
464 
465 #endif
friend std::ostream & operator<<(std::ostream &os, const Measure &meas)
Each derived class should have:
A 1-D Specialization of the Array class.
int Int
Definition: aipstype.h:50
std::vector< double > Vector
Definition: ds9context.h:24
Base for Reference frame for physical measures.
Definition: MRBase.h:103
virtual Bool putValue(const Vector< Quantum< Double > > &in)=0
void dummy_data() const
Each class will have the following information: Actual data.
Definition: Measure.h:446
virtual MRBase * getRefPtr() const =0
Get general reference pointer.
Physical quantities within reference frame.
Definition: Measure.h:235
virtual const String * allTypes(Int &nall, Int &nextra, const uInt *&typ) const
Get a list of all known reference codes.
virtual uInt type() const =0
Get the type (== Register() of derived Measure (faster than Strings) All should have: static uInt myT...
void dummy_getValue() const
Each derived class should be able to get its internal value and have:
Definition: Measure.h:402
ostream & operator<<(ostream &os, const std::pair< T, U > &p)
virtual ~Measure()
Destructor.
virtual Bool setRefString(const String &in)=0
Set the reference type to the specified String.
virtual Bool areYou(const String &tp) const =0
Check the type of derived Measure entity (e.g.
defines physical units
Definition: Unit.h:189
virtual String getRefString() const =0
Each Measure should have the following static methods to give its name (e.g.
virtual const MeasValue * getData() const =0
Get data pointer (used by MeasConvert)
Base class for values in a Measure.
Definition: MeasValue.h:107
virtual Measure * clone() const =0
Create a copy.
virtual void clear()=0
Clear the measure.
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 Bool isModel() const
Tell me if you are a pure model (e.g.
virtual void set(const MeasValue &dt)=0
Each Measure should have the following set functions (with appropiate MVs and Ref): ...
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual const Unit & getUnit() const =0
Get unit (only available if Measure generated from a Quantum, else &quot;&quot;)
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 void checkTypes() const =0
Check if all internal tables of types (both enum and String) are complete and correct.
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:340
virtual const String & tellMe() const =0
Tell me your Measure type (e.g.
virtual void assured(const String &tp) const =0
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.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
void dummy_getRef() const
Each class should have a function to return its reference:
Definition: Measure.h:388
unsigned int uInt
Definition: aipstype.h:51
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42