casacore
measures
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.<br>
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><br>
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>).<br>
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).<br>
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
casacore
this file contains all the compiler specific defines
Definition:
mainpage.dox:28
Generated by
1.8.18