- General knowlege of FITS, FITS keywords, and FITS coordinate
conventions is assumed.
- Presumably you are using this in conjuction with the
FITSKeywordUtil class
to get or set the FITS coordinate axis information.
Etymology
This is a collection of static utility functions for use with
FITS spectral axes.
Synopsis
This class provides functions to extract information from a FITS
header about the spectral axis, to setup a FITS header with
appropriate information for the spectral axis, and to translate
to and from the MFrequency refrence frame codes and their FITS
equivalents.
It is never necessary to construct a FITSSpectralUtil, just use the
static functions to help handle FITS Spectral axes.
Example
Record rec;
... extract the FITS keyword values into rec using FITSKeywordUtil
Int whichAxis;
Double refPix, refFreq, freqInc, restFreq;
Vector<Double> freqs;
MFrequency::Types refFrame;
MDoppler::Types veldef;
LogIO logger;
FITSSpectralUtil::fromFITSHeader(whichAxis, refPix, refFreq,
freqInc, freqs, refFrame, veldef, logger, rec);
Motivation
This is designed to be used after the keywords have been extracted from
the FITS file using the FITSKeywordUtil
class. Extracting spectral axis and related information requires detailed
knowledge of FITS conventions that this class strives to encapsulize.
Member Description
static Bool fromFITSHeader(Int &spectralAxis, Double &referenceChannel, Double &referenceFrequency, Double &deltaFrequency, Vector<Double> &frequencies, MFrequency::Types &refFrame, MDoppler::Types &velocityPreference, Double &restFrequency, MDoppler &logger, const RecordInterface &header, char prefix = 'c', Bool oneRelative=True)
Get information about the spectral axis from a record containing the
FITS axis information. Usually this will be from a FITS header using,
for example, the FITSKeywordUtil::getKeywords method.
referenceFrequency and deltaFrequency give the best
possible linear frequency scale. prefix is the first character in the
set of keywords describing the axes (e.g. crpix, crval, ctype - the prefix is
'c'). If oneRelative is False, the returned referenceChannel is decrimented
from that found in header by 1. The naxis keywords are used to determine
the output length of the freqs vector.
This method returns False if:
- no spectral axis is found. The freqs vector will have a length of zero.
- The expected set of axis description keywords is not found.
- The spectral axis is FELO but there is no rest frequency (making it
impossible to convert to frequency and construct a freqs vector).
- The combination FELO and RADIO is used (which does not make sense).
- The combination VELO and OPTICAL is used (not yet implemented).
static Bool toFITSHeader(String &ctype, Double &crval, Double &cdelt, Double &crpix, Bool &haveAlt, Double &altrval, Double &altrpix, Int &velref, Double &restfreq, LogIO &logger, Double refFrequency, Double refChannel, Double freqIncrement, MFrequency::Types referenceFrame, Bool preferVelocity = True, MDoppler::Types velocityPreference = MDoppler::OPTICAL)
Nearly the inverse of fromFITSHeader. This returns parameters which could
be used in filling in a header record with appropriate values for
the spectral axis given the arguments after the logger.
The alternate axis description values are set when sufficient information is available.
If they have been set, haveAlt will be set to True.
- Note that the output arguments after "haveAlt"
should not be written to the FITS header unless haveAlt is true.
- Note that restfreq is both an input and an output. If there is no rest
frequency, set it to be <=0 on input.
If preferVelocity is True, the
axis description parameters will be set to those appropriate for
a velocity axis given the referenceFrame, and velocityPreference
if possible.
This method always returns True.
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 ctype string for the
frequency-like axis) to a MFrequency::Types value.
A velref value (used in AIPS images to alternatively record
the velocity reference frame) may also optionally be supplied.
If tag is empty, velref will be used if it is >= 0.
This function returns False if:
- The tag is not empty but is unrecognized.
- The tag is empty and velref is unrecognized.
- The tag is empty and velref is < 0 (no velref was supplied).
The default value (set when the return value is False) is TOPO.
Construct a reference frame tag from the given referenceFrame
An appropriate velref value is also constructed (this may need
to be adjusted by +256 if the velocity definition is radio before
being used in a FITS file). This returns False if the
reference frame is not recognized. The value of tag defaults
to "-OBS".