casacore
FITSSpectralUtil.h
Go to the documentation of this file.
1 //# FITSSpectralUtil.h: Static functions to help with FITS spectral axes.
2 //# Copyright (C) 2002
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 
30 #ifndef FITS_FITSSPECTRALUTIL_H
31 #define FITS_FITSSPECTRALUTIL_H
32 
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/Arrays/ArrayFwd.h>
35 #include <casacore/measures/Measures/MDoppler.h>
36 #include <casacore/measures/Measures/MFrequency.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 class RecordInterface;
41 class String;
42 class LogIO;
43 
44 // <summary>
45 // A class with static functions to help deal with FITS spectral axes.
46 // </summary>
47 
48 // <use visibility=export>
49 
50 // <reviewed reviewer="Eric Sessoms" date="2002/08/19" tests="tFITSSpectralUtil.cc">
51 // </reviewed>
52 
53 // <prerequisite>
54 // <li> General knowlege of FITS, FITS keywords, and FITS coordinate
55 // conventions is assumed.
56 // <li> Presumably you are using this in conjuction with the
57 // <linkto class=FITSKeywordUtil>FITSKeywordUtil</linkto> class
58 // to get or set the FITS coordinate axis information.
59 // </prerequisite>
60 
61 // <etymology>
62 // This is a collection of static utility functions for use with
63 // FITS spectral axes.
64 // </etymology>
65 
66 // <synopsis>
67 // This class provides functions to extract information from a FITS
68 // header about the spectral axis, to setup a FITS header with
69 // appropriate information for the spectral axis, and to translate
70 // to and from the MFrequency reference frame codes and their FITS
71 // equivalents.
72 // It is never necessary to construct a FITSSpectralUtil, just use the
73 // static functions to help handle FITS Spectral axes.
74 // </synopsis>
75 //
76 // <example>
77 // <srcblock>
78 // Record rec;
79 // ... extract the FITS keyword values into rec using FITSKeywordUtil
80 // Int whichAxis;
81 // Double refPix, refFreq, freqInc, restFreq;
82 // Vector<Double> freqs;
83 // MFrequency::Types refFrame;
84 // MDoppler::Types veldef;
85 // LogIO logger;
86 // FITSSpectralUtil::fromFITSHeader(whichAxis, refPix, refFreq,
87 // freqInc, freqs, refFrame, veldef, logger, rec);
88 // </srcblock>
89 // </example>
90 //
91 // <motivation>
92 // This is designed to be used after the keywords have been extracted from
93 // the FITS file using the <linkto class=FITSKeywordUtil>FITSKeywordUtil</linkto>
94 // class. Extracting spectral axis and related information requires detailed
95 // knowledge of FITS conventions that this class strives to encapsulize.
96 // </motivation>
97 //
98 // <todo asof="2011/11/30">
99 // <li> General usage of units for frequency and velocity in "fromFITSHeader"
100 // (currently only implemented for wavelength)
101 // </todo>
102 
104 {
105 public:
106  // Get information about the spectral axis from a record containing the
107  // FITS axis information. Usually this will be from a FITS header using,
108  // for example, the FITSKeywordUtil::getKeywords method.
109  // referenceFrequency and deltaFrequency give the best
110  // possible linear frequency scale. prefix is the first character in the
111  // set of keywords describing the axes (e.g. crpix, crval, ctype - the prefix is
112  // 'c'). If oneRelative is False, the returned referenceChannel is decrimented
113  // from that found in header by 1. The naxis keywords are used to determine
114  // the output length of the freqs vector.
115  // This method returns False if:
116  // <ul>
117  // <li> no spectral axis is found. The freqs vector will have a length of zero.
118  // <li> The expected set of axis description keywords is not found.
119  // <li> The spectral axis is FELO but there is no rest frequency (making it
120  // impossible to convert to frequency and construct a freqs vector).
121  // <li> The combination FELO and RADIO is used (which does not make sense).
122  // <li> The combination VELO and OPTICAL is used (not yet implemented).
123  // </ul>
124  static Bool fromFITSHeader(Int &spectralAxis,
125  Double &referenceChannel,
126  Double &referenceFrequency,
127  Double &deltaFrequency,
128  Vector<Double> &frequencies,
129  MFrequency::Types &refFrame,
130  MDoppler::Types &velocityPreference,
131  Double &restFrequency,
132  LogIO &logger,
133  const RecordInterface &header,
134  char prefix = 'c',
135  Bool oneRelative=True);
136 
137  // Nearly the inverse of fromFITSHeader. This returns parameters which could
138  // be used in filling in a header record with appropriate values for
139  // the spectral axis given the arguments after the logger.
140  // The alternate axis description values are set when sufficient information is available.
141  // If they have been set, haveAlt will be set to True.
142  // <ul>
143  // <li> Note that the output arguments after "haveAlt"
144  // should not be written to the FITS header unless haveAlt is true.
145  // <li> Note that restfreq is both an input and an output. If there is no
146  // rest frequency, set it to be <=0 on input.
147  // </ul>
148  // If preferVelocity is True, the
149  // axis description parameters will be set to those appropriate for
150  // a velocity axis given the referenceFrame, and velocityPreference
151  // if possible.
152  // If preferWavelength is True, the
153  // axis description parameters will be set to those appropriate for
154  // a wavelength axis given the referenceFrame if possible.
155  // The two preferences cannot be True at the same time.
156  // If airWavelength is True, the
157  // axis description parameters will be set to those appropriate for
158  // an air wavelength axis given the referenceFrame if possible.
159  // This parameter has an effect only if preferWavelength is True.
160 
161  // This method always returns True.
162  static Bool toFITSHeader(String &ctype,
163  Double &crval,
164  Double &cdelt,
165  Double &crpix,
166  String &cunit,
167  Bool &haveAlt,
168  Double &altrval,
169  Double &altrpix,
170  Int &velref,
171  Double &restfreq,
172  String &specsys,
173  LogIO &logger,
174  Double refFrequency,
175  Double refChannel,
176  Double freqIncrement,
177  MFrequency::Types referenceFrame,
178  Bool preferVelocity = True,
179  MDoppler::Types velocityPreference = MDoppler::OPTICAL,
180  Bool preferWavelength = False,
181  Bool airWavelength = False,
182  Bool useDeprecatedCtypes = False);
183 
184  // Convert a reference frame tag (typically found as the characters
185  // after the first 4 characters in a ctype string for the
186  // frequency-like axis) to a MFrequency::Types value.
187  // A velref value (used in AIPS images to alternatively record
188  // the velocity reference frame) may also optionally be supplied.
189  // If tag is empty, velref will be used if it is >= 0.
190  // This function returns False if:
191  // <ul>
192  // <li> The tag is not empty but is unrecognized.
193  // <li> The tag is empty and velref is unrecognized.
194  // <li> The tag is empty and velref is < 0 (no velref was supplied).
195  // </ul>
196  // The default value (set when the return value is False) is TOPO.
197  static Bool frameFromTag(MFrequency::Types &referenceFrame,
198  const String &tag,
199  Int velref=-1);
200 
201  // Construct a reference frame tag from the given referenceFrame
202  // An appropriate velref value is also constructed (this may need
203  // to be adjusted by +256 if the velocity definition is radio before
204  // being used in a FITS file). This returns False if the
205  // reference frame is not recognized. The value of tag defaults
206  // to "-OBS".
207  static Bool tagFromFrame(String &tag, Int &velref,
208  MFrequency::Types referenceFrame);
209 
210  // Construct a SPECSYS keyword value from the given referenceFrame
211  // This returns False if the reference frame is not recognized.
212  // The value of tag defaults to "TOPOCENT".
213  static Bool specsysFromFrame(String &specsys,
214  MFrequency::Types referenceFrame);
215 
216  static Bool frameFromSpecsys(MFrequency::Types& refFrame, String& specsys);
217 
218  // The refractive index of air (argument can be vacuum wavelength or airwavelength)
219  // according to Greisen et al., 2006, A&A, 464, 746.
220  // If vacuum wavelength is used there is an error of the order of 1E-9.
221  // Argument must be in micrometers!
222  static Double refractiveIndex(const Double& lambda_um);
223 };
224 
225 
226 } //# NAMESPACE CASACORE - END
227 
228 #endif
static Bool toFITSHeader(String &ctype, Double &crval, Double &cdelt, Double &crpix, String &cunit, Bool &haveAlt, Double &altrval, Double &altrpix, Int &velref, Double &restfreq, String &specsys, LogIO &logger, Double refFrequency, Double refChannel, Double freqIncrement, MFrequency::Types referenceFrame, Bool preferVelocity=True, MDoppler::Types velocityPreference=MDoppler::OPTICAL, Bool preferWavelength=False, Bool airWavelength=False, Bool useDeprecatedCtypes=False)
Nearly the inverse of fromFITSHeader.
static Bool fromFITSHeader(Int &spectralAxis, Double &referenceChannel, Double &referenceFrequency, Double &deltaFrequency, Vector< Double > &frequencies, MFrequency::Types &refFrame, MDoppler::Types &velocityPreference, Double &restFrequency, LogIO &logger, const RecordInterface &header, char prefix='c', Bool oneRelative=True)
Get information about the spectral axis from a record containing the FITS axis information.
static Bool frameFromTag(MFrequency::Types &referenceFrame, const String &tag, Int velref=-1)
Convert a reference frame tag (typically found as the characters after the first 4 characters in a ct...
static Bool frameFromSpecsys(MFrequency::Types &refFrame, String &specsys)
static Double refractiveIndex(const Double &lambda_um)
The refractive index of air (argument can be vacuum wavelength or airwavelength) according to Greisen...
static Bool specsysFromFrame(String &specsys, MFrequency::Types referenceFrame)
Construct a SPECSYS keyword value from the given referenceFrame This returns False if the reference f...
static Bool tagFromFrame(String &tag, Int &velref, MFrequency::Types referenceFrame)
Construct a reference frame tag from the given referenceFrame An appropriate velref value is also con...
Types
Types of known MDopplers Warning: The order defines the order in the translation matrix FromTo in th...
Definition: MDoppler.h:149
Types
Types of known MFrequencies Warning: The order defines the order in the translation matrix FromTo in...
Definition: MFrequency.h:176
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
const Bool False
Definition: aipstype.h:44
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43
double Double
Definition: aipstype.h:55