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