Measures.h

Go to the documentation of this file.
00001 //# Measures.h:  a module for coordinates
00002 //# Copyright (C) 1994,1995,1996,1997,1998,1999,2000,2002
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id$
00027 
00028 #ifndef MEASURES_MEASURES_H
00029 #define MEASURES_MEASURES_H
00030 
00031 //# Includes
00032 #include <casacore/casa/aips.h>
00033 #include <casacore/casa/Quanta.h>
00034 #include <casacore/measures/Measures/Measure.h>
00035 #include <casacore/measures/Measures/MeasBase.h>
00036 #include <casacore/casa/Quanta/MeasValue.h>
00037 #include <casacore/measures/Measures/MeasRef.h>
00038 #include <casacore/measures/Measures/MeasConvert.h>
00039 
00040 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00041 
00042 // <module>
00043 // 
00044 
00045 // <summary> a module for coordinates </summary>
00046 
00047 // <use visibility=export>
00048 
00049 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tMeasMath tMeasure"
00050 //       demos="dMeasure">
00051 
00052 // <prerequisite>
00053 //   <li> <linkto module=Quanta>Quanta</linkto> module for units and quantities.
00054 // </prerequisite>
00055 
00056 // <etymology>
00057 // The name Measure derives from physical measurements, i.e. values with
00058 // units and possibly a reference frame attached.
00059 // </etymology>
00060 //
00061 // <synopsis> 
00062 // The Measure model deals with measures (i.e. quantities with a
00063 // reference frame).
00064 // Measures are handled in the <a href="#Measure">Measure</a> section
00065 // (see <linkto class="Measure">Measure.h</linkto>).
00066 //
00067 // <h3> Includes</h3>
00068 // Including the <src>measures/Measures.h</src> will take care of all
00069 // includes necessary for the handling of Units and Quantities, and the
00070 // general Measure interface. For the use of individual Measures, the
00071 // appropiate include files should be added. E.g. to be able to handle
00072 // Directions, the following includes could be given:
00073 // <srcblock>
00074 //      #include <casacore/measures/Measures.h>
00075 //      #include <casacore/measures/Measures/MDirection.h>
00076 // </srcblock>
00077 // An inclusion of the appropiate measure file, will also take care of the
00078 // connected measure value (in this case <src>MVDirection</src>). However,
00079 // if only the value suffices, it can be included on its own (from the
00080 // Quanta directory).<br>
00081 // When doing actual conversions (see MeasConvert later on), by using the
00082 // explicit Measure::Convert types, the description of the actual
00083 // conversions (called MCmeasure, e.g. MCEpoch.h) should be included as well;
00084 // in adition to general MeasConvert.h. 
00085 //
00086 //  <anchor name="Measure"><h3> Measures</h3></anchor>
00087 //
00088 // Measures are physical quantities within a certain reference frame. Examples
00089 // are the Hour-angle and Declination of a source at a certain time and 
00090 // observatory; an Ra/Dec for a certain mean epoch; an apparent frequency at
00091 // a certain time given in eV; a local sidereal time at an observatory.<br>
00092 // Measures can be converted from one reference frame to another (and this
00093 // possibility is its main reason for existence). A simple B1950-J2000
00094 // coordinate conversion example:
00095 // <srcblock>
00096 //  cout <<                     // output
00097 //                              // the conversion of a B1950 direction
00098 //      MDirection::Convert( MDirection( Quantity( 20, "deg"),
00099 //                                       Quantity(-10, "deg"),
00100 //                                       MDirection::Ref( MDirection::B1950)),
00101 //                              // to J2000
00102 //                           MDirection::Ref( MDirection::J2000)) () 
00103 //                              // where the constructor sets up a conversion
00104 //                              // engine, and the operator() converts
00105 //              << endl;
00106 // </srcblock>
00107 // or converting an UTC to a local apparent sidereal time:
00108 // <srcblock>
00109 //  // Set up the model for the input (default reference is UTC)
00110 //      MEpoch model (  Quantity(0., "d"));
00111 //  // Set up the frame with the observatory position
00112 //      MPosition obs(  MVPosition(     Quantity( 10, "m"),
00113 //                                      Quantity( -6, "deg"),
00114 //                                      Quantity( 50, "deg")),
00115 //                      MPosition::Ref(MPosition::WGS84));
00116 //      Measframe frame( obs);
00117 //  // Set up the output reference
00118 //      MEpoch::Ref outref(     MEpoch::LAST,
00119 //                              frame);
00120 //  // Set up conversion
00121 //      MEpoch::Convert toLST(  model,
00122 //                              outref);
00123 //  // Output a series of sidereal times (formatted in ddd::hh:mm:ss)
00124 //      for (Double d = 12345; d<12346; d += 0.1) {
00125 //        cout << "Converted from UTC to LAST: " <<
00126 //              d <<  " : " <<
00127 //              toLST(d).getValue() << endl;
00128 //      };
00129 // </srcblock>
00130 //
00131 // The examples show the use of the 5 major classes involved in Measures:
00132 // <srcblock>
00133 //   Base         Example               Description
00134 //  ------       ---------             -------------
00135 //  Measure      MEpoch          has a value and a  reference
00136 //  MeasValue    MVEpoch         value
00137 //  MeasRef      MEpoch::Ref     contains type, frame, offset
00138 //  MeasFrame    MeasFrame       contains Measures describing frame
00139 //  MeasConvert  MEpoch::Convert contains conversion information and engine
00140 // </srcblock>
00141 //
00142 // Each type of Measure has its own distinct class. Each
00143 // is (weakly) derived from the <linkto class="Measure">Measure</linkto> base
00144 // class, and its name starts with an <em>M</em>. Examples are:
00145 // <ul>
00146 //   <li> <linkto class="MEpoch">MEpoch</linkto>: an instance in time
00147 //   <li> <linkto class="MDirection">MDirection</linkto>: a direction in space
00148 //   <li> <linkto class="MPosition">MPosition</linkto>: a position on Earth
00149 //   <li> <linkto class="MFrequency">MFrequency</linkto>: the characteristics
00150 //              of a wave
00151 //   <li> <linkto class="MDoppler">MDoppler</linkto>: a Doppler shift
00152 //   <li> <linkto class="MRadialVelocity">MRadialVelocity</linkto>: a 
00153 //              radial velocity
00154 //   <li> <linkto class="MBaseline">MBaseline</linkto>: a baseline
00155 //   <li> <linkto class="Muvw">Muvw</linkto>: a uvw value
00156 //   <li> <linkto class="MEarthMagnetic">MEarthMagnetic</linkto>: an
00157 //               earth' magnetic field value
00158 // </ul>
00159 // Others are being, or could be, considered.<br>
00160 // <note role=tip>The current set can be deduced from the class list at the end of
00161 // the html version of this module description.</note><br>
00162 // <p>
00163 // The main role of the Measure (and related) classes is to be able to convert
00164 // an observed (or to be calculated) physical entity from one reference frame
00165 // to another, e.g. a J2000 coordinate to galactic coordinates, or an TAI
00166 // time to a local sidereal time (LAST).
00167 // Simple unit conversions (e.g. an angle from mrad to deg), or calculations
00168 // with values with attached units, are sufficiently catered for by the
00169 // <linkto module="Quanta">Quanta</linkto> module classes.
00170 // <p>
00171 // Each measure has a <em>value</em> (<linkto class=MeasValue>MeasValue</linkto>) and
00172 // a <em>reference</em> (<linkto class=MeasRef>MeasRef</linkto>).<br>
00173 // The values are in general measure specific, weakly derived from MeasValue,
00174 // and named with an initial <em>MV</em>. Examples are:
00175 // <ul>  
00176 // <li> <linkto class=MVEpoch>MVEpoch</linkto> (a high precision single value), 
00177 // <li> <linkto class=MVDirection>MVDirection</linkto> (direction cosines), 
00178 // <li> <linkto class=MVPosition>MVPosition</linkto> (3-vector positions),
00179 // <li> <linkto class=MVFrequency>MVFrequency</linkto> (single, unit depended
00180 // value).<br>
00181 // <li> <linkto class=MVDoppler>MVDoppler</linkto> (single, unit depended value)
00182 // <li> <linkto class=MVRadialVelocity>MVRadialVelocity</linkto> (single value)
00183 // </ul>
00184 // MeasValue and the MV classes can be found in the
00185 // <linkto module=Quanta>Quanta</linkto> module.
00186 // In addition some other value classes, not directly used in measures, are
00187 // available. Examples:
00188 // <ul>
00189 //  <li> <linkto class=MVAngle>MVAngle</linkto> (to normalise
00190 // and have specific I/O formatting for angle-like values)
00191 // <li> <linkto class=MVTime>MVTime</linkto> (same for time-like values)
00192 // </ul>
00193 // <em>References</em> are measure specific. Each specific reference class is
00194 // called <em>Measure</em>\::Ref (e.g. <src>MEpoch::Ref</src>). It specifies
00195 // the full reference frame of the specific measure, i.e. its type, an optional
00196 // frame of measures (a MeasFrame, consisting of say a time and position), and
00197 // an optional offset.
00198 // It has at least a <em>reference code</em>
00199 // (e.g. MDirection::B1950, MEpoch::LAST), with defaults for each measure
00200 // (i.e. MDirection::J2000, MEpoch::UTC) if none specified. <br>
00201 // In addition the reference can contain a <em>reference frame</em> 
00202 // (<linkto class=MeasFrame>MeasFrame</linkto>) to specify from when and/or
00203 // where the measure was obtained or calculated.<br>
00204 // A third optional element of the reference is an <em>offset measure</em>, which
00205 // indicates the offset (e.g. a sidereal date) that has to be added to the
00206 // value referenced before it is used.<br>
00207 // Examples of some measures are:
00208 // <srcblock>
00209 //      // An instance of time expressed in days (MJD) in UTC
00210 //      MEpoch date(MVEpoch(Quantity(50237.29, "d")),
00211 //                  MEpoch::Ref(MEpoch::UTC));
00212 //      // which could also be expressed as:
00213 //      MEpoch date(Quantity(50237.29, "d"),
00214 //                  MEpoch::UTC);
00215 //      // or using the default reference type:
00216 //      MEpoch date(Quantity(50237.29, "d"));
00217 //      // or as a time with an offset to a specific date:
00218 //      MEpoch date(Quantity(12.3, "h"),                // time
00219 //                  MEpoch::Ref(MEpoch::UTC,            // reference with
00220 //                              MEpoch(Quantity(50237, "d"))));  // offset
00221 //      // A position of a telescope
00222 //      MPosition pos(MVPosition(Quantity(25, "m"),     // height
00223 //                               Quantity(20, "deg"),   // East longitude
00224 //                               Quantity(53, "deg")),  // lattitude
00225 //                    MPosition::WGS84);                // reference type
00226 //      // Use this position in a frame
00227 //      MeasFrame frame(pos);
00228 //      // Specify an LAST (in MGSD) observed at this position:
00229 //      MEpoch last(Quantity(51000.234, "d"),           // time and date
00230 //                  MEpoch::Ref(MEpoch::LAST,           // indicate LAST
00231 //                              frame));                // and where observed
00232 //      // Maybe we know the MJD of the observed sidereal time,
00233 //      // but not its sidereal date. We could then specify it as an
00234 //      // offset to the beginning of the sidereal day in progress at
00235 //      // specified UTC
00236 //      MEpoch last(Quantity(13.45, "h"),               // time
00237 //                  MEpoch::Ref(MEpoch::LAST,           // indicate LAST
00238 //                              frame,                  // where observed
00239 //                              MEpoch(51234,           // MJD of today
00240 //                                     MEpoch::Ref(MEpoch::TAI + MEpoch::RAZE)));
00241 //      // where the RAZE indicates that the value will be truncated after
00242 //      // conversion. In this case it will be converted to LAST to be able
00243 //      // to add it as an offset to the specified LAST
00244 //      //
00245 //      // A direction (in RA/Dec) could be:
00246 //      MDirection coord(MVDirection(Quantity(54, "deg"),       // RA
00247 //                                   Quantity(2034, "'")),      // DEC arcmin
00248 //                       MDirection::Ref(MDirection::J2000));   // J2000 type
00249 //      // If it were apparent coordinates, the time when observed should
00250 //      // have been known. We could just add it to the frame defined above,
00251 //      // and use it:
00252 //      frame.set(date);                                // add time to frame
00253 //      MDirection acoord(MVDirection(Quantity(54, "deg"),      // RA
00254 //                                    Quantity(2034, "'")),     // DEC
00255 //                        MDirection::Ref(MDirection::APP,      // apparent type
00256 //                                        frame));              // and when
00257 //      // If it was given in HA/Dec, the position should have been known
00258 //      // as well, but it is already in the frame, hence we could say:
00259 //      MDirection acoord(MVDirection(Quantity(54, "deg"),      // HA
00260 //                                    Quantity(2034, "'")),     // DEC
00261 //                        MDirection::Ref(MDirection::HADEC,    // type
00262 //                                        frame));              // when/where
00263 // </srcblock>
00264 // <note role=tip>In the above examples in general explicit <em>MV</em>
00265 // values have been used to specified the measure's value. In many
00266 // cases (depending on the actual measure) it can be omitted, and the data
00267 // can be given directly to the measure constructor. See the 
00268 // constructors for the individual measures for details.<br>
00269 // If the reference is simple (i.e. no frame and/or offset) the 
00270 // <em>Measure::Ref</em> can be omitted, and only the code has to be
00271 // specified. </note>
00272 // A <linkto class=MeasFrame>MeasFrame</linkto> is a container for specifying
00273 // Measures needed to describe the circumstances under which the measure was
00274 // observed (or for which it has to be calculated).
00275 // E.g. the position on Earth (an <em>MPosition</em>) is necessary for 
00276 // sidereal time and coordinates like HA/Dec and Az/El; the time 
00277 // (<em>MEpoch</em>)
00278 // is necessary for non-standard coordinates (apparent, mean, HA/Dec etc); 
00279 // the coordinates (<em>MDirection</em>) for radial velocities; etc.<br>
00280 // Although quite often the value has to be in a specific format (e.g. TBD for
00281 // precession calculations; astronomical longitude for the LAST), the
00282 // frame values can be given in any known reference format: conversion to the
00283 // appropiate type will be done automatically if and when necessary.<br>
00284 // Frames (and references) are never copied, but act always as containers
00285 // with shallow copying only (i.e. <em>copied</em> frames will point to
00286 // identical instances, and changes made in one copy will be visible in all
00287 // others. This
00288 // means, e.g., that in the following:
00289 // <srcblock>
00290 //      MeasFrame frame1(MEpoch(50236.12));
00291 //      MeasFrame frame2(frame1);
00292 // </srcblock>
00293 // the two frames will be identical, and a change to one means a change to 
00294 // the other. Furthermore, only the information needed for a specific 
00295 // calculation will be used (and calculated). This means that one frame can
00296 // be used specifying all of e.g. the position (which will probably stay the
00297 // same for a series of calculations) and time; with the time being <em>set()</em>
00298 // (if also the reference of the epoch changes) or <em>resetEpoch()</em> (if only
00299 // the value changes, but the reference and its frame stay the same).
00300 // A change in the frame will influence automatically any calculation (e.g.
00301 // conversion to LAST) of which it is part.<br>
00302 //
00303 // The value of a measure (in <em>MV</em> format) can be obtained with the
00304 // <em>getValue()</em> member function. The value in a variety of formats
00305 // and units can be obtained with a (specific Measure dependent) series of
00306 // <em>get()</em> members of both the <em>MV</em>-value and the Measure.<br>
00307 //
00308 // Measures in themselves are not really necessary for proper data reduction
00309 // and the like. Its real value is the ability to transform a Measure from
00310 // one reference type (and frame, offset) to another.<br>
00311 // Conversion of a measure of a certain kind from one reference to another
00312 // is done with the aid of special, measure specific,
00313 // <linkto class=MeasConvert>MeasConvert</linkto> classes. Each conversion
00314 // class is called <em>Measure</em>\::Convert (e.g. MDirection::Convert).
00315 // A conversion generates from an input reference (or an input measure) and
00316 // an output reference a conversion functional, that can be used to convert
00317 // specific values.<br>
00318 // Example:
00319 // <srcblock>
00320 //  cout <<                     // output
00321 //                              // the conversion of a B1950 direction
00322 //      MDirection::Convert( MDirection( Quantity( 20, "deg"),
00323 //                                       Quantity(-10, "deg"),
00324 //                                       MDirection::Ref( MDirection::B1950)),
00325 //                              // to J2000
00326 //                           MDirection::Ref( MDirection::J2000)) () 
00327 //                              // where the constructor sets up a conversion
00328 //                              // engine, and the operator() converts
00329 //              << endl;
00330 //</srcblock>
00331 // The same could have been done by only setting up the conversion engine, and
00332 // not specifing the default value to be converted in the Convert constructor
00333 // by:
00334 // <srcblock>
00335 //  cout <<                     // output
00336 //                              // the conversion of a B1950 direction
00337 //      MDirection::Convert(MDirection::Ref( MDirection::B1950),
00338 //                              // to J2000
00339 //                          MDirection::Ref( MDirection::J2000))
00340 //                              // and use conversion on value
00341 //                               (MVDirection( Quantity( 20, "deg"),
00342 //                                             Quantity(-10, "deg")))
00343 //                              // where the operator() converts
00344 //              << endl;
00345 // </srcblock>
00346 // Specifying the conversion engine separately, it can be re-used for other
00347 // values:
00348 // <srcblock>
00349 //      MDirection::Convert conv(MDirection::Ref( MDirection::B1950),
00350 //                               MDirection::Ref( MDirection::J2000));
00351 //      // We have some coordinates from somewhere, say coord(0:N-1):
00352 //      for (Int i=0; i<N; i++) {
00353 //         cout << "B1950: " << coord(i) << "= J2000: " <<
00354 //                              conv(coord(i)) << endl;
00355 //      };
00356 // </srcblock>
00357 // A larger example. Say you have the J2000 coordinates for a source (RA=11
00358 // deg, DEC= -30 deg), and you want to observe it on May 17, 1996 (MJD=50220)
00359 // at 8:18 UTC in a place
00360 // with a Longitude of 150 deg (latitude of 20 deg) at 1000 m high,
00361 //  you could get the
00362 // apparent RA,DEC, and the LAST at that time (you could also go straight to
00363 // HA/DEC or so) with (I write the example longer than necessary to indicate
00364 // the steps, and with explicit reference to MV values):
00365 // <srcblock>
00366 // // The observatory position. Note that the reference is geodetic position 
00367 //      MPosition myobs(MVPosition ( Quantity(1, "km") ,
00368 //                                   Quantity(150, "deg"),
00369 //                                   Quantity(20, "deg")),
00370 //                                   MPosition::WGS84);
00371 // // The time I want to observe (note that it could be specified in many
00372 // // other ways)
00373 //      MEpoch obstime(MVEpoch(MVTime(1996, 5, 17, (8+18./60.)/24.)), 
00374 //                     MEpoch::UTC);
00375 // // The frame specification for when and where to observe
00376 //      MeasFrame frame(myobs, obstime);
00377 // // The reference for a sidereal time (note the frame could be empty and 
00378 // // filled at the actual conversion time)
00379 //      MEpoch::Ref sidref( MEpoch::LAST, frame);
00380 // // The reference for apparent coordinates:
00381 //      MDirection::Ref appref( MDirection::APP, frame);
00382 // // The conversion engine for my time to LAST
00383 //      MEpoch::Convert tosid(obstime, sidref);
00384 // // The conversion to sidereal time of obstime
00385 //      MEpoch sidtime = tosid();
00386 // // Conversion of UTC 10.8 h 
00387 //      sidtime = tosid(MVEpoch(MVTime(1996, 5, 17, 10.8/24.))); 
00388 // // Show me some time
00389 //      cout << "LAST for UTC = 11:00: " <<
00390 //              tosid(MVEpoch( MVTime( 1996, 5, 17, 11, 0))) << endl;
00391 // // An offset reference (note the RAZE will keep only the integer part of
00392 // // the day for the conversion result)
00393 //      MEpoch::Ref offtime(obstime.getValue(), MEpoch::UTC+MEpoch::RAZE);
00394 // // The reference for a sidereal with respect to a specified offset (note
00395 // // that it is automatically calculated into correct units)
00396 //      MEpoch::Ref sidoffref(MEpoch::LAST, frame, offtime);
00397 // // Show the offset result
00398 //      cout << "LAST today: " <<
00399 //              MEpoch::Convert(11., sidoffref)() << endl;
00400 // // Coordinate conversion from J2000
00401 //      cout << "Apparent coordinates: " <<
00402 //              MDirection::Convert ( MDirection(Quantum(11,"deg"),
00403 //                                               Quantum(-30, "deg")),
00404 //                                    MDirection::Ref( MDirection::APP,
00405 //                                                     frame))() << endl;
00406 // // Handier to have the conversion engine available
00407 //      MDirection::Convert cvt( MDirection(Quantum(11,"deg"),
00408 //                                          Quantum(-30, "deg")),
00409 //                               MDirection::Ref( MDirection::APP,
00410 //                                                frame));
00411 // // Set another frame time (note it is now sidereal, not UTC. The
00412 // // frame will automatically convert it (using the frame again for
00413 // // position) to TDB for precession etc calculations).
00414 //      frame.set(sidtime);
00415 // // And look what same position is at this new time
00416 //      cout << "Next position: " << cvt() << endl;
00417 // </srcblock>
00418 // <p>
00419 // Some conversions need maybe some fine tuning (e.g. what is the acceptable
00420 // interval for Nutation linear interpolation: could be different from the
00421 // default interval; some time calculations will want to use the predicted
00422 // IERS values rather than the actual determined; some Nutation will maybe
00423 // use the IERS updates, some maybe the JPL DE databases).<br>
00424 // The <linkto class=AipsrcValue>AipsrcValue</linkto> class can be used to
00425 // specify very specific parameters that are used to steer
00426 // the conversion process beyond what is possible with just a list
00427 // of measure reference types (that list is already long for some cases).
00428 // Values, switches can be <src>set()</src> (and removed) to change the
00429 // default behaviour of the conversions. In general the user will only need
00430 // to use the details in very specific cases. The details that can be used
00431 // are described in the classes that provide calculations (e.g.
00432 // <linkto class=Nutation>Nutation</linkto>), and in the aipsrc-data reference
00433 // manual entry.<br>
00434 // <p>
00435 // Some details about the different classes follows. In the examples often
00436 // a specific measure value (e.g. MVEpoch, the MeasValue for MEpoch), or a
00437 // specific measure (e.g. MDirection, a direction in space) is used. This
00438 // is only to visualise the use, any other measure could have been used.
00439 // <p>
00440 // <h4> MeasValue</h4>
00441 // The MeasValue class derivatives are all named <em>MVmeasure</em>, e.g.
00442 // <em>MVFrequency</em>, and represent the internal representation of the
00443 // specific measure class.  Details
00444 // can be found in the <linkto module=Quanta>Quanta</linkto> module.
00445 // <p>
00446 // <h4> Measure</h4>
00447 // The Measure class derivatives are all called <em>MMeasure</em>.
00448 // <linkto class=MDirection>MDirection</linkto> (a celestial direction),
00449 // <linkto class=MPosition>MPosition</linkto> (a position on Earth),
00450 // <linkto class=MFrequency>MFrequency</linkto> (characteristics of 
00451 //      electro-magnetic wave),
00452 // <linkto class=MEpoch>MEpoch</linkto> (an instance in time),
00453 // <linkto class=MDoppler>MDoppler</linkto>,
00454 // <linkto class=MRadialVelocity>MRadialVelocity</linkto>
00455 // <linkto class=MBaseline>MBaseline</linkto>,
00456 // <linkto class=Muvw>Muvw</linkto>,
00457 // <linkto class=MEarthMagnetic>MEarthMagnetic</linkto>,
00458 //. <br>
00459 // A measure has a value (kept in internal units in <em>MVmeasure</em>
00460 // format) and a definition
00461 // of the reference frame (MeasRef) of the value. The reference is optional, and
00462 // will default to <em>Measure::DEFAULT</em>.<br>
00463 // All measures have a set of standard constructors:
00464 // <srcblock>
00465 //      M();                    // some default, e.g. pole directoon, time ==0)
00466 //      M(MV, MeasRef);
00467 //      M(Quantity, MeasRef);
00468 //      M(Quantum<Vector<Double> >, MeasRef);
00469 //      M(Vector<Quantity>, MeasRef);
00470 // </srcblock>
00471 // But also some special ones (e.g. two Quantities for MDirection to specify
00472 // two angles) depending on type. The MeasRef can be omitted (will then be
00473 // defaulted to Measure::DEFAULT, e.g. MEpoch::DEFAULT); can be specified as
00474 // a full reference as a <em>Measure::Ref</em> (e.g. <em>MDirection::Ref</em>)
00475 // type; or as a simple reference as <em>Measure::TYPE</em> (e.g. 
00476 // <em>MDirection::J2000</em>).<br>
00477 // The individual elements of a Measure (i.e the MV value and the reference)
00478 // can be overwritten (or set) with the <src>set()</src> methods.<br>
00479 // <src>get()</src> methods (in general <src>get(unit)</src> 
00480 // to return the internal value in some
00481 // specified unit as a Quantum; and methods like <src>getAngle()</src>
00482 // for e.g. MDirection)
00483 // enable the user to obtain the value of the measure.<br>
00484 // A <src>String tellMe()</src> will tell the type of Measure; a 
00485 // <src>void assured(String)</src> and <src>Bool areYou(String)</src> will
00486 // check the type; while a <src>String showType(Measure::TYPE)</src> will
00487 // return the string value of a reference type code (e.g. J2000).<br>
00488 // <p>
00489 // Recall that a Measure is a value with a reference specified. The MeasConvert
00490 // engines enable you to convert it into another Measure, with a different 
00491 // reference (e.g. from J2000 to AZEL). The different get() methods (either
00492 // directly, or indirectly using additional MV get() functions, or
00493 // Quantum conversion methods, can convert the internal value into a value
00494 // (or values) with user preferred units.<br>
00495 // For reasons of speed (and safety) the allowed reference types for each
00496 // Measure are enumerated in each measure class. The different reference 
00497 // types for MDirection are, for example:
00498 // <srcblock>
00499 //              MDirection::J2000,
00500 //              MDirection::JMEAN,
00501 //              MDirection::JTRUE,
00502 //              MDirection::APP,
00503 //              MDirection::B1950,
00504 //              MDirection::BMEAN,
00505 //              MDirection::BTRUE,
00506 //              MDirection::GALACTIC,
00507 //              MDirection::HADEC,
00508 //              MDirection::AZEL,
00509 //              MDirection::DEFAULT = MDirection::J2000
00510 // </srcblock>
00511 // The MEpoch has a special reference type (<src>MEpoch::RAZE</src>) that 
00512 // can only be used
00513 // in conjuncion with another reference type 
00514 // (e.g. <src> MEpoch::UT1+MEpoch::RAZE)</src>.
00515 // The meaning is: if a measure with such a reference type is converted to
00516 // another reference type (say <src>MEpoch::LAST</src>) the 
00517 // resultant (sidereal time)
00518 // instance will be <em>razed</em> to an integer number of days; hence providing
00519 // an easy way to specify sidereal times offset with the beginning of the
00520 // current sidereal day.<br>
00521 // To aid with external data, a <src>Bool giveMe(String, uInt)</src> will
00522 // give the correct reference type to be used given the String type.
00523 // Note that the
00524 // uInt, rather than the corresponding enum is used, due to templating
00525 // restrictions in some compilers.<br>
00526 // The correct reference (MeasRef) and conversion (MeasConvert) class for
00527 // each Measure (a frequency cannot be converted into an epoch) are templated,
00528 // and have specified (and to be used) typedefs: <em>Measure::Ref</em> and
00529 // <em>Measure::Convert</em> (e.g. <em>MEpoch::Ref, MEpoch::Convert</em>). In
00530 // addition, Measure::MVType and Measure::MCType are defined for all
00531 // measures.
00532 // <p>
00533 // <h4>Measure errors </h4>
00534 // In the current implementation, no errors are attached to a Measure. In the
00535 // original design errors were foreseen, but up till now they have been left
00536 // out.<br>
00537 // The addition of errors is in principle an easy process. They could be 
00538 // attached to either a Measure (as an additial MV value), or the MV's could
00539 // be expanded to include errors (my preferred option at the moment). An
00540 // MV being converted will then automatically have its error converted as
00541 // well.<br>
00542 // Before implementing, however, I think it would be worthwhile to look at
00543 // the whole area of error handling. The easiest way would be to introduce
00544 // for each of the defined Casacore standard values a corresponding E class
00545 // (EDouble, EInt, EComplex, EuInt etc), and have all mathematical and
00546 // logical operators that are defined for the standard classes be defined
00547 // for the E-classes as well. It would then be easy to introduce errors
00548 // everywhere.
00549 // <p>
00550 // <h4>MeasFrame</h4>
00551 // A MeasFrame is a container with the instance of time
00552 // (an MEpoch) and/or the position (an MPosition) for a measure reference.
00553 // (Other Measures, like MDirection and MRadialVelocity are sometimes needed
00554 // as well).
00555 // MeasFrames are never actually copied, but only referred to (<em>shallow copy</em>)
00556 // , so they can be used for all different types
00557 // of measure reference. They are only necessary, but then essential, if the
00558 // reference type does not fully specify the frame (like e.g. MDirection::J2000,
00559 // or MEpoch::TAI do). Examples are the position necessary to go to
00560 // MEpoch::LAST, the epoch necessary to go to MDirection::APP, the epoch and
00561 // position necessary to reference an MDirection::AZEL.<br>
00562 // A MeasFrame can be constructed empty (and used in references, as long as it
00563 // is filled properly at the time of an actual conversion), or with one or
00564 // Measures already defined with: <src>MeasFrame frame(a_Measure, ...)</src>.
00565 // It can be filled, or re-filled, with <src>set(a_measure,....)</src>.<br>
00566 // The conversion routines use different values of the frame values given (e.g.
00567 // the precession and nutation will need the epoch in TDB time, the hour-angle
00568 // constructor local apparent sidereal time, which needs the astronomical
00569 // longitude etc.). For that reason the specification of an epoch or position
00570 // in either the constructor or the set() will create conversion engines for
00571 // conversion of the input measure to all appropiate values that can be asked
00572 // by the conversion routines. Note that the actual conversion is only done
00573 // when that value is requested (and is then saved for later use). It is,
00574 // therefore, safe and probably good practice to have one frame in a certain
00575 // conversion environment, filled with as much info as is needed at that stage.<br>
00576 // To aid and speed up, <src>resetEpoch()</src> and <src>resetPosition()</src>
00577 // methods are available. As arguments they accept the corresponding
00578 // MV or a variety of Double and Quantum arguments to reset the <em>value</em>
00579 // of the corresponding frame measure only. In that case the conversion engine
00580 // won't be redesigned, leading to fast recalculation when necessary, since
00581 // e.g. nutation values could be re-used.<br>
00582 // In an observing environment you could hence setup a proper frame with the
00583 // Observatory position, and an observing day offset (see MeasRef) time; and
00584 // do resetEpoch() to update the time if and when necessary.<br>
00585 // <p>
00586 // <h4>MeasRef</h4>
00587 // A MeasRef is a measure specific container (and its class reference is
00588 // <src>Measure::Ref</src>, e.g. <src>MFrequency::Ref</src>) with the
00589 // measure reference type (e.g. <src>MEpoch::UTC</src>), an optional (but in
00590 // some cases necessary) MeasFrame (e.g. to specify where the sidereal time
00591 // was determined), and, just for convenience, an optional offset (e.g.
00592 // the MJD for which the time specified in the MEpoch referenced is valid).
00593 // Note that if no frame or offset is necessary, the <src>Measure::TYPE</src>
00594 // can be used everywhere where a <src>Measure::Ref</src> is needed.<br>
00595 // A MeasRef is never copied (all copying and so is done by referencing). This
00596 // means, for example, that if a specific MeasRef is part of the MEpoch
00597 // definition for an epoch that is part of a MeasFrame, and you chnage that
00598 // MeasRef, the change will automatically occur wherever that MeasRef is
00599 // used (as e.g. in the frame). In most cases that is the expected response,
00600 // but you should be aware of it, and not re-use a MeasRef for a completely
00601 // different purpose.<br>
00602 // A simple example:
00603 // <srcblock>
00604 //      MEpoch mytime(MVEpoch(50236.5), MEpoch::UTC);
00605 // // this will define a time in UTC on MJD 50236, 12 hours. The MVEpoch
00606 // // explicit conversion could be left out for most compilers, but some
00607 // // have trouble with automatic conversions.
00608 // // Another way of doing it would be to use Quantities, which have
00609 // // explicit constructors for all measures:
00610 //      MEpoch mytime(Quantity(50236.5, "d"));
00611 // </srcblock>
00612 // A slighty more involved example, written out a bit:
00613 // <srcblock>
00614 // // Specify the location of the observatory (10m high, at given longitude
00615 // // and latitude as geodetic position)
00616 //      MPosition obs(  MVPosition(     Quantity( 10, "m"),
00617 //                                      Quantity( -6, "deg"),
00618 //                                      Quantity( 52, "deg")),
00619 //                      MPosition::WGS84);
00620 // // If the current time is MJD50236, 12.3 h UTC, it could be specified as:
00621 //      MEpoch tim(     MVEpoch(        Quantity( 50236, "d"),
00622 //                                      Quantity( 12.3, "h")));
00623 // // Note the default reference
00624 // // For this example we will also specify it as:
00625 //      MEpoch offtim(tim); 
00626 //      offtim.set(MEpoch::DEFAULT+MEpoch::RAZE);
00627 // // These two could define a frame
00628 //      MeasFrame frame(tim, obs);
00629 // // Or maybe as (since observatory will stay put)
00630 //      MeasFrame frame1(obs);
00631 // // and later addition of some time and its reference frame
00632 //      frame1.set(tim);
00633 // // with a change to another time value at a later stage with
00634 //      frame1.resetEpoch(      MVEpoch(        Quantity( 50236, "d"),
00635 //                                      Quantity( 13, "h")));
00636 // // At this time we observe a sidereal time of 2.3 h. The actual instance
00637 // // of time needs a sidereal date to specify, but we are too lazy to
00638 // // look it up, hence we specify that this time has an offset, equal to
00639 // // the sidereal time at offtim (which with the RAZE addition will be
00640 // // converted to an integral number of days in whatever time it is
00641 // // converted to)
00642 //      MEpoch mylast(  MVEpoch(        Quantity( 2.3, "h")),
00643 //                      MEpoch::Ref(    MEpoch::LAST,
00644 //                                      frame,
00645 //                                      offtim));
00646 // // Which specifies that we have a Local apparent sidereal time of 2.3 h
00647 // // at the position specified by obs in the frame, at an offset offtim.
00648 // // Note that the offset is given in UTC (and RAZE). Any conversion of
00649 // // this mylast value to any other reference type, will always auto start
00650 // // with a conversion of the offset to the current type (i.e LAST (with
00651 // // the RAZE taking the integer part only)), and adding it to the value
00652 // // given. Note that if an output reference has an offset, the resulting
00653 // // value will be corrected for the specified offset as well.
00654 // </srcblock>
00655 // The reference type can be set with a set() function, and set() functions
00656 // for the offset and frame will be present as well.<br>
00657 // A <src>Bool empty()</src> checks if the reference is empty; <src>get()</src>
00658 // functions provide the information in the reference; and a 
00659 // <src>String showMe()</src> will return the type of measure (e.g. "Epoch") the
00660 // MeasRef can be used for.
00661 //<p>
00662 // <h4>MeasConvert</h4>
00663 // The MeasConvert class converts Measures from one reference type and frame
00664 // to another.
00665 // It gathers all relevant
00666 // information and analyses it to have fast multiple conversions.
00667 // The MeasConvert classes are Measure specific, and should be used with
00668 // the class names <src>Measure::Convert</src> (e.g. <src>MFrequency::Convert
00669 // </src>).
00670 // The () operator will do the actual conversion; constructors and set()
00671 // methods will only fill the information necessary to do the conversion.
00672 // MeasConvert is a non-copying container.<br>
00673 // To set up the conversion engine, the MeasConvert object has to know the
00674 // input data reference (remember the MeasRef contains information about the
00675 // type, the possible reference frame and a possible offset), and an output
00676 // reference. Using these references it will communicate with the appropiate
00677 // Measure class to set up a series of routines that have to be executed in
00678 // order to attain the goal. (Note that if the input and output reference
00679 // both define a frame, but different ones, e.g. because you want to convert
00680 // a  sidereal time at one place to a sidereal time at another place, the
00681 // conversion machinery will always first go to the proper default (UTC in this
00682 // case), and then go to the goal).<br>
00683 // The actual conversion need a value to be converted, and it also can use
00684 // a default Unit, so that if your frequencies are in nm, you can once
00685 // specify that they are nm, and then simply convert a Double.<br>
00686 // This means that the optimal constructor for a MeasConvert is:
00687 // <srcblock>
00688 // // The first argument will give the input reference, and, if a Quantum is
00689 // // used to make the Measure, the default units for inputs to the conversion.
00690 // // It acts as a 'model' for subsequent input to be converted.
00691 // // () operator
00692 //      Measure::Convert(       Measure(Quantum), 
00693 // // the second argument gives the output reference
00694 //                              Measure::Ref);
00695 // </srcblock>
00696 // The actual constructors present include ones with the first argument only
00697 // an input reference, rather than a full Measure.
00698 // However, in all cases an empty or partial one can be constructed, with set()
00699 // functions filling in the rest. The conversion engine is only
00700 // (re-)setup if at least an input and output reference can be found.<br>
00701 // After setting up the conversion engine, the () operator can be used with
00702 // a variety of values to return a converted Measure. Possibilities are:
00703 // <srcblock>
00704 //      ()              // convert the value as specified in the 'model'
00705 //      (Double)        // convert the value first to appropiate units (if they
00706 //                      // were implicit in 'model' or explicitly set), and
00707 //                      // then convert
00708 //      (Vector<Double>)// as Double
00709 //      (Quantity)      // convert the full value, including its own units
00710 //      (Quantum<Vector<Double> >) // as Quantity
00711 //      (MeasValue)     // convert the specified appropiate MV
00712 //      (Measure)       // set up a new conversion chain, using the value as
00713 //                      // 'model', and the old output reference,
00714 //                      //  and then convert
00715 //      (Measure, Measure::Ref) // set up a new conversion chain for the
00716 //                      // 'model' given and the output reference given
00717 //      (Measure::Ref)  // set up a new conversion chain using the old 'model'
00718 //                      // and the output reference given, and convert the
00719 //                      // existing model value
00720 // </srcblock>
00721 // A simple example to output the J2000 coordinates for a B1950 input (RA=20 deg,
00722 // DEC=-10 deg):
00723 // <srcblock>
00724 //  cout <<     
00725 //      MDirection::Convert( MDirection( Quantity( 20, "deg")
00726 //                                       Quantity(-10, "deg"),
00727 //                                       MDirection::Ref( MDirection::B1950)),
00728 //                           MDirection::Ref( MDirection::J2000)) () << endl;
00729 // </srcblock>
00730 // In this example everything is done in one go (the () at the end does the
00731 // conversion). Another example, to have a UTC to LAST converter:
00732 // <srcblock>
00733 // // Set up the model for the input (default reference is UTC)
00734 //      MEpoch model (  Quantity(0., "d"));
00735 // // Set up the frame with the observatory position
00736 //      MPosition obs(  MVPosition(     Quantity( 10, "m"),
00737 //                                      Quantity( -6, "deg"),
00738 //                                      Quantity( 50, "deg")),
00739 //                      MPosition::Ref(MPosition::WGS84));
00740 //      Measframe frame( obs);
00741 // // set up the output reference
00742 //      MEpoch::Ref outref(     MEpoch::LAST,
00743 //                              frame);
00744 // // Set up conversion
00745 //      MEpoch::Convert toLST(  model,
00746 //                              outref);
00747 // // Output a series of sidereal times (formatted in ddd::hh:mm:ss)
00748 //      for (Double d = 12345; d<12346; d += 0.1) {
00749 //        cout << "Converted from UTC to LAST: " <<
00750 //              d <<
00751 //              toLST(d).getValue() << endl;
00752 //      };
00753 // </srcblock>
00754 // <p>
00755 // For specific purposes it would be very easy to set up a series of simple
00756 // classes, that would do standard conversions. 
00757 // <p>
00758 // <h4> MeasData, MeasTable, MeasBase, other help classes</h4>
00759 // A series of help classes are present to aid in the conversion, especially
00760 // caching information. They are of no direct use for the end user (except
00761 // maybe a few constants in MeasData).<br>
00762 // The classes are:
00763 // <ul>
00764 //  <li> <linkto class=MeasBase>MeasBase</linkto>:
00765 //      base class (derived from Measure) for all real Measures
00766 //  <li> <linkto class=MeasData>MeasData</linkto>:
00767 //      all constants, polynomial factors, interface to IERS
00768 //      database etc. which are not stored in Tables. (MeasTable looks after 
00769 //      these). Mn short it provides all the actual data values necessary
00770 //      for the conversions (and the other help classes)
00771 //  <li> <linkto class=MeasTable>MeasTable</linkto>:
00772 //      interface for all data that comes from Tables rather than
00773 //      the program
00774 //  <li> <linkto class=MeasIERS>MeasIERS</linkto>:
00775 //      (static) class to converse with the IERS database(s)
00776 //  <li> <linkto class=MeasJPL>MeasJPL</linkto>:
00777 //      (static) class to converse with the JPL DE database(s)
00778 //  <li> <linkto class=Precession>Precession</linkto>:
00779 //       all precession related calculations
00780 //  <li> <linkto class=Nutation>Nutation</linkto>
00781 //  <li> <linkto class=Aberration>Aberration</linkto>
00782 //  <li> <linkto class=SolarPos>SolarPos</linkto>:
00783 //       all solarposition related calculations
00784 //  <li> <linkto class=Euler>Euler</linkto>:
00785 //       representation of Euler rotation angles
00786 //  <li> <linkto class=RotMatrix>RotMatrix</linkto>: a 3-D rotation matrix
00787 // </ul>
00788 // <p>
00789 
00790 // </synopsis> 
00791 //
00792 // <motivation>
00793 // The Measures module originated to be able to convert ccordinates between
00794 // different reference frames.
00795 // </motivation>
00796 //
00797 // <todo asof="1998/07/22">
00798 //   <li> inlining
00799 // </todo>
00800 //
00801 // <example>
00802 // See the individual measures for appropiate examples.
00803 // </example>
00804 // </module>
00805 
00806 //# Dummy class definition for extractor
00807 //# class Measures {};
00808 
00809 
00810 } //# NAMESPACE CASACORE - END
00811 
00812 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1