AST_SPECADD

Add a spectral coordinate conversion to a SpecMap

Description:

This routine adds one of the standard spectral coordinate system conversions listed below to an existing SpecMap.

When a SpecMap is first created (using AST_SPECMAP), it simply performs a unit (null) Mapping. By using AST_SPECADD (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 AST_SPECADD 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.

Invocation

CALL AST_SPECADD( THIS, CVT, NARG, ARGS, STATUS )

Arguments

THIS = INTEGER (Given)
Pointer to the SpecMap.
CVT = CHARACTER ( ) (Given)
A character string which identifies the spectral coordinate conversion to be added to the SpecMap. See the " Available Conversions" section for details of those available.
NARG = INTEGER (Given)
The number of argument values supplied in the ARGS array.
ARGS( ) = DOUBLE PRECISION (Given)
An array containing argument values for the spectral coordinate conversion. The number of arguments required, and hence the number of array elements used, depends on the conversion specified (see the " Available Conversions" section). This array is ignored if no arguments are needed.
STATUS = INTEGER (Given and Returned)
The global status.

Notes:

Available Conversions

The following strings (which are case-insensitive) may be supplied via the CVT argument 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.

The units for the values processed by the above conversions are as follows:

The arguments used in the above conversions are as follows:

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.