casacore
Loading...
Searching...
No Matches
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
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40//# Forward Declarations
41class MFrequency;
42class MCFrequency;
43class MDoppler;
44class MVDoppler;
45template <class M> class MeasConvert;
46template <class M> class ArrayMeasColumn;
47template <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
161class 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 {
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
215 // Create from data and reference
216 // <group>
221 MFrequency(const Quantity &dt, const MFrequency::Ref &rf);
223 MFrequency(const Measure *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 static void assure(const Measure &in);
238 // </group>
239 // Translate reference code. The uInt version has a check for valid codes
240 // (i.e. it is a safe cast).
241 // <thrown>
242 // <li> AipsError in the uInt interface if illegal code given
243 // </thrown>
244 // <group>
247 static const String &showType(uInt tp);
248 // </group>
249 // Translate string to reference code
250 // <group>
251 static Bool getType(MFrequency::Types &tp, const String &in);
252
253 // Throws an exception if the type string is not recognized
255
256
258 // </group>
259 // Set the offset in the reference (False if non-matching Measure)
260 virtual Bool setOffset(const Measure &in);
261 // Set the reference type to the specified String. False if illegal
262 // string, reference set to DEFAULT.
263 virtual Bool setRefString(const String &in);
264 // Get the default reference type
265 virtual const String &getDefaultType() const;
266 // Get a list of all known reference codes. nall returns the number in list,
267 // nextra the number of specials (like planets) that should be at
268 // end of list). typ returns the list of corresponding types.
269 // <group>
270 virtual const String* allTypes(Int &nall, Int &nextra,
271 const uInt *&typ) const;
272 static const String* allMyTypes(Int &nall, Int &nextra,
273 const uInt *&typ);
274 // </group>
275 // Check if all internal tables of types (both enum and String) are
276 // complete and correct. This function is called automatically if and when
277 // necessary.
278 // <thrown>
279 // <li> AipsError if a (programming) error in the types.
280 // </thrown>
281 // <group>
282 virtual void checkTypes() const;
283 static void checkMyTypes();
284 // </group>
285 // Get the reference type (for records, including codes like R_)
286 virtual String getRefString() const;
287
288 // Get frequency in specified units
289 Quantity get(const Unit &un) const;
290
291 // Make a Doppler velocity from the frequency and the specified rest frequency
292 // <group>
294 MDoppler toDoppler(const MVFrequency &rest) const;
295 // </group>
296 // Local use only
297 static MDoppler toDoppler(const Measure &in, const MVFrequency &rest);
298 // Make a frequency from the Doppler velocity and the specified rest frequency
299 // (default reference type LSRK)
300 // <group>
301 static MFrequency fromDoppler(const MDoppler &dop,
302 const MVFrequency &rest);
303 static MFrequency fromDoppler(const MDoppler &dop,
304 const MVFrequency &rest,
305 MFrequency::Types type);
306 // For internal use only
307 static MFrequency fromDoppler(const Measure &dop,
308 const MVFrequency &rest,
309 MFrequency::Types type);
310 // </group>
311
312 // Make a rest frequency using a Doppler velocity
313 MFrequency toRest(const MDoppler &dop) const;
314 // For local use only
315 static MFrequency toRest(const Measure &in, const Measure &dop);
316
317 // Make a copy
318 // <group>
319 virtual Measure *clone() const;
320 // </group>
321
322 private:
323 //# Enumerations
324
325 //# Data
326
327 //# Member functions
328
329};
330
331
332} //# NAMESPACE CASACORE - END
333
334#endif
static Bool getType(MFrequency::Types &tp, const String &in)
Translate string to reference code.
MFrequency(const MVFrequency &dt, MFrequency::Types rf)
virtual Bool setRefString(const String &in)
Set the reference type to the specified String.
MDoppler toDoppler(const MVFrequency &rest)
Make a Doppler velocity from the frequency and the specified rest frequency.
static void checkMyTypes()
MeasConvert< MFrequency > Convert
Measure conversion use (i.e.
Definition MFrequency.h:204
MFrequency(const Quantity &dt, MFrequency::Types rf)
static void assure(const Measure &in)
static MFrequency toRest(const Measure &in, const Measure &dop)
For local use only.
virtual void checkTypes() const
Check if all internal tables of types (both enum and String) are complete and correct.
MFrequency(const Quantity &dt)
MCFrequency MCType
Measure conversion routines for this class (i.e.
Definition MFrequency.h:200
Types
Types of known MFrequencies Warning: The order defines the order in the translation matrix FromTo in...
Definition MFrequency.h:176
@ EXTRA
all extra bits
Definition MFrequency.h:190
static MFrequency fromDoppler(const Measure &dop, const MVFrequency &rest, MFrequency::Types type)
For internal use only.
MeasRef< MFrequency > Ref
Measure reference (i.e.
Definition MFrequency.h:202
static const String & showType(uInt tp)
virtual const String & tellMe() const
Tell me your type.
MFrequency(const Measure *dt)
virtual const String & getDefaultType() const
Get the default reference type.
MFrequency(const MVFrequency &dt, const MFrequency::Ref &rf)
MFrequency()
Tip: In the following constructors and other functions, all MeasRef can be replaced with simple Measu...
static MFrequency fromDoppler(const MDoppler &dop, const MVFrequency &rest, MFrequency::Types type)
static const String & showType(MFrequency::Types tp)
ScalarMeasColumn< MFrequency > ScalarColumn
Measure table Columns (e.g., MFrequency::ScalarColumn)
Definition MFrequency.h:206
MVFrequency MVType
Measure value container for this class (i.e.
Definition MFrequency.h:198
MFrequency(const MeasValue *dt)
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...
ArrayMeasColumn< MFrequency > ArrayColumn
Definition MFrequency.h:207
virtual Bool setOffset(const Measure &in)
Set the offset in the reference (False if non-matching Measure)
MDoppler toDoppler(const MVFrequency &rest) const
static const String & showMe()
virtual const String * allTypes(Int &nall, Int &nextra, const uInt *&typ) const
Get a list of all known reference codes.
static MFrequency::Types typeFromString(const String &in)
Throws an exception if the type string is not recognized.
static MFrequency::Types castType(uInt tp)
Translate reference code.
Quantity get(const Unit &un) const
Get frequency in specified units.
Bool giveMe(MFrequency::Ref &mr, const String &in)
MFrequency(const MVFrequency &dt)
Create from data and reference.
virtual Measure * clone() const
Make a copy.
static const String * allMyTypes(Int &nall, Int &nextra, const uInt *&typ)
static MDoppler toDoppler(const Measure &in, const MVFrequency &rest)
Local use only.
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_)
MFrequency(const Quantity &dt, const MFrequency::Ref &rf)
String: the storage and methods of handling collections of characters.
Definition String.h:225
this file contains all the compiler specific defines
Definition mainpage.dox:28
unsigned int uInt
Definition aipstype.h:51
int Int
Definition aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42