astSlaAdd

Add a celestial coordinate conversion to an SlaMap

Description:

This function adds one of the standard celestial coordinate system conversions provided by the SLALIB Positional Astronomy Library (Starlink User Note SUN/67) to an existing SlaMap.

When an SlaMap is first created (using astSlaMap), it simply performs a unit (null) Mapping. By using astSlaAdd (repeatedly if necessary), one or more coordinate conversion steps may then be added, which the SlaMap will perform in sequence. This allows multi-step conversions between a variety of celestial coordinate systems to be assembled out of the building blocks provided by SLALIB.

Normally, if an SlaMap s Invert attribute is zero (the default), then its forward transformation is performed by carrying out each of the individual coordinate conversions specified by astSlaAdd in the order given (i.e. with the most recently added conversion applied last).

This order is reversed if the SlaMap 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 SlaMap. In this case, the first conversion to be applied would be the inverse of the one most recently added.

Synopsis

void astSlaAdd( AstSlaMap this, const char cvt, int narg, const double args[] )

Parameters:

this
Pointer to the SlaMap.
cvt
Pointer to a null-terminated string which identifies the celestial coordinate conversion to be added to the SlaMap. See the " SLALIB Conversions" section for details of those available.
narg
The number of argument values supplied in the " args" array.
args
An array containing argument values for the celestial coordinate conversion. The number of arguments required, and hence the number of array elements used, depends on the conversion specified (see the " SLALIB Conversions" section). This array is ignored and a NULL pointer may be supplied if no arguments are needed.

Notes:

SLALIB Conversions

The following strings (which are case-insensitive) may be supplied via the " cvt" parameter to indicate which celestial coordinate conversion is to be added to the SlaMap. Each string is derived from the name of the SLALIB routine that performs the conversion and the relevant documentation (SUN/67) should be consulted for details. 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. The argument names match the corresponding SLALIB routine arguments and their values should be given using exactly the same units, time scale, calendar, etc. as described in SUN/67:

For example, to use the " ADDET" conversion, which takes a single argument EQ, you should consult the documentation for the SLALIB routine SLA_ADDET. This describes the conversion in detail and shows that EQ is the Besselian epoch of the mean equator and equinox. This value should then be supplied to astSlaAdd in args[0].

In addition the following strings may be supplied for more complex conversions which do not correspond to any one single SLALIB routine (DIURAB is the magnitude of the diurnal aberration vector in units of " day/(2.PI)" , DATE is the Modified Julian Date of the observation, and (OBSX,OBSY,OBZ) are the Heliocentric-Aries-Ecliptic cartesian coordinates, in metres, of the observer):

Note, the " H2E" and " E2H" conversions convert between topocentric horizon coordinates (azimuth,elevation), and apparent local equatorial coordinates (hour angle,declination). Thus, the effects of diurnal aberration are taken into account in the conversions but the effects of atmospheric refraction are not.