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