casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
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 
209  //# Constructors
210  // <note role=tip> In the following constructors and other functions, all
211  // <em>MeasRef</em> can be replaced with simple <src>Measure::TYPE</src>
212  // where no offsets or frames are needed in the reference. </note>
213  // Default constructor; generates a zero rest frequency
214  MFrequency();
215  // Create from data and reference
216  // <group>
217  MFrequency(const MVFrequency &dt);
218  MFrequency(const MVFrequency &dt, const MFrequency::Ref &rf);
220  MFrequency(const Quantity &dt);
221  MFrequency(const Quantity &dt, const MFrequency::Ref &rf);
222  MFrequency(const Quantity &dt, MFrequency::Types rf);
223  MFrequency(const Measure *dt);
224  MFrequency(const MeasValue *dt);
225  // </group>
226 
227  //# Destructor
228  virtual ~MFrequency();
229 
230  //# Operators
231 
232  //# General Member Functions
233  // Tell me your type
234  // <group>
235  virtual const String &tellMe() const;
236  static const String &showMe();
237  virtual uInt type() const;
238  static void assure(const Measure &in);
239  // </group>
240  // Translate reference code. The uInt version has a check for valid codes
241  // (i.e. it is a safe cast).
242  // <thrown>
243  // <li> AipsError in the uInt interface if illegal code given
244  // </thrown>
245  // <group>
246  static MFrequency::Types castType(uInt tp);
247  static const String &showType(MFrequency::Types tp);
248  static const String &showType(uInt tp);
249  // </group>
250  // Translate string to reference code
251  // <group>
252  static Bool getType(MFrequency::Types &tp, const String &in);
253 
254  // Throws an exception if the type string is not recognized
255  static MFrequency::Types typeFromString(const String& in);
256 
257 
258  Bool giveMe(MFrequency::Ref &mr, const String &in);
259  // </group>
260  // Set the offset in the reference (False if non-matching Measure)
261  virtual Bool setOffset(const Measure &in);
262  // Set the reference type to the specified String. False if illegal
263  // string, reference set to DEFAULT.
264  virtual Bool setRefString(const String &in);
265  // Get the default reference type
266  virtual const String &getDefaultType() const;
267  // Get a list of all known reference codes. nall returns the number in list,
268  // nextra the number of specials (like planets) that should be at
269  // end of list). typ returns the list of corresponding types.
270  // <group>
271  virtual const String* allTypes(Int &nall, Int &nextra,
272  const uInt *&typ) const;
273  static const String* allMyTypes(Int &nall, Int &nextra,
274  const uInt *&typ);
275  // </group>
276  // Check if all internal tables of types (both enum and String) are
277  // complete and correct. This function is called automatically if and when
278  // necessary.
279  // <thrown>
280  // <li> AipsError if a (programming) error in the types.
281  // </thrown>
282  // <group>
283  virtual void checkTypes() const;
284  static void checkMyTypes();
285  // </group>
286  // Get the reference type (for records, including codes like R_)
287  virtual String getRefString() const;
288  // Get my type (as Register)
289  static uInt myType();
290 
291  // Get frequency in specified units
292  Quantity get(const Unit &un) const;
293 
294  // Make a Doppler velocity from the frequency and the specified rest frequency
295  // <group>
296  MDoppler toDoppler(const MVFrequency &rest);
297  MDoppler toDoppler(const MVFrequency &rest) const;
298  // </group>
299  // Local use only
300  static MDoppler toDoppler(const Measure &in, const MVFrequency &rest);
301  // Make a frequency from the Doppler velocity and the specified rest frequency
302  // (default reference type LSRK)
303  // <group>
304  static MFrequency fromDoppler(const MDoppler &dop,
305  const MVFrequency &rest);
306  static MFrequency fromDoppler(const MDoppler &dop,
307  const MVFrequency &rest,
309  // For internal use only
310  static MFrequency fromDoppler(const Measure &dop,
311  const MVFrequency &rest,
313  // </group>
314 
315  // Make a rest frequency using a Doppler velocity
316  MFrequency toRest(const MDoppler &dop) const;
317  // For local use only
318  static MFrequency toRest(const Measure &in, const Measure &dop);
319 
320  // Make a copy
321  // <group>
322  virtual Measure *clone() const;
323  // </group>
324 
325  private:
326  //# Enumerations
327 
328  //# Data
329 
330  //# Member functions
331 
332 };
333 
334 
335 } //# NAMESPACE CASACORE - END
336 
337 #endif
static Bool getType(MFrequency::Types &tp, const String &in)
Translate string to reference code.
int Int
Definition: aipstype.h:50
Conversion of Measures.
Definition: MDirection.h:43
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
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
static const String & showMe()
Base class for all measures.
Definition: MeasBase.h:75
static void checkMyTypes()
defines physical units
Definition: Unit.h:189
A Measure: wave characteristics.
Definition: MFrequency.h:161
Base class for values in a Measure.
Definition: MeasValue.h:107
MFrequency toRest(const MDoppler &dop) const
Make a rest frequency using a Doppler velocity.
virtual String getRefString() const
Get the reference type (for records, including codes like R_)
static uInt myType()
Get my type (as Register)
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:42
MFrequency()
Tip: In the following constructors and other functions, all MeasRef can be replaced with simple Meas...
Types
Each derived class should have a Types enumeration, specifying the recognised frame types...
Definition: Measure.h:254
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.
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.
Bool giveMe(MFrequency::Ref &mr, const String &in)
Types
Types of known MFrequencies Warning: The order defines the order in the translation matrix FromTo in...
Definition: MFrequency.h:176
static MFrequency::Types typeFromString(const String &in)
Throws an exception if the type string is not recognized.
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:51
virtual uInt type() const
Get the type (== Register() of derived Measure (faster than Strings) All should have: static uInt myT...
virtual const String & tellMe() const
Tell me your type.
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42