00001 //# MFrequency.h: A Measure: wave characteristics 00002 //# Copyright (C) 1995,1996,1997,1998,1999,2000,2001,2002,2003 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 //# 00027 //# $Id$ 00028 00029 #ifndef MEASURES_MFREQUENCY_H 00030 #define MEASURES_MFREQUENCY_H 00031 00032 //# Includes 00033 #include <casacore/casa/aips.h> 00034 #include <casacore/measures/Measures/MeasBase.h> 00035 #include <casacore/measures/Measures/MeasRef.h> 00036 #include <casacore/casa/Quanta/MVFrequency.h> 00037 00038 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00039 00040 //# Forward Declarations 00041 class MFrequency; 00042 class MCFrequency; 00043 class MDoppler; 00044 class MVDoppler; 00045 template <class M> class MeasConvert; 00046 template <class M> class ArrayMeasColumn; 00047 template <class M> class ScalarMeasColumn; 00048 00049 //# Typedefs 00050 00051 // <summary> 00052 // A Measure: wave characteristics 00053 // </summary> 00054 00055 // <use visibility=export> 00056 00057 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tMeasure" demos=""> 00058 // </reviewed> 00059 00060 // <prerequisite> 00061 // <li> <linkto class=Measure>Measure</linkto> class 00062 // <li> <linkto class = MRadialVelocity>MRadialVelocity</linkto> class 00063 // for some other background. 00064 // </prerequisite> 00065 // 00066 // <etymology> 00067 // </etymology> 00068 // 00069 // <synopsis> 00070 // MFrequency is a derived Measure class for wave characteristics.<br> 00071 // An MFrequency can be generated from a simple value (or an 00072 // <linkto class=MVFrequency>MFrequency</linkto> object), which is then 00073 // interpreted as a frequency in Hz, and a reference, with an LSRK type 00074 // as default.<br> 00075 // It can also be generated from a Quantity, where the interpretation 00076 // depends on the dimensionality of the Quantity: 00077 // <ul> 00078 // <li> time (e.g. s): period 00079 // <li> frequency (e.g. Hz): frequency 00080 // <li> angular frequency (e.g. arcmin/s): angular frequency 00081 // <li> length (e.g. cm): wavelength 00082 // <li> inverse length (e.g. mm<sup>-1</sup>): wave number 00083 // <li> energy (e.g. J.s): energy (i.e. <em>h.nu</em>) 00084 // <li> momentum (e.g. kg.m): <em>m.c/h</em> 00085 // </ul> 00086 // The different reference types of a frequency are: 00087 // <ul> 00088 // <li> MFrequency::REST -- Rest frequency 00089 // <li> MFrequency::LSRD -- Local Standard of Rest (J2000) -- as the 00090 // dynamical definition (IAU, [9,12,7] km/s in galactic 00091 // coordinates) 00092 // <li> MFrequency::LSRK -- LSR as a kinematical (radio) definition -- 00093 // 20.0 km/s in direction ra,dec = [270,+30] deg (B1900.0) 00094 // <li> MFrequency::BARY -- Barycentric (J2000) 00095 // <li> MFrequency::GEO --- Geocentric 00096 // <li> MFrequency::TOPO -- Topocentric 00097 // <li> MFrequency::GALACTO -- Galacto centric (with rotation of 220 km/s 00098 // in direction l,b = [90,0] deg. 00099 // <li> MFrequency::LGROUP -- Local group velocity -- 308km/s towards 00100 // l,b = [105,-7] deg (F. Ghigo) 00101 // <li> MFrequency::CMB -- CMB velocity -- 369.5km/s towards 00102 // l,b = [264.4, 48.4] deg (F. Ghigo) 00103 // <li> MFrequency::DEFAULT = LSRK 00104 // </ul> 00105 // <p> 00106 // Conversion between the different types is done with the standard 00107 // <linkto class=MeasConvert>MeasConvert</linkto> class 00108 // (<src>MFrequency::Convert</src> in this case). 00109 // Some of the conversions are only possible if frame information has been 00110 // filled in. The following frame information is necessary if a conversion 00111 // goes to or from the (different) specified types: 00112 // <ul> 00113 // <li><em>Radial Velocity</em>: REST 00114 // <li><em>Epoch</em>: TOPO, GEO 00115 // <li><em>Position</em>: TOPO 00116 // <li><em>Direction</em> all 00117 // </ul> 00118 // <br> 00119 // To accommodate unknown or invalid frames, the additional reference type 00120 // <ul> 00121 // <li> MFrequency::Undefined 00122 // </ul> 00123 // is available. Conversions to/from Undefined are not possible. 00124 // If attempted, an exception will be thrown. 00125 // The name was chosen to be Undefined and not UNDEFINED in order to 00126 // not collide with the (ugly) WCSLIB macro of the upper case name 00127 // and in concordance with Stokes::Undefined. 00128 // <br> 00129 // An MFrequency can be created from an 00130 // <linkto class=MDoppler>MDoppler</linkto> (and a rest frequency, (the 00131 // <linkto class=QC>QC</linkto> class contains at least <src>QC::HI</src>)) 00132 // by the <src>fromDoppler()</src> member. It can be converted to an MDoppler 00133 // with the <src>toDoppler()</src>. Comparable methods will be available 00134 // for <linkto class=MFrequency>MFrequency</linkto> as 00135 // <src>toRadial()</src> and <src>fromRadial</src>.<br> 00136 // If the Doppler shift is known (e.g. from another spectral line), the 00137 // REST frequency can be determined with the <src>toREST()</src> member. 00138 // <note role=caution> Conversion between the different frequencies can, 00139 // due to relativistic effects, only be done approximately for very high 00140 // (order c) radial velocities (shifted frequencies). A better approach 00141 // would be to start from radial velocities and a rest frequency. 00142 // </note> 00143 // </synopsis> 00144 // 00145 // <example> 00146 // Get the Doppler shift for an oberved HI frequency of 1380 MHz 00147 // <srcblock> 00148 // cout << "Redshift for 1380 MHz: " << 00149 // MDoppler::Convert( MFrequency( Quantity(1380., "MHz"), 00150 // MFrequency::TOPO).toDoppler(QC::HI), 00151 // MDoppler::Z)() << endl; 00152 // </srcblock> 00153 // </example> 00154 // 00155 // <motivation> 00156 // </motivation> 00157 // 00158 // <todo asof="2003/03/03"> 00159 // </todo> 00160 00161 class MFrequency : public MeasBase<MVFrequency, MeasRef<MFrequency> > { 00162 00163 public: 00164 //# Friends 00165 // Conversion of data 00166 friend class MeasConvert<MFrequency>; 00167 00168 //# Enumerations 00169 // Types of known MFrequencies 00170 // <note role=warning> The order defines the order in the translation 00171 // matrix FromTo 00172 // in the getConvert routine. Do not change the order without 00173 // changing the array. Additions should be made before N_types, and 00174 // an additional row and column should be coded in FromTo, and 00175 // in showType().</note> 00176 enum Types { 00177 REST, 00178 LSRK, 00179 LSRD, 00180 BARY, 00181 GEO, 00182 TOPO, 00183 GALACTO, 00184 LGROUP, 00185 CMB, 00186 N_Types, 00187 Undefined = 64, 00188 N_Other, 00189 // all extra bits 00190 EXTRA = 64, 00191 // Defaults 00192 DEFAULT=LSRK, 00193 // Synonyms 00194 LSR=LSRK }; 00195 00196 //# Typedefs 00197 // Measure value container for this class (i.e. MFrequency::MVType) 00198 typedef MVFrequency MVType; 00199 // Measure conversion routines for this class (i.e. MFrequency::MCType) 00200 typedef MCFrequency MCType; 00201 // Measure reference (i.e. MFrequency::Ref) 00202 typedef MeasRef<MFrequency> Ref; 00203 // Measure conversion use (i.e. MFrequency::Convert) 00204 typedef MeasConvert<MFrequency> Convert; 00205 // Measure table Columns (e.g., MFrequency::ScalarColumn) 00206 typedef ScalarMeasColumn<MFrequency> ScalarColumn; 00207 typedef ArrayMeasColumn<MFrequency> ArrayColumn; 00208 // Reference enum Types (included originally for gcc 2.95) 00209 typedef WHATEVER_SUN_TYPEDEF(MFrequency) Types Types; 00210 00211 //# Constructors 00212 // <note role=tip> In the following constructors and other functions, all 00213 // <em>MeasRef</em> can be replaced with simple <src>Measure::TYPE</src> 00214 // where no offsets or frames are needed in the reference. </note> 00215 // Default constructor; generates a zero rest frequency 00216 MFrequency(); 00217 // Create from data and reference 00218 // <group> 00219 MFrequency(const MVFrequency &dt); 00220 MFrequency(const MVFrequency &dt, const MFrequency::Ref &rf); 00221 MFrequency(const MVFrequency &dt, MFrequency::Types rf); 00222 MFrequency(const Quantity &dt); 00223 MFrequency(const Quantity &dt, const MFrequency::Ref &rf); 00224 MFrequency(const Quantity &dt, MFrequency::Types rf); 00225 MFrequency(const Measure *dt); 00226 MFrequency(const MeasValue *dt); 00227 // </group> 00228 00229 //# Destructor 00230 virtual ~MFrequency(); 00231 00232 //# Operators 00233 00234 //# General Member Functions 00235 // Tell me your type 00236 // <group> 00237 virtual const String &tellMe() const; 00238 static const String &showMe(); 00239 virtual uInt type() const; 00240 static void assure(const Measure &in); 00241 // </group> 00242 // Translate reference code. The uInt version has a check for valid codes 00243 // (i.e. it is a safe cast). 00244 // <thrown> 00245 // <li> AipsError in the uInt interface if illegal code given 00246 // </thrown> 00247 // <group> 00248 static MFrequency::Types castType(uInt tp); 00249 static const String &showType(MFrequency::Types tp); 00250 static const String &showType(uInt tp); 00251 // </group> 00252 // Translate string to reference code 00253 // <group> 00254 static Bool getType(MFrequency::Types &tp, const String &in); 00255 00256 // Throws an exception if the type string is not recognized 00257 static MFrequency::Types typeFromString(const String& in); 00258 00259 00260 Bool giveMe(MFrequency::Ref &mr, const String &in); 00261 // </group> 00262 // Set the offset in the reference (False if non-matching Measure) 00263 virtual Bool setOffset(const Measure &in); 00264 // Set the reference type to the specified String. False if illegal 00265 // string, reference set to DEFAULT. 00266 virtual Bool setRefString(const String &in); 00267 // Get the default reference type 00268 virtual const String &getDefaultType() const; 00269 // Get a list of all known reference codes. nall returns the number in list, 00270 // nextra the number of specials (like planets) that should be at 00271 // end of list). typ returns the list of corresponding types. 00272 // <group> 00273 virtual const String* allTypes(Int &nall, Int &nextra, 00274 const uInt *&typ) const; 00275 static const String* allMyTypes(Int &nall, Int &nextra, 00276 const uInt *&typ); 00277 // </group> 00278 // Check if all internal tables of types (both enum and String) are 00279 // complete and correct. This function is called automatically if and when 00280 // necessary. 00281 // <thrown> 00282 // <li> AipsError if a (programming) error in the types. 00283 // </thrown> 00284 // <group> 00285 virtual void checkTypes() const; 00286 static void checkMyTypes(); 00287 // </group> 00288 // Get the reference type (for records, including codes like R_) 00289 virtual String getRefString() const; 00290 // Get my type (as Register) 00291 static uInt myType(); 00292 00293 // Get frequency in specified units 00294 Quantity get(const Unit &un) const; 00295 00296 // Make a Doppler velocity from the frequency and the specified rest frequency 00297 // <group> 00298 MDoppler toDoppler(const MVFrequency &rest); 00299 MDoppler toDoppler(const MVFrequency &rest) const; 00300 // </group> 00301 // Local use only 00302 static MDoppler toDoppler(const Measure &in, const MVFrequency &rest); 00303 // Make a frequency from the Doppler velocity and the specified rest frequency 00304 // (default reference type LSRK) 00305 // <group> 00306 static MFrequency fromDoppler(const MDoppler &dop, 00307 const MVFrequency &rest); 00308 static MFrequency fromDoppler(const MDoppler &dop, 00309 const MVFrequency &rest, 00310 MFrequency::Types type); 00311 // For internal use only 00312 static MFrequency fromDoppler(const Measure &dop, 00313 const MVFrequency &rest, 00314 MFrequency::Types type); 00315 // </group> 00316 00317 // Make a rest frequency using a Doppler velocity 00318 MFrequency toRest(const MDoppler &dop); 00319 // For local use only 00320 static MFrequency toRest(const Measure &in, const Measure &dop); 00321 00322 // Make a copy 00323 // <group> 00324 virtual Measure *clone() const; 00325 // </group> 00326 00327 private: 00328 //# Enumerations 00329 00330 //# Data 00331 00332 //# Member functions 00333 00334 }; 00335 00336 00337 } //# NAMESPACE CASACORE - END 00338 00339 #endif