casacore
MFrequency.h
Go to the documentation of this file.
1 //# MFrequency.h: A Measure: wave characteristics
2 //# Copyright (C) 1995,1996,1997,1998,1999,2000,2001,2002,2003
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //#
27 //# $Id$
28 
29 #ifndef MEASURES_MFREQUENCY_H
30 #define MEASURES_MFREQUENCY_H
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/measures/Measures/MeasBase.h>
35 #include <casacore/measures/Measures/MeasRef.h>
36 #include <casacore/casa/Quanta/MVFrequency.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 //# Forward Declarations
41 class MFrequency;
42 class MCFrequency;
43 class MDoppler;
44 class MVDoppler;
45 template <class M> class MeasConvert;
46 template <class M> class ArrayMeasColumn;
47 template <class M> class ScalarMeasColumn;
48 
49 //# Typedefs
50 
51 // <summary>
52 // A Measure: wave characteristics
53 // </summary>
54 
55 // <use visibility=export>
56 
57 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tMeasure" demos="">
58 // </reviewed>
59 
60 // <prerequisite>
61 // <li> <linkto class=Measure>Measure</linkto> class
62 // <li> <linkto class = MRadialVelocity>MRadialVelocity</linkto> class
63 // for some other background.
64 // </prerequisite>
65 //
66 // <etymology>
67 // </etymology>
68 //
69 // <synopsis>
70 // MFrequency is a derived Measure class for wave characteristics.<br>
71 // An MFrequency can be generated from a simple value (or an
72 // <linkto class=MVFrequency>MFrequency</linkto> object), which is then
73 // interpreted as a frequency in Hz, and a reference, with an LSRK type
74 // as default.<br>
75 // It can also be generated from a Quantity, where the interpretation
76 // depends on the dimensionality of the Quantity:
77 // <ul>
78 // <li> time (e.g. s): period
79 // <li> frequency (e.g. Hz): frequency
80 // <li> angular frequency (e.g. arcmin/s): angular frequency
81 // <li> length (e.g. cm): wavelength
82 // <li> inverse length (e.g. mm<sup>-1</sup>): wave number
83 // <li> energy (e.g. J.s): energy (i.e. <em>h.nu</em>)
84 // <li> momentum (e.g. kg.m): <em>m.c/h</em>
85 // </ul>
86 // The different reference types of a frequency are:
87 // <ul>
88 // <li> MFrequency::REST -- Rest frequency
89 // <li> MFrequency::LSRD -- Local Standard of Rest (J2000) -- as the
90 // dynamical definition (IAU, [9,12,7] km/s in galactic
91 // coordinates)
92 // <li> MFrequency::LSRK -- LSR as a kinematical (radio) definition --
93 // 20.0 km/s in direction ra,dec = [270,+30] deg (B1900.0)
94 // <li> MFrequency::BARY -- Barycentric (J2000)
95 // <li> MFrequency::GEO --- Geocentric
96 // <li> MFrequency::TOPO -- Topocentric
97 // <li> MFrequency::GALACTO -- Galacto centric (with rotation of 220 km/s
98 // in direction l,b = [90,0] deg.
99 // <li> MFrequency::LGROUP -- Local group velocity -- 308km/s towards
100 // l,b = [105,-7] deg (F. Ghigo)
101 // <li> MFrequency::CMB -- CMB velocity -- 369.5km/s towards
102 // l,b = [264.4, 48.4] deg (F. Ghigo)
103 // <li> MFrequency::DEFAULT = LSRK
104 // </ul>
105 // <p>
106 // Conversion between the different types is done with the standard
107 // <linkto class=MeasConvert>MeasConvert</linkto> class
108 // (<src>MFrequency::Convert</src> in this case).
109 // Some of the conversions are only possible if frame information has been
110 // filled in. The following frame information is necessary if a conversion
111 // goes to or from the (different) specified types:
112 // <ul>
113 // <li><em>Radial Velocity</em>: REST
114 // <li><em>Epoch</em>: TOPO, GEO
115 // <li><em>Position</em>: TOPO
116 // <li><em>Direction</em> all
117 // </ul>
118 // <br>
119 // To accommodate unknown or invalid frames, the additional reference type
120 // <ul>
121 // <li> MFrequency::Undefined
122 // </ul>
123 // is available. Conversions to/from Undefined are not possible.
124 // If attempted, an exception will be thrown.
125 // The name was chosen to be Undefined and not UNDEFINED in order to
126 // not collide with the (ugly) WCSLIB macro of the upper case name
127 // and in concordance with Stokes::Undefined.
128 // <br>
129 // An MFrequency can be created from an
130 // <linkto class=MDoppler>MDoppler</linkto> (and a rest frequency, (the
131 // <linkto class=QC>QC</linkto> class contains at least <src>QC::HI</src>))
132 // by the <src>fromDoppler()</src> member. It can be converted to an MDoppler
133 // with the <src>toDoppler()</src>. Comparable methods will be available
134 // for <linkto class=MFrequency>MFrequency</linkto> as
135 // <src>toRadial()</src> and <src>fromRadial</src>.<br>
136 // If the Doppler shift is known (e.g. from another spectral line), the
137 // REST frequency can be determined with the <src>toREST()</src> member.
138 // <note role=caution> Conversion between the different frequencies can,
139 // due to relativistic effects, only be done approximately for very high
140 // (order c) radial velocities (shifted frequencies). A better approach
141 // would be to start from radial velocities and a rest frequency.
142 // </note>
143 // </synopsis>
144 //
145 // <example>
146 // Get the Doppler shift for an oberved HI frequency of 1380 MHz
147 // <srcblock>
148 // cout << "Redshift for 1380 MHz: " <<
149 // MDoppler::Convert( MFrequency( Quantity(1380., "MHz"),
150 // MFrequency::TOPO).toDoppler(QC::HI),
151 // MDoppler::Z)() << endl;
152 // </srcblock>
153 // </example>
154 //
155 // <motivation>
156 // </motivation>
157 //
158 // <todo asof="2003/03/03">
159 // </todo>
160 
161 class MFrequency : public MeasBase<MVFrequency, MeasRef<MFrequency> > {
162 
163  public:
164  //# Friends
165  // Conversion of data
166  friend class MeasConvert<MFrequency>;
167 
168  //# Enumerations
169  // Types of known MFrequencies
170  // <note role=warning> The order defines the order in the translation
171  // matrix FromTo
172  // in the getConvert routine. Do not change the order without
173  // changing the array. Additions should be made before N_types, and
174  // an additional row and column should be coded in FromTo, and
175  // in showType().</note>
176  enum Types {
187  Undefined = 64,
189  // all extra bits
190  EXTRA = 64,
191  // Defaults
193  // Synonyms
195 
196  //# Typedefs
197  // Measure value container for this class (i.e. MFrequency::MVType)
199  // Measure conversion routines for this class (i.e. MFrequency::MCType)
201  // Measure reference (i.e. MFrequency::Ref)
203  // Measure conversion use (i.e. MFrequency::Convert)
205  // Measure table Columns (e.g., MFrequency::ScalarColumn)
208  // Reference enum Types (included originally for gcc 2.95)
209  typedef WHATEVER_SUN_TYPEDEF(MFrequency) Types Types;
210 
211  //# Constructors
212  // <note role=tip> In the following constructors and other functions, all
213  // <em>MeasRef</em> can be replaced with simple <src>Measure::TYPE</src>
214  // where no offsets or frames are needed in the reference. </note>
215  // Default constructor; generates a zero rest frequency
216  MFrequency();
217  // Create from data and reference
218  // <group>
219  MFrequency(const MVFrequency &dt);
220  MFrequency(const MVFrequency &dt, const MFrequency::Ref &rf);
221  MFrequency(const MVFrequency &dt, MFrequency::Types rf);
222  MFrequency(const Quantity &dt);
223  MFrequency(const Quantity &dt, const MFrequency::Ref &rf);
224  MFrequency(const Quantity &dt, MFrequency::Types rf);
225  MFrequency(const Measure *dt);
226  MFrequency(const MeasValue *dt);
227  // </group>
228 
229  //# Destructor
230  virtual ~MFrequency();
231 
232  //# Operators
233 
234  //# General Member Functions
235  // Tell me your type
236  // <group>
237  virtual const String &tellMe() const;
238  static const String &showMe();
239  virtual uInt type() const;
240  static void assure(const Measure &in);
241  // </group>
242  // Translate reference code. The uInt version has a check for valid codes
243  // (i.e. it is a safe cast).
244  // <thrown>
245  // <li> AipsError in the uInt interface if illegal code given
246  // </thrown>
247  // <group>
248  static MFrequency::Types castType(uInt tp);
249  static const String &showType(MFrequency::Types tp);
250  static const String &showType(uInt tp);
251  // </group>
252  // Translate string to reference code
253  // <group>
254  static Bool getType(MFrequency::Types &tp, const String &in);
255 
256  // Throws an exception if the type string is not recognized
257  static MFrequency::Types typeFromString(const String& in);
258 
259 
260  Bool giveMe(MFrequency::Ref &mr, const String &in);
261  // </group>
262  // Set the offset in the reference (False if non-matching Measure)
263  virtual Bool setOffset(const Measure &in);
264  // Set the reference type to the specified String. False if illegal
265  // string, reference set to DEFAULT.
266  virtual Bool setRefString(const String &in);
267  // Get the default reference type
268  virtual const String &getDefaultType() const;
269  // Get a list of all known reference codes. nall returns the number in list,
270  // nextra the number of specials (like planets) that should be at
271  // end of list). typ returns the list of corresponding types.
272  // <group>
273  virtual const String* allTypes(Int &nall, Int &nextra,
274  const uInt *&typ) const;
275  static const String* allMyTypes(Int &nall, Int &nextra,
276  const uInt *&typ);
277  // </group>
278  // Check if all internal tables of types (both enum and String) are
279  // complete and correct. This function is called automatically if and when
280  // necessary.
281  // <thrown>
282  // <li> AipsError if a (programming) error in the types.
283  // </thrown>
284  // <group>
285  virtual void checkTypes() const;
286  static void checkMyTypes();
287  // </group>
288  // Get the reference type (for records, including codes like R_)
289  virtual String getRefString() const;
290  // Get my type (as Register)
291  static uInt myType();
292 
293  // Get frequency in specified units
294  Quantity get(const Unit &un) const;
295 
296  // Make a Doppler velocity from the frequency and the specified rest frequency
297  // <group>
298  MDoppler toDoppler(const MVFrequency &rest);
299  MDoppler toDoppler(const MVFrequency &rest) const;
300  // </group>
301  // Local use only
302  static MDoppler toDoppler(const Measure &in, const MVFrequency &rest);
303  // Make a frequency from the Doppler velocity and the specified rest frequency
304  // (default reference type LSRK)
305  // <group>
306  static MFrequency fromDoppler(const MDoppler &dop,
307  const MVFrequency &rest);
308  static MFrequency fromDoppler(const MDoppler &dop,
309  const MVFrequency &rest,
310  MFrequency::Types type);
311  // For internal use only
312  static MFrequency fromDoppler(const Measure &dop,
313  const MVFrequency &rest,
314  MFrequency::Types type);
315  // </group>
316 
317  // Make a rest frequency using a Doppler velocity
318  MFrequency toRest(const MDoppler &dop);
319  // For local use only
320  static MFrequency toRest(const Measure &in, const Measure &dop);
321 
322  // Make a copy
323  // <group>
324  virtual Measure *clone() const;
325  // </group>
326 
327  private:
328  //# Enumerations
329 
330  //# Data
331 
332  //# Member functions
333 
334 };
335 
336 
337 } //# NAMESPACE CASACORE - END
338 
339 #endif
static Bool getType(MFrequency::Types &tp, const String &in)
Translate string to reference code.
int Int
Definition: aipstype.h:47
MFrequency toRest(const MDoppler &dop)
Make a rest frequency using a Doppler velocity.
Conversion of Measures.
Definition: MBaseline.h:44
virtual Measure * clone() const
Make a copy.
Internal value for MFrequency.
Definition: MVFrequency.h:97
MVFrequency MVType
Measure value container for this class (i.e.
Definition: MFrequency.h:198
Quantity get(const Unit &un) const
Get frequency in specified units.
virtual const String * allTypes(Int &nall, Int &nextra, const uInt *&typ) const
Get a list of all known reference codes.
MeasConvert< MFrequency > Convert
Measure conversion use (i.e.
Definition: MFrequency.h:204
A Measure: Doppler shift.
Definition: MDoppler.h:134
Physical quantities within reference frame.
Definition: Measure.h:235
ArrayMeasColumn< MFrequency > ArrayColumn
Definition: MFrequency.h:207
Base class for all measures.
Definition: MeasBase.h:75
Read only access to table array Measure columns.
Definition: MBaseline.h:45
defines physical units
Definition: Unit.h:189
Base class for values in a Measure.
Definition: MeasValue.h:107
virtual String getRefString() const
Get the reference type (for records, including codes like R_)
virtual Bool setOffset(const Measure &in)
Set the offset in the reference (False if non-matching Measure)
MeasRef< MFrequency > Ref
Measure reference (i.e.
Definition: MFrequency.h:202
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
static const String & showType(MFrequency::Types tp)
static MFrequency fromDoppler(const MDoppler &dop, const MVFrequency &rest)
Make a frequency from the Doppler velocity and the specified rest frequency (default reference type L...
virtual void checkTypes() const
Check if all internal tables of types (both enum and String) are complete and correct.
static const String * allMyTypes(Int &nall, Int &nextra, const uInt *&typ)
ScalarMeasColumn< MFrequency > ScalarColumn
Measure table Columns (e.g., MFrequency::ScalarColumn)
Definition: MFrequency.h:206
MCFrequency MCType
Measure conversion routines for this class (i.e.
Definition: MFrequency.h:200
MFrequency conversion routines.
Definition: MCFrequency.h:93
virtual Bool setRefString(const String &in)
Set the reference type to the specified String.
typedef WHATEVER_SUN_TYPEDEF(MFrequency) Types Types
Reference enum Types (included originally for gcc 2.95)
String: the storage and methods of handling collections of characters.
Definition: String.h:223
static void assure(const Measure &in)
MDoppler toDoppler(const MVFrequency &rest)
Make a Doppler velocity from the frequency and the specified rest frequency.
Read only access to table scalar Measure columns.
Definition: MBaseline.h:46
Bool giveMe(MFrequency::Ref &mr, const String &in)
static MFrequency::Types typeFromString(const String &in)
Throws an exception if the type string is not recognized.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
virtual const String & getDefaultType() const
Get the default reference type.
static MFrequency::Types castType(uInt tp)
Translate reference code.
unsigned int uInt
Definition: aipstype.h:48
virtual const String & tellMe() const
Tell me your type.