casacore
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 
40 namespace 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