casacore
Loading...
Searching...
No Matches
Measures.h
Go to the documentation of this file.
1//# Measures.h: a module for coordinates
2//# Copyright (C) 1994,1995,1996,1997,1998,1999,2000,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//# $Id$
27
28#ifndef MEASURES_MEASURES_H
29#define MEASURES_MEASURES_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/casa/Quanta.h>
34#include <casacore/measures/Measures/Measure.h>
35#include <casacore/measures/Measures/MeasBase.h>
36#include <casacore/casa/Quanta/MeasValue.h>
37#include <casacore/measures/Measures/MeasRef.h>
38#include <casacore/measures/Measures/MeasConvert.h>
39
40namespace casacore { //# NAMESPACE CASACORE - BEGIN
41
42// <module>
43//
44
45// <summary> a module for coordinates </summary>
46
47// <use visibility=export>
48
49// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tMeasMath tMeasure"
50// demos="dMeasure">
51
52// <prerequisite>
53// <li> <linkto module=Quanta>Quanta</linkto> module for units and quantities.
54// </prerequisite>
55
56// <etymology>
57// The name Measure derives from physical measurements, i.e. values with
58// units and possibly a reference frame attached.
59// </etymology>
60//
61// <synopsis>
62// The Measure model deals with measures (i.e. quantities with a
63// reference frame).
64// Measures are handled in the <a href="#Measure">Measure</a> section
65// (see <linkto class="Measure">Measure.h</linkto>).
66//
67// <h3> Includes</h3>
68// Including the <src>measures/Measures.h</src> will take care of all
69// includes necessary for the handling of Units and Quantities, and the
70// general Measure interface. For the use of individual Measures, the
71// appropiate include files should be added. E.g. to be able to handle
72// Directions, the following includes could be given:
73// <srcblock>
74// #include <casacore/measures/Measures.h>
75// #include <casacore/measures/Measures/MDirection.h>
76// </srcblock>
77// An inclusion of the appropiate measure file, will also take care of the
78// connected measure value (in this case <src>MVDirection</src>). However,
79// if only the value suffices, it can be included on its own (from the
80// Quanta directory).<br>
81// When doing actual conversions (see MeasConvert later on), by using the
82// explicit Measure::Convert types, the description of the actual
83// conversions (called MCmeasure, e.g. MCEpoch.h) should be included as well;
84// in adition to general MeasConvert.h.
85//
86// <anchor name="Measure"><h3> Measures</h3></anchor>
87//
88// Measures are physical quantities within a certain reference frame. Examples
89// are the Hour-angle and Declination of a source at a certain time and
90// observatory; an Ra/Dec for a certain mean epoch; an apparent frequency at
91// a certain time given in eV; a local sidereal time at an observatory.<br>
92// Measures can be converted from one reference frame to another (and this
93// possibility is its main reason for existence). A simple B1950-J2000
94// coordinate conversion example:
95// <srcblock>
96// cout << // output
97// // the conversion of a B1950 direction
98// MDirection::Convert( MDirection( Quantity( 20, "deg"),
99// Quantity(-10, "deg"),
100// MDirection::Ref( MDirection::B1950)),
101// // to J2000
102// MDirection::Ref( MDirection::J2000)) ()
103// // where the constructor sets up a conversion
104// // engine, and the operator() converts
105// << endl;
106// </srcblock>
107// or converting an UTC to a local apparent sidereal time:
108// <srcblock>
109// // Set up the model for the input (default reference is UTC)
110// MEpoch model ( Quantity(0., "d"));
111// // Set up the frame with the observatory position
112// MPosition obs( MVPosition( Quantity( 10, "m"),
113// Quantity( -6, "deg"),
114// Quantity( 50, "deg")),
115// MPosition::Ref(MPosition::WGS84));
116// Measframe frame( obs);
117// // Set up the output reference
118// MEpoch::Ref outref( MEpoch::LAST,
119// frame);
120// // Set up conversion
121// MEpoch::Convert toLST( model,
122// outref);
123// // Output a series of sidereal times (formatted in ddd::hh:mm:ss)
124// for (Double d = 12345; d<12346; d += 0.1) {
125// cout << "Converted from UTC to LAST: " <<
126// d << " : " <<
127// toLST(d).getValue() << endl;
128// };
129// </srcblock>
130//
131// The examples show the use of the 5 major classes involved in Measures:
132// <srcblock>
133// Base Example Description
134// ------ --------- -------------
135// Measure MEpoch has a value and a reference
136// MeasValue MVEpoch value
137// MeasRef MEpoch::Ref contains type, frame, offset
138// MeasFrame MeasFrame contains Measures describing frame
139// MeasConvert MEpoch::Convert contains conversion information and engine
140// </srcblock>
141//
142// Each type of Measure has its own distinct class. Each
143// is (weakly) derived from the <linkto class="Measure">Measure</linkto> base
144// class, and its name starts with an <em>M</em>. Examples are:
145// <ul>
146// <li> <linkto class="MEpoch">MEpoch</linkto>: an instance in time
147// <li> <linkto class="MDirection">MDirection</linkto>: a direction in space
148// <li> <linkto class="MPosition">MPosition</linkto>: a position on Earth
149// <li> <linkto class="MFrequency">MFrequency</linkto>: the characteristics
150// of a wave
151// <li> <linkto class="MDoppler">MDoppler</linkto>: a Doppler shift
152// <li> <linkto class="MRadialVelocity">MRadialVelocity</linkto>: a
153// radial velocity
154// <li> <linkto class="MBaseline">MBaseline</linkto>: a baseline
155// <li> <linkto class="Muvw">Muvw</linkto>: a uvw value
156// <li> <linkto class="MEarthMagnetic">MEarthMagnetic</linkto>: an
157// earth magnetic field value
158// </ul>
159// Others are being, or could be, considered.
160// <note role=tip>The current set can be deduced from the class list at the end of
161// the html version of this module description.</note>
162// <p>
163// The main role of the Measure (and related) classes is to be able to convert
164// an observed (or to be calculated) physical entity from one reference frame
165// to another, e.g. a J2000 coordinate to galactic coordinates, or an TAI
166// time to a local sidereal time (LAST).
167// Simple unit conversions (e.g. an angle from mrad to deg), or calculations
168// with values with attached units, are sufficiently catered for by the
169// <linkto module="Quanta">Quanta</linkto> module classes.
170// <p>
171// Each measure has a <em>value</em> (<linkto class=MeasValue>MeasValue</linkto>) and
172// a <em>reference</em> (<linkto class=MeasRef>MeasRef</linkto>).
173// The values are in general measure specific, weakly derived from MeasValue,
174// and named with an initial <em>MV</em>. Examples are:
175// <ul>
176// <li> <linkto class=MVEpoch>MVEpoch</linkto> (a high precision single value),
177// <li> <linkto class=MVDirection>MVDirection</linkto> (direction cosines),
178// <li> <linkto class=MVPosition>MVPosition</linkto> (3-vector positions),
179// <li> <linkto class=MVFrequency>MVFrequency</linkto> (single, unit depended
180// value).
181// <li> <linkto class=MVDoppler>MVDoppler</linkto> (single, unit depended value)
182// <li> <linkto class=MVRadialVelocity>MVRadialVelocity</linkto> (single value)
183// </ul>
184// MeasValue and the MV classes can be found in the
185// <linkto module=Quanta>Quanta</linkto> module.
186// In addition some other value classes, not directly used in measures, are
187// available. Examples:
188// <ul>
189// <li> <linkto class=MVAngle>MVAngle</linkto> (to normalise
190// and have specific I/O formatting for angle-like values)
191// <li> <linkto class=MVTime>MVTime</linkto> (same for time-like values)
192// </ul>
193// <em>References</em> are measure specific. Each specific reference class is
194// called <em>Measure</em>\::Ref (e.g. <src>MEpoch::Ref</src>). It specifies
195// the full reference frame of the specific measure, i.e. its type, an optional
196// frame of measures (a MeasFrame, consisting of say a time and position), and
197// an optional offset.
198// It has at least a <em>reference code</em>
199// (e.g. MDirection::B1950, MEpoch::LAST), with defaults for each measure
200// (i.e. MDirection::J2000, MEpoch::UTC) if none specified. <br>
201// In addition the reference can contain a <em>reference frame</em>
202// (<linkto class=MeasFrame>MeasFrame</linkto>) to specify from when and/or
203// where the measure was obtained or calculated.<br>
204// A third optional element of the reference is an <em>offset measure</em>, which
205// indicates the offset (e.g. a sidereal date) that has to be added to the
206// value referenced before it is used.<br>
207// Examples of some measures are:
208// <srcblock>
209// // An instance of time expressed in days (MJD) in UTC
210// MEpoch date(MVEpoch(Quantity(50237.29, "d")),
211// MEpoch::Ref(MEpoch::UTC));
212// // which could also be expressed as:
213// MEpoch date(Quantity(50237.29, "d"),
214// MEpoch::UTC);
215// // or using the default reference type:
216// MEpoch date(Quantity(50237.29, "d"));
217// // or as a time with an offset to a specific date:
218// MEpoch date(Quantity(12.3, "h"), // time
219// MEpoch::Ref(MEpoch::UTC, // reference with
220// MEpoch(Quantity(50237, "d")))); // offset
221// // A position of a telescope
222// MPosition pos(MVPosition(Quantity(25, "m"), // height
223// Quantity(20, "deg"), // East longitude
224// Quantity(53, "deg")), // lattitude
225// MPosition::WGS84); // reference type
226// // Use this position in a frame
227// MeasFrame frame(pos);
228// // Specify an LAST (in MGSD) observed at this position:
229// MEpoch last(Quantity(51000.234, "d"), // time and date
230// MEpoch::Ref(MEpoch::LAST, // indicate LAST
231// frame)); // and where observed
232// // Maybe we know the MJD of the observed sidereal time,
233// // but not its sidereal date. We could then specify it as an
234// // offset to the beginning of the sidereal day in progress at
235// // specified UTC
236// MEpoch last(Quantity(13.45, "h"), // time
237// MEpoch::Ref(MEpoch::LAST, // indicate LAST
238// frame, // where observed
239// MEpoch(51234, // MJD of today
240// MEpoch::Ref(MEpoch::TAI + MEpoch::RAZE)));
241// // where the RAZE indicates that the value will be truncated after
242// // conversion. In this case it will be converted to LAST to be able
243// // to add it as an offset to the specified LAST
244// //
245// // A direction (in RA/Dec) could be:
246// MDirection coord(MVDirection(Quantity(54, "deg"), // RA
247// Quantity(2034, "'")), // DEC arcmin
248// MDirection::Ref(MDirection::J2000)); // J2000 type
249// // If it were apparent coordinates, the time when observed should
250// // have been known. We could just add it to the frame defined above,
251// // and use it:
252// frame.set(date); // add time to frame
253// MDirection acoord(MVDirection(Quantity(54, "deg"), // RA
254// Quantity(2034, "'")), // DEC
255// MDirection::Ref(MDirection::APP, // apparent type
256// frame)); // and when
257// // If it was given in HA/Dec, the position should have been known
258// // as well, but it is already in the frame, hence we could say:
259// MDirection acoord(MVDirection(Quantity(54, "deg"), // HA
260// Quantity(2034, "'")), // DEC
261// MDirection::Ref(MDirection::HADEC, // type
262// frame)); // when/where
263// </srcblock>
264// <note role=tip>In the above examples in general explicit <em>MV</em>
265// values have been used to specified the measure's value. In many
266// cases (depending on the actual measure) it can be omitted, and the data
267// can be given directly to the measure constructor. See the
268// constructors for the individual measures for details.<br>
269// If the reference is simple (i.e. no frame and/or offset) the
270// <em>Measure::Ref</em> can be omitted, and only the code has to be
271// specified. </note>
272// A <linkto class=MeasFrame>MeasFrame</linkto> is a container for specifying
273// Measures needed to describe the circumstances under which the measure was
274// observed (or for which it has to be calculated).
275// E.g. the position on Earth (an <em>MPosition</em>) is necessary for
276// sidereal time and coordinates like HA/Dec and Az/El; the time
277// (<em>MEpoch</em>)
278// is necessary for non-standard coordinates (apparent, mean, HA/Dec etc);
279// the coordinates (<em>MDirection</em>) for radial velocities; etc.<br>
280// Although quite often the value has to be in a specific format (e.g. TBD for
281// precession calculations; astronomical longitude for the LAST), the
282// frame values can be given in any known reference format: conversion to the
283// appropiate type will be done automatically if and when necessary.<br>
284// Frames (and references) are never copied, but act always as containers
285// with shallow copying only (i.e. <em>copied</em> frames will point to
286// identical instances, and changes made in one copy will be visible in all
287// others. This
288// means, e.g., that in the following:
289// <srcblock>
290// MeasFrame frame1(MEpoch(50236.12));
291// MeasFrame frame2(frame1);
292// </srcblock>
293// the two frames will be identical, and a change to one means a change to
294// the other. Furthermore, only the information needed for a specific
295// calculation will be used (and calculated). This means that one frame can
296// be used specifying all of e.g. the position (which will probably stay the
297// same for a series of calculations) and time; with the time being <em>set()</em>
298// (if also the reference of the epoch changes) or <em>resetEpoch()</em> (if only
299// the value changes, but the reference and its frame stay the same).
300// A change in the frame will influence automatically any calculation (e.g.
301// conversion to LAST) of which it is part.<br>
302//
303// The value of a measure (in <em>MV</em> format) can be obtained with the
304// <em>getValue()</em> member function. The value in a variety of formats
305// and units can be obtained with a (specific Measure dependent) series of
306// <em>get()</em> members of both the <em>MV</em>-value and the Measure.<br>
307//
308// Measures in themselves are not really necessary for proper data reduction
309// and the like. Its real value is the ability to transform a Measure from
310// one reference type (and frame, offset) to another.<br>
311// Conversion of a measure of a certain kind from one reference to another
312// is done with the aid of special, measure specific,
313// <linkto class=MeasConvert>MeasConvert</linkto> classes. Each conversion
314// class is called <em>Measure</em>\::Convert (e.g. MDirection::Convert).
315// A conversion generates from an input reference (or an input measure) and
316// an output reference a conversion functional, that can be used to convert
317// specific values.<br>
318// Example:
319// <srcblock>
320// cout << // output
321// // the conversion of a B1950 direction
322// MDirection::Convert( MDirection( Quantity( 20, "deg"),
323// Quantity(-10, "deg"),
324// MDirection::Ref( MDirection::B1950)),
325// // to J2000
326// MDirection::Ref( MDirection::J2000)) ()
327// // where the constructor sets up a conversion
328// // engine, and the operator() converts
329// << endl;
330//</srcblock>
331// The same could have been done by only setting up the conversion engine, and
332// not specifing the default value to be converted in the Convert constructor
333// by:
334// <srcblock>
335// cout << // output
336// // the conversion of a B1950 direction
337// MDirection::Convert(MDirection::Ref( MDirection::B1950),
338// // to J2000
339// MDirection::Ref( MDirection::J2000))
340// // and use conversion on value
341// (MVDirection( Quantity( 20, "deg"),
342// Quantity(-10, "deg")))
343// // where the operator() converts
344// << endl;
345// </srcblock>
346// Specifying the conversion engine separately, it can be re-used for other
347// values:
348// <srcblock>
349// MDirection::Convert conv(MDirection::Ref( MDirection::B1950),
350// MDirection::Ref( MDirection::J2000));
351// // We have some coordinates from somewhere, say coord(0:N-1):
352// for (Int i=0; i<N; i++) {
353// cout << "B1950: " << coord(i) << "= J2000: " <<
354// conv(coord(i)) << endl;
355// };
356// </srcblock>
357// A larger example. Say you have the J2000 coordinates for a source (RA=11
358// deg, DEC= -30 deg), and you want to observe it on May 17, 1996 (MJD=50220)
359// at 8:18 UTC in a place
360// with a Longitude of 150 deg (latitude of 20 deg) at 1000 m high,
361// you could get the
362// apparent RA,DEC, and the LAST at that time (you could also go straight to
363// HA/DEC or so) with (I write the example longer than necessary to indicate
364// the steps, and with explicit reference to MV values):
365// <srcblock>
366// // The observatory position. Note that the reference is geodetic position
367// MPosition myobs(MVPosition ( Quantity(1, "km") ,
368// Quantity(150, "deg"),
369// Quantity(20, "deg")),
370// MPosition::WGS84);
371// // The time I want to observe (note that it could be specified in many
372// // other ways)
373// MEpoch obstime(MVEpoch(MVTime(1996, 5, 17, (8+18./60.)/24.)),
374// MEpoch::UTC);
375// // The frame specification for when and where to observe
376// MeasFrame frame(myobs, obstime);
377// // The reference for a sidereal time (note the frame could be empty and
378// // filled at the actual conversion time)
379// MEpoch::Ref sidref( MEpoch::LAST, frame);
380// // The reference for apparent coordinates:
381// MDirection::Ref appref( MDirection::APP, frame);
382// // The conversion engine for my time to LAST
383// MEpoch::Convert tosid(obstime, sidref);
384// // The conversion to sidereal time of obstime
385// MEpoch sidtime = tosid();
386// // Conversion of UTC 10.8 h
387// sidtime = tosid(MVEpoch(MVTime(1996, 5, 17, 10.8/24.)));
388// // Show me some time
389// cout << "LAST for UTC = 11:00: " <<
390// tosid(MVEpoch( MVTime( 1996, 5, 17, 11, 0))) << endl;
391// // An offset reference (note the RAZE will keep only the integer part of
392// // the day for the conversion result)
393// MEpoch::Ref offtime(obstime.getValue(), MEpoch::UTC+MEpoch::RAZE);
394// // The reference for a sidereal with respect to a specified offset (note
395// // that it is automatically calculated into correct units)
396// MEpoch::Ref sidoffref(MEpoch::LAST, frame, offtime);
397// // Show the offset result
398// cout << "LAST today: " <<
399// MEpoch::Convert(11., sidoffref)() << endl;
400// // Coordinate conversion from J2000
401// cout << "Apparent coordinates: " <<
402// MDirection::Convert ( MDirection(Quantum(11,"deg"),
403// Quantum(-30, "deg")),
404// MDirection::Ref( MDirection::APP,
405// frame))() << endl;
406// // Handier to have the conversion engine available
407// MDirection::Convert cvt( MDirection(Quantum(11,"deg"),
408// Quantum(-30, "deg")),
409// MDirection::Ref( MDirection::APP,
410// frame));
411// // Set another frame time (note it is now sidereal, not UTC. The
412// // frame will automatically convert it (using the frame again for
413// // position) to TDB for precession etc calculations).
414// frame.set(sidtime);
415// // And look what same position is at this new time
416// cout << "Next position: " << cvt() << endl;
417// </srcblock>
418// <p>
419// Some conversions need maybe some fine tuning (e.g. what is the acceptable
420// interval for Nutation linear interpolation: could be different from the
421// default interval; some time calculations will want to use the predicted
422// IERS values rather than the actual determined; some Nutation will maybe
423// use the IERS updates, some maybe the JPL DE databases).<br>
424// The <linkto class=AipsrcValue>AipsrcValue</linkto> class can be used to
425// specify very specific parameters that are used to steer
426// the conversion process beyond what is possible with just a list
427// of measure reference types (that list is already long for some cases).
428// Values, switches can be <src>set()</src> (and removed) to change the
429// default behaviour of the conversions. In general the user will only need
430// to use the details in very specific cases. The details that can be used
431// are described in the classes that provide calculations (e.g.
432// <linkto class=Nutation>Nutation</linkto>), and in the aipsrc-data reference
433// manual entry.<br>
434// <p>
435// Some details about the different classes follows. In the examples often
436// a specific measure value (e.g. MVEpoch, the MeasValue for MEpoch), or a
437// specific measure (e.g. MDirection, a direction in space) is used. This
438// is only to visualise the use, any other measure could have been used.
439// <p>
440// <h4> MeasValue</h4>
441// The MeasValue class derivatives are all named <em>MVmeasure</em>, e.g.
442// <em>MVFrequency</em>, and represent the internal representation of the
443// specific measure class. Details
444// can be found in the <linkto module=Quanta>Quanta</linkto> module.
445// <p>
446// <h4> Measure</h4>
447// The Measure class derivatives are all called <em>MMeasure</em>.
448// <linkto class=MDirection>MDirection</linkto> (a celestial direction),
449// <linkto class=MPosition>MPosition</linkto> (a position on Earth),
450// <linkto class=MFrequency>MFrequency</linkto> (characteristics of
451// electro-magnetic wave),
452// <linkto class=MEpoch>MEpoch</linkto> (an instance in time),
453// <linkto class=MDoppler>MDoppler</linkto>,
454// <linkto class=MRadialVelocity>MRadialVelocity</linkto>
455// <linkto class=MBaseline>MBaseline</linkto>,
456// <linkto class=Muvw>Muvw</linkto>,
457// <linkto class=MEarthMagnetic>MEarthMagnetic</linkto>,
458//. <br>
459// A measure has a value (kept in internal units in <em>MVmeasure</em>
460// format) and a definition
461// of the reference frame (MeasRef) of the value. The reference is optional, and
462// will default to <em>Measure::DEFAULT</em>.<br>
463// All measures have a set of standard constructors:
464// <srcblock>
465// M(); // some default, e.g. pole directoon, time ==0)
466// M(MV, MeasRef);
467// M(Quantity, MeasRef);
468// M(Quantum<Vector<Double> >, MeasRef);
469// M(Vector<Quantity>, MeasRef);
470// </srcblock>
471// But also some special ones (e.g. two Quantities for MDirection to specify
472// two angles) depending on type. The MeasRef can be omitted (will then be
473// defaulted to Measure::DEFAULT, e.g. MEpoch::DEFAULT); can be specified as
474// a full reference as a <em>Measure::Ref</em> (e.g. <em>MDirection::Ref</em>)
475// type; or as a simple reference as <em>Measure::TYPE</em> (e.g.
476// <em>MDirection::J2000</em>).<br>
477// The individual elements of a Measure (i.e the MV value and the reference)
478// can be overwritten (or set) with the <src>set()</src> methods.<br>
479// <src>get()</src> methods (in general <src>get(unit)</src>
480// to return the internal value in some
481// specified unit as a Quantum; and methods like <src>getAngle()</src>
482// for e.g. MDirection)
483// enable the user to obtain the value of the measure.<br>
484// A <src>String tellMe()</src> will tell the type of Measure; a
485// <src>void assured(String)</src> and <src>Bool areYou(String)</src> will
486// check the type; while a <src>String showType(Measure::TYPE)</src> will
487// return the string value of a reference type code (e.g. J2000).<br>
488// <p>
489// Recall that a Measure is a value with a reference specified. The MeasConvert
490// engines enable you to convert it into another Measure, with a different
491// reference (e.g. from J2000 to AZEL). The different get() methods (either
492// directly, or indirectly using additional MV get() functions, or
493// Quantum conversion methods, can convert the internal value into a value
494// (or values) with user preferred units.<br>
495// For reasons of speed (and safety) the allowed reference types for each
496// Measure are enumerated in each measure class. The different reference
497// types for MDirection are, for example:
498// <srcblock>
499// MDirection::J2000,
500// MDirection::JMEAN,
501// MDirection::JTRUE,
502// MDirection::APP,
503// MDirection::B1950,
504// MDirection::BMEAN,
505// MDirection::BTRUE,
506// MDirection::GALACTIC,
507// MDirection::HADEC,
508// MDirection::AZEL,
509// MDirection::DEFAULT = MDirection::J2000
510// </srcblock>
511// The MEpoch has a special reference type (<src>MEpoch::RAZE</src>) that
512// can only be used
513// in conjuncion with another reference type
514// (e.g. <src> MEpoch::UT1+MEpoch::RAZE)</src>.
515// The meaning is: if a measure with such a reference type is converted to
516// another reference type (say <src>MEpoch::LAST</src>) the
517// resultant (sidereal time)
518// instance will be <em>razed</em> to an integer number of days; hence providing
519// an easy way to specify sidereal times offset with the beginning of the
520// current sidereal day.<br>
521// To aid with external data, a <src>Bool giveMe(String, uInt)</src> will
522// give the correct reference type to be used given the String type.
523// Note that the
524// uInt, rather than the corresponding enum is used, due to templating
525// restrictions in some compilers.<br>
526// The correct reference (MeasRef) and conversion (MeasConvert) class for
527// each Measure (a frequency cannot be converted into an epoch) are templated,
528// and have specified (and to be used) typedefs: <em>Measure::Ref</em> and
529// <em>Measure::Convert</em> (e.g. <em>MEpoch::Ref, MEpoch::Convert</em>). In
530// addition, Measure::MVType and Measure::MCType are defined for all
531// measures.
532// <p>
533// <h4>Measure errors </h4>
534// In the current implementation, no errors are attached to a Measure. In the
535// original design errors were foreseen, but up till now they have been left
536// out.<br>
537// The addition of errors is in principle an easy process. They could be
538// attached to either a Measure (as an additial MV value), or the MV's could
539// be expanded to include errors (my preferred option at the moment). An
540// MV being converted will then automatically have its error converted as
541// well.<br>
542// Before implementing, however, I think it would be worthwhile to look at
543// the whole area of error handling. The easiest way would be to introduce
544// for each of the defined Casacore standard values a corresponding E class
545// (EDouble, EInt, EComplex, EuInt etc), and have all mathematical and
546// logical operators that are defined for the standard classes be defined
547// for the E-classes as well. It would then be easy to introduce errors
548// everywhere.
549// <p>
550// <h4>MeasFrame</h4>
551// A MeasFrame is a container with the instance of time
552// (an MEpoch) and/or the position (an MPosition) for a measure reference.
553// (Other Measures, like MDirection and MRadialVelocity are sometimes needed
554// as well).
555// MeasFrames are never actually copied, but only referred to (<em>shallow copy</em>)
556// , so they can be used for all different types
557// of measure reference. They are only necessary, but then essential, if the
558// reference type does not fully specify the frame (like e.g. MDirection::J2000,
559// or MEpoch::TAI do). Examples are the position necessary to go to
560// MEpoch::LAST, the epoch necessary to go to MDirection::APP, the epoch and
561// position necessary to reference an MDirection::AZEL.<br>
562// A MeasFrame can be constructed empty (and used in references, as long as it
563// is filled properly at the time of an actual conversion), or with one or
564// Measures already defined with: <src>MeasFrame frame(a_Measure, ...)</src>.
565// It can be filled, or re-filled, with <src>set(a_measure,....)</src>.<br>
566// The conversion routines use different values of the frame values given (e.g.
567// the precession and nutation will need the epoch in TDB time, the hour-angle
568// constructor local apparent sidereal time, which needs the astronomical
569// longitude etc.). For that reason the specification of an epoch or position
570// in either the constructor or the set() will create conversion engines for
571// conversion of the input measure to all appropiate values that can be asked
572// by the conversion routines. Note that the actual conversion is only done
573// when that value is requested (and is then saved for later use). It is,
574// therefore, safe and probably good practice to have one frame in a certain
575// conversion environment, filled with as much info as is needed at that stage.<br>
576// To aid and speed up, <src>resetEpoch()</src> and <src>resetPosition()</src>
577// methods are available. As arguments they accept the corresponding
578// MV or a variety of Double and Quantum arguments to reset the <em>value</em>
579// of the corresponding frame measure only. In that case the conversion engine
580// won't be redesigned, leading to fast recalculation when necessary, since
581// e.g. nutation values could be re-used.<br>
582// In an observing environment you could hence setup a proper frame with the
583// Observatory position, and an observing day offset (see MeasRef) time; and
584// do resetEpoch() to update the time if and when necessary.<br>
585// <p>
586// <h4>MeasRef</h4>
587// A MeasRef is a measure specific container (and its class reference is
588// <src>Measure::Ref</src>, e.g. <src>MFrequency::Ref</src>) with the
589// measure reference type (e.g. <src>MEpoch::UTC</src>), an optional (but in
590// some cases necessary) MeasFrame (e.g. to specify where the sidereal time
591// was determined), and, just for convenience, an optional offset (e.g.
592// the MJD for which the time specified in the MEpoch referenced is valid).
593// Note that if no frame or offset is necessary, the <src>Measure::TYPE</src>
594// can be used everywhere where a <src>Measure::Ref</src> is needed.<br>
595// A MeasRef is never copied (all copying and so is done by referencing). This
596// means, for example, that if a specific MeasRef is part of the MEpoch
597// definition for an epoch that is part of a MeasFrame, and you chnage that
598// MeasRef, the change will automatically occur wherever that MeasRef is
599// used (as e.g. in the frame). In most cases that is the expected response,
600// but you should be aware of it, and not re-use a MeasRef for a completely
601// different purpose.<br>
602// A simple example:
603// <srcblock>
604// MEpoch mytime(MVEpoch(50236.5), MEpoch::UTC);
605// // this will define a time in UTC on MJD 50236, 12 hours. The MVEpoch
606// // explicit conversion could be left out for most compilers, but some
607// // have trouble with automatic conversions.
608// // Another way of doing it would be to use Quantities, which have
609// // explicit constructors for all measures:
610// MEpoch mytime(Quantity(50236.5, "d"));
611// </srcblock>
612// A slighty more involved example, written out a bit:
613// <srcblock>
614// // Specify the location of the observatory (10m high, at given longitude
615// // and latitude as geodetic position)
616// MPosition obs( MVPosition( Quantity( 10, "m"),
617// Quantity( -6, "deg"),
618// Quantity( 52, "deg")),
619// MPosition::WGS84);
620// // If the current time is MJD50236, 12.3 h UTC, it could be specified as:
621// MEpoch tim( MVEpoch( Quantity( 50236, "d"),
622// Quantity( 12.3, "h")));
623// // Note the default reference
624// // For this example we will also specify it as:
625// MEpoch offtim(tim);
626// offtim.set(MEpoch::DEFAULT+MEpoch::RAZE);
627// // These two could define a frame
628// MeasFrame frame(tim, obs);
629// // Or maybe as (since observatory will stay put)
630// MeasFrame frame1(obs);
631// // and later addition of some time and its reference frame
632// frame1.set(tim);
633// // with a change to another time value at a later stage with
634// frame1.resetEpoch( MVEpoch( Quantity( 50236, "d"),
635// Quantity( 13, "h")));
636// // At this time we observe a sidereal time of 2.3 h. The actual instance
637// // of time needs a sidereal date to specify, but we are too lazy to
638// // look it up, hence we specify that this time has an offset, equal to
639// // the sidereal time at offtim (which with the RAZE addition will be
640// // converted to an integral number of days in whatever time it is
641// // converted to)
642// MEpoch mylast( MVEpoch( Quantity( 2.3, "h")),
643// MEpoch::Ref( MEpoch::LAST,
644// frame,
645// offtim));
646// // Which specifies that we have a Local apparent sidereal time of 2.3 h
647// // at the position specified by obs in the frame, at an offset offtim.
648// // Note that the offset is given in UTC (and RAZE). Any conversion of
649// // this mylast value to any other reference type, will always auto start
650// // with a conversion of the offset to the current type (i.e LAST (with
651// // the RAZE taking the integer part only)), and adding it to the value
652// // given. Note that if an output reference has an offset, the resulting
653// // value will be corrected for the specified offset as well.
654// </srcblock>
655// The reference type can be set with a set() function, and set() functions
656// for the offset and frame will be present as well.<br>
657// A <src>Bool empty()</src> checks if the reference is empty; <src>get()</src>
658// functions provide the information in the reference; and a
659// <src>String showMe()</src> will return the type of measure (e.g. "Epoch") the
660// MeasRef can be used for.
661//<p>
662// <h4>MeasConvert</h4>
663// The MeasConvert class converts Measures from one reference type and frame
664// to another.
665// It gathers all relevant
666// information and analyses it to have fast multiple conversions.
667// The MeasConvert classes are Measure specific, and should be used with
668// the class names <src>Measure::Convert</src> (e.g. <src>MFrequency::Convert
669// </src>).
670// The () operator will do the actual conversion; constructors and set()
671// methods will only fill the information necessary to do the conversion.
672// MeasConvert is a non-copying container.<br>
673// To set up the conversion engine, the MeasConvert object has to know the
674// input data reference (remember the MeasRef contains information about the
675// type, the possible reference frame and a possible offset), and an output
676// reference. Using these references it will communicate with the appropiate
677// Measure class to set up a series of routines that have to be executed in
678// order to attain the goal. (Note that if the input and output reference
679// both define a frame, but different ones, e.g. because you want to convert
680// a sidereal time at one place to a sidereal time at another place, the
681// conversion machinery will always first go to the proper default (UTC in this
682// case), and then go to the goal).<br>
683// The actual conversion need a value to be converted, and it also can use
684// a default Unit, so that if your frequencies are in nm, you can once
685// specify that they are nm, and then simply convert a Double.<br>
686// This means that the optimal constructor for a MeasConvert is:
687// <srcblock>
688// // The first argument will give the input reference, and, if a Quantum is
689// // used to make the Measure, the default units for inputs to the conversion.
690// // It acts as a 'model' for subsequent input to be converted.
691// // () operator
692// Measure::Convert( Measure(Quantum),
693// // the second argument gives the output reference
694// Measure::Ref);
695// </srcblock>
696// The actual constructors present include ones with the first argument only
697// an input reference, rather than a full Measure.
698// However, in all cases an empty or partial one can be constructed, with set()
699// functions filling in the rest. The conversion engine is only
700// (re-)setup if at least an input and output reference can be found.<br>
701// After setting up the conversion engine, the () operator can be used with
702// a variety of values to return a converted Measure. Possibilities are:
703// <srcblock>
704// () // convert the value as specified in the 'model'
705// (Double) // convert the value first to appropiate units (if they
706// // were implicit in 'model' or explicitly set), and
707// // then convert
708// (Vector<Double>)// as Double
709// (Quantity) // convert the full value, including its own units
710// (Quantum<Vector<Double> >) // as Quantity
711// (MeasValue) // convert the specified appropiate MV
712// (Measure) // set up a new conversion chain, using the value as
713// // 'model', and the old output reference,
714// // and then convert
715// (Measure, Measure::Ref) // set up a new conversion chain for the
716// // 'model' given and the output reference given
717// (Measure::Ref) // set up a new conversion chain using the old 'model'
718// // and the output reference given, and convert the
719// // existing model value
720// </srcblock>
721// A simple example to output the J2000 coordinates for a B1950 input (RA=20 deg,
722// DEC=-10 deg):
723// <srcblock>
724// cout <<
725// MDirection::Convert( MDirection( Quantity( 20, "deg")
726// Quantity(-10, "deg"),
727// MDirection::Ref( MDirection::B1950)),
728// MDirection::Ref( MDirection::J2000)) () << endl;
729// </srcblock>
730// In this example everything is done in one go (the () at the end does the
731// conversion). Another example, to have a UTC to LAST converter:
732// <srcblock>
733// // Set up the model for the input (default reference is UTC)
734// MEpoch model ( Quantity(0., "d"));
735// // Set up the frame with the observatory position
736// MPosition obs( MVPosition( Quantity( 10, "m"),
737// Quantity( -6, "deg"),
738// Quantity( 50, "deg")),
739// MPosition::Ref(MPosition::WGS84));
740// Measframe frame( obs);
741// // set up the output reference
742// MEpoch::Ref outref( MEpoch::LAST,
743// frame);
744// // Set up conversion
745// MEpoch::Convert toLST( model,
746// outref);
747// // Output a series of sidereal times (formatted in ddd::hh:mm:ss)
748// for (Double d = 12345; d<12346; d += 0.1) {
749// cout << "Converted from UTC to LAST: " <<
750// d <<
751// toLST(d).getValue() << endl;
752// };
753// </srcblock>
754// <p>
755// For specific purposes it would be very easy to set up a series of simple
756// classes, that would do standard conversions.
757// <p>
758// <h4> MeasData, MeasTable, MeasBase, other help classes</h4>
759// A series of help classes are present to aid in the conversion, especially
760// caching information. They are of no direct use for the end user (except
761// maybe a few constants in MeasData).<br>
762// The classes are:
763// <ul>
764// <li> <linkto class=MeasBase>MeasBase</linkto>:
765// base class (derived from Measure) for all real Measures
766// <li> <linkto class=MeasData>MeasData</linkto>:
767// all constants, polynomial factors, interface to IERS
768// database etc. which are not stored in Tables. (MeasTable looks after
769// these). Mn short it provides all the actual data values necessary
770// for the conversions (and the other help classes)
771// <li> <linkto class=MeasTable>MeasTable</linkto>:
772// interface for all data that comes from Tables rather than
773// the program
774// <li> <linkto class=MeasIERS>MeasIERS</linkto>:
775// (static) class to converse with the IERS database(s)
776// <li> <linkto class=MeasJPL>MeasJPL</linkto>:
777// (static) class to converse with the JPL DE database(s)
778// <li> <linkto class=Precession>Precession</linkto>:
779// all precession related calculations
780// <li> <linkto class=Nutation>Nutation</linkto>
781// <li> <linkto class=Aberration>Aberration</linkto>
782// <li> <linkto class=SolarPos>SolarPos</linkto>:
783// all solarposition related calculations
784// <li> <linkto class=Euler>Euler</linkto>:
785// representation of Euler rotation angles
786// <li> <linkto class=RotMatrix>RotMatrix</linkto>: a 3-D rotation matrix
787// </ul>
788// <p>
789
790// </synopsis>
791//
792// <motivation>
793// The Measures module originated to be able to convert ccordinates between
794// different reference frames.
795// </motivation>
796//
797// <todo asof="1998/07/22">
798// <li> inlining
799// </todo>
800//
801// <example>
802// See the individual measures for appropiate examples.
803// </example>
804// </module>
805
806//# Dummy class definition for extractor
807//# class Measures {};
808
809
810} //# NAMESPACE CASACORE - END
811
812#endif
this file contains all the compiler specific defines
Definition mainpage.dox:28