Add a spectral coordinate conversion to a SpecMap
When a SpecMap is first created (using astSpecMap), it simply performs a unit (null) Mapping. By using astSpecAdd (repeatedly if necessary), one or more coordinate conversion steps may then be added, which the SpecMap will perform in sequence. This allows multi-step conversions between a variety of spectral coordinate systems to be assembled out of the building blocks provided by this class.
Normally, if a SpecMap’
s Invert attribute is zero (the default), then its forward
transformation is performed by carrying out each of the individual coordinate
conversions specified by astSpecAdd in the order given (i.e. with the most recently
added conversion applied last).
This order is reversed if the SpecMap’
s Invert attribute is non-zero (or if the
inverse transformation is requested by any other means) and each individual coordinate
conversion is also replaced by its own inverse. This process inverts the overall effect
of the SpecMap. In this case, the first conversion to be applied would be the
inverse of the one most recently added.
"
Available Conversions"
section for details of
those available. "
args"
array.
"
Available Conversions"
section). This array is
ignored and a NULL pointer may be supplied if no arguments are needed. When assembling a multi-stage conversion, it can sometimes be difficult to determine the most economical conversion path. For example, when converting between reference frames, converting first to the heliographic reference frame as an intermediate stage is often sensible in formulating the problem, but may introduce unnecessary extra conversion steps. A solution to this is to include all the steps which are (logically) necessary, but then to use astSimplify to simplify the resulting SpecMap. The simplification process will eliminate any steps which turn out not to be needed.
This function does not check to ensure that the sequence of coordinate conversions added to a SpecMap is physically meaningful.
"
cvt"
parameter to
indicate which spectral coordinate conversion is to be added to the SpecMap.
Where arguments are needed by the conversion, they are listed in parentheses.
Values for these arguments should be given, via the "
args"
array, in the order
indicated. Units and argument names are described at the end of the list of
conversions.
"
FRTOVL"
(RF): Convert frequency to relativistic velocity.
"
VLTOFR"
(RF): Convert relativistic velocity to Frequency.
"
ENTOFR"
: Convert energy to frequency.
"
FRTOEN"
: Convert frequency to energy.
"
WNTOFR"
: Convert wave number to frequency.
"
FRTOWN"
: Convert frequency to wave number.
"
WVTOFR"
: Convert wavelength (vacuum) to frequency.
"
FRTOWV"
: Convert frequency to wavelength (vacuum).
"
AWTOFR"
: Convert wavelength (air) to frequency.
"
FRTOAW"
: Convert frequency to wavelength (air).
"
VRTOVL"
: Convert radio to relativistic velocity.
"
VLTOVR"
: Convert relativistic to radio velocity.
"
VOTOVL"
: Convert optical to relativistic velocity.
"
VLTOVO"
: Convert relativistic to optical velocity.
"
ZOTOVL"
: Convert redshift to relativistic velocity.
"
VLTOZO"
: Convert relativistic velocity to redshift.
"
BTTOVL"
: Convert beta factor to relativistic velocity.
"
VLTOBT"
: Convert relativistic velocity to beta factor.
"
USF2HL"
(VOFF,RA,DEC): Convert frequency from a user-defined reference frame to
heliocentric.
"
HLF2US"
(VOFF,RA,DEC): Convert frequency from heliocentric reference frame to
user-defined.
"
TPF2HL"
(OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from topocentric
reference frame to heliocentric.
"
HLF2TP"
(OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from heliocentric
reference frame to topocentric.
"
GEF2HL"
(EPOCH,RA,DEC): Convert frequency from geocentric reference frame to
heliocentric.
"
HLF2GE"
(EPOCH,RA,DEC): Convert frequency from heliocentric reference frame to
geocentric.
"
BYF2HL"
(EPOCH,RA,DEC): Convert frequency from barycentric reference frame to
heliocentric.
"
HLF2BY"
(EPOCH,RA,DEC): Convert frequency from heliocentric reference frame to
barycentric.
"
LKF2HL"
(RA,DEC): Convert frequency from kinematic LSR reference frame to
heliocentric.
"
HLF2LK"
(RA,DEC): Convert frequency from heliocentric reference frame to kinematic
LSR.
"
LDF2HL"
(RA,DEC): Convert frequency from dynamical LSR reference frame to
heliocentric.
"
HLF2LD"
(RA,DEC): Convert frequency from heliocentric reference frame to dynamical
LSR.
"
LGF2HL"
(RA,DEC): Convert frequency from local group reference frame to heliocentric.
"
HLF2LG"
(RA,DEC): Convert frequency from heliocentric reference frame to local
group.
"
GLF2HL"
(RA,DEC): Convert frequency from galactic reference frame to heliocentric.
"
HLF2GL"
(RA,DEC): Convert frequency from heliocentric reference frame to
galactic.
The units for the values processed by the above conversions are as follows:
all velocities: metres per second (positive if the source receeds from the observer).
frequency: Hertz.
all wavelengths: metres.
energy: Joules.
wave number: cycles per metre.
The arguments used in the above conversions are as follows:
RF: Rest frequency (Hz).
OBSALT: Geodetic altitude of observer (IAU 1975, metres).
OBSLAT: Geodetic latitude of observer (IAU 1975, radians).
OBSLON: Longitude of observer (radians - positive eastwards).
EPOCH: Epoch of observation (UT1 expressed as a Modified Julian Date).
RA: Right Ascension of source (radians, FK5 J2000).
DEC: Declination of source (radians, FK5 J2000).
VOFF: Velocity of the user-defined reference frame, towards the position given by RA and DEC, measured in the heliocentric reference frame.
If the SpecMap is 3-dimensional, source positions are provided by the values supplied
to inputs 2 and 3 of the SpecMap (which are simply copied to outputs 2 and 3). Note,
usable values are still required for the RA and DEC arguments in order to define the "
user-defined"
reference frame used by USF2HL and HLF2US. However, AST__BAD can be
supplied for RA and DEC if the user-defined reference frame is not required.