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
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39//# Forward Declarations
40class String;
41class Unit;
42class MeasValue;
43class MRBase;
44template <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
235class Measure {
236
237public:
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>
418protected:
419
420private:
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
456std::ostream &operator<<(std::ostream &os, const Measure &meas);
457// </group>
459
460} //# NAMESPACE CASACORE - END
461
462#endif
virtual const String & getDefaultType() const =0
Get the default reference type.
virtual Measure * clone() const =0
Create a copy.
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.
virtual const MeasValue * getData() const =0
Get data pointer (used by MeasConvert)
friend std::ostream & operator<<(std::ostream &os, const Measure &meas)
Each derived class should have:
void dummy_getValue() const
Each derived class should be able to get its internal value and have:
Definition: Measure.h:399
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.
void dummy_getRef() const
Each class should have a function to return its reference:
Definition: Measure.h:385
virtual const String * allTypes(Int &nall, Int &nextra, const uInt *&typ) const
Get a list of all known reference codes.
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 String & tellMe() const =0
Tell me your Measure type (e.g.
virtual const Unit & getUnit() const =0
Get unit (only available if Measure generated from a Quantum, else "")
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.
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.
virtual MRBase * getRefPtr() const =0
Get general reference pointer.
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
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
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
std::ostream & operator<<(std::ostream &os, const Measure &meas)
Output declaration.