#include "spx.h"
#include "wcserr.h"

Data Structures
struct	spcprm
	Spectral transformation parameters. More...

Macros
#define	SPCLEN (sizeof(struct spcprm)/sizeof(int))
	Size of the spcprm struct in int units. More...

#define	spcini_errmsg spc_errmsg
	Deprecated. More...

#define	spcprt_errmsg spc_errmsg
	Deprecated. More...

#define	spcset_errmsg spc_errmsg
	Deprecated. More...

#define	spcx2s_errmsg spc_errmsg
	Deprecated. More...

#define	spcs2x_errmsg spc_errmsg
	Deprecated. More...

Enumerations
enum	spc_errmsg_enum { SPCERR_NO_CHANGE = -1, SPCERR_SUCCESS = 0, SPCERR_NULL_POINTER = 1, SPCERR_BAD_SPEC_PARAMS = 2, SPCERR_BAD_X = 3, SPCERR_BAD_SPEC = 4 }

Functions
int	spcini (struct spcprm *spc)
	Default constructor for the spcprm struct. More...

int	spcfree (struct spcprm *spc)
	Destructor for the spcprm struct. More...

int	spcprt (const struct spcprm *spc)
	Print routine for the spcprm struct. More...

int	spcset (struct spcprm *spc)
	Setup routine for the spcprm struct. More...

int	spcx2s (struct spcprm *spc, int nx, int sx, int sspec, const double x[], double spec[], int stat[])
	Transform to spectral coordinates. More...

int	spcs2x (struct spcprm *spc, int nspec, int sspec, int sx, const double spec[], double x[], int stat[])
	Transform spectral coordinates. More...

int	spctype (const char ctype[9], char stype[], char scode[], char sname[], char units[], char ptype, char xtype, int restreq, struct wcserr *err)
	Spectral `CTYPEia` keyword analysis. More...

int	spcspxe (const char ctypeS[9], double crvalS, double restfrq, double restwav, char ptype, char xtype, int restreq, double crvalX, double dXdS, struct wcserr *err)
	Spectral keyword analysis. More...

int	spcxpse (const char ctypeS[9], double crvalX, double restfrq, double restwav, char ptype, char xtype, int restreq, double crvalS, double dSdX, struct wcserr *err)
	Spectral keyword synthesis. More...

int	spctrne (const char ctypeS1[9], double crvalS1, double cdeltS1, double restfrq, double restwav, char ctypeS2[9], double crvalS2, double cdeltS2, struct wcserr **err)
	Spectral keyword translation. More...

int	spcaips (const char ctypeA[9], int velref, char ctype[9], char specsys[9])
	Translate AIPS-convention spectral keywords. More...

int	spctyp (const char ctype[9], char stype[], char scode[], char sname[], char units[], char ptype, char xtype, int *restreq)

int	spcspx (const char ctypeS[9], double crvalS, double restfrq, double restwav, char ptype, char xtype, int restreq, double crvalX, double *dXdS)

int	spcxps (const char ctypeS[9], double crvalX, double restfrq, double restwav, char ptype, char xtype, int restreq, double crvalS, double *dSdX)

int	spctrn (const char ctypeS1[9], double crvalS1, double cdeltS1, double restfrq, double restwav, char ctypeS2[9], double crvalS2, double cdeltS2)

Variables
const char *	spc_errmsg []
	Status return messages. More...

Detailed Description

These routines implement the part of the FITS WCS standard that deals with spectral coordinates. They define methods to be used for computing spectral world coordinates from intermediate world coordinates (a linear transformation of image pixel coordinates), and vice versa. They are based on the spcprm struct which contains all information needed for the computations. The struct contains some members that must be set by the user, and others that are maintained by these routines, somewhat like a C++ class but with no encapsulation.

Routine spcini() is provided to initialize the spcprm struct with default values, spcfree() reclaims any memory that may have been allocated to store an error message, and spcprt() prints its contents.

A setup routine, spcset(), computes intermediate values in the spcprm struct from parameters in it that were supplied by the user. The struct always needs to be set up by spcset() but it need not be called explicitly - refer to the explanation of spcprm::flag.

spcx2s() and spcs2x() implement the WCS spectral coordinate transformations. In fact, they are high level driver routines for the lower level spectral coordinate transformation routines described in spx.h.

A number of routines are provided to aid in analysing or synthesising sets of FITS spectral axis keywords:

spctype() checks a spectral CTYPEia keyword for validity and returns information derived from it.
Spectral keyword analysis routine spcspxe() computes the values of the -type spectral variables for the -type variables supplied.
Spectral keyword synthesis routine, spcxpse(), computes the -type variables for the -types supplied.
Given a set of spectral keywords, a translation routine, spctrne(), produces the corresponding set for the specified spectral CTYPEia.
spcaips() translates AIPS-convention spectral CTYPEia and VELREF keyvalues.

Spectral variable types - , , and :
A few words of explanation are necessary regarding spectral variable types in FITS.

Every FITS spectral axis has three associated spectral variables:

$S$ -type: the spectral variable in which coordinates are to be expressed. Each $S$ -type is encoded as four characters and is linearly related to one of four basic types as follows:

F: frequency 'FREQ': frequency 'AFRQ': angular frequency 'ENER': photon energy 'WAVN': wave number 'VRAD': radio velocity

W: wavelength in vacuo 'WAVE': wavelength 'VOPT': optical velocity 'ZOPT': redshift

A: wavelength in air 'AWAV': wavelength in air

V: velocity 'VELO': relativistic velocity 'BETA': relativistic beta factor

The $S$ -type forms the first four characters of the CTYPEia keyvalue, and CRVALia and CDELTia are expressed as $S$ -type quantities so that they provide a first-order approximation to the $S$ -type variable at the reference point.

Note that 'AFRQ', angular frequency, is additional to the variables defined in WCS Paper III.

$P$ -type: the basic spectral variable (F, W, A, or V) with which the $S$ -type variable is associated (see list above).

For non-grism axes, the $P$ -type is encoded as the eighth character of CTYPEia.

$X$ -type: the basic spectral variable (F, W, A, or V) for which the spectral axis is linear, grisms excluded (see below).

For non-grism axes, the $X$ -type is encoded as the sixth character of CTYPEia.

Grisms: Grism axes have normal $S$ -, and $P$ -types but the axis is linear, not in any spectral variable, but in a special "grism parameter". The $X$ -type spectral variable is either W or A for grisms in vacuo or air respectively, but is encoded as 'w' or 'a' to indicate that an additional transformation is required to convert to or from the grism parameter. The spectral algorithm code for grisms also has a special encoding in CTYPEia, either 'GRI' (in vacuo) or 'GRA' (in air).

In the algorithm chain, the non-linear transformation occurs between the $X$ -type and the $P$ -type variables; the transformation between $P$ -type and $S$ -type variables is always linear.

When the $P$ -type and $X$ -type variables are the same, the spectral axis is linear in the $S$ -type variable and the second four characters of CTYPEia are blank. This can never happen for grism axes.

As an example, correlating radio spectrometers always produce spectra that are regularly gridded in frequency; a redshift scale on such a spectrum is non-linear. The required value of CTYPEia would be 'ZOPT-F2W', where the desired $S$ -type is 'ZOPT' (redshift), the $P$ -type is necessarily 'W' (wavelength), and the $X$ -type is 'F' (frequency) by the nature of the instrument.

Argument checking:
The input spectral values are only checked for values that would result in floating point exceptions. In particular, negative frequencies and wavelengths are allowed, as are velocities greater than the speed of light. The same is true for the spectral parameters - rest frequency and wavelength.

Accuracy:
No warranty is given for the accuracy of these routines (refer to the copyright notice); intending users must satisfy for themselves their adequacy for the intended purpose. However, closure effectively to within double precision rounding error was demonstrated by test routine tspc.c which accompanies this software.

Macro Definition Documentation

#define SPCLEN (sizeof(struct spcprm)/sizeof(int))

Size of the spcprm struct in int units, used by the Fortran wrappers.

#define spcini_errmsg spc_errmsg

Deprecated:: Added for backwards compatibility, use spc_errmsg directly now instead.

#define spcprt_errmsg spc_errmsg

Deprecated:: Added for backwards compatibility, use spc_errmsg directly now instead.

#define spcset_errmsg spc_errmsg

Deprecated:: Added for backwards compatibility, use spc_errmsg directly now instead.

#define spcx2s_errmsg spc_errmsg

Deprecated:: Added for backwards compatibility, use spc_errmsg directly now instead.

#define spcs2x_errmsg spc_errmsg

Deprecated:: Added for backwards compatibility, use spc_errmsg directly now instead.

Enumeration Type Documentation

enum spc_errmsg_enum

Enumerator
SPCERR_NO_CHANGE
SPCERR_SUCCESS
SPCERR_NULL_POINTER
SPCERR_BAD_SPEC_PARAMS
SPCERR_BAD_X
SPCERR_BAD_SPEC

Function Documentation

int spcini ( struct spcprm * spc)

spcini() sets all members of a spcprm struct to default values. It should be used to initialize every spcprm struct.

Parameters

[in,out] spc Spectral transformation parameters.

Returns

Status return value:

0: Success.
1: Null spcprm pointer passed.

int spcfree ( struct spcprm * spc)

spcfree() frees any memory that may have been allocated to store an error message in the spcprm struct.

Parameters

[in] spc Spectral transformation parameters.

Returns

Status return value:

0: Success.
1: Null spcprm pointer passed.

int spcprt ( const struct spcprm * spc)

spcprt() prints the contents of a spcprm struct using wcsprintf(). Mainly intended for diagnostic purposes.

Parameters

[in] spc Spectral transformation parameters.

Returns

Status return value:

0: Success.
1: Null spcprm pointer passed.

int spcset ( struct spcprm * spc)

spcset() sets up a spcprm struct according to information supplied within it.

Note that this routine need not be called directly; it will be invoked by spcx2s() and spcs2x() if spcprm::flag is anything other than a predefined magic value.

Parameters

[in,out] spc Spectral transformation parameters.

Returns

Status return value:

0: Success.
1: Null spcprm pointer passed.
2: Invalid spectral parameters.

For returns > 1, a detailed error message is set in spcprm::err if enabled, see wcserr_enable().

int spcx2s	(	struct spcprm *	spc,
		int	nx,
		int	sx,
		int	sspec,
		const double	x[],
		double	spec[],
		int	stat[]
	)

spcx2s() transforms intermediate world coordinates to spectral coordinates.

Parameters

[in,out]	spc	Spectral transformation parameters.
[in]	nx	Vector length.
[in]	sx	Vector stride.
[in]	sspec	Vector stride.
[in]	x	Intermediate world coordinates, in SI units.
[out]	spec	Spectral coordinates, in SI units.
[out]	stat	Status return value status for each vector element: 0: Success. 1: Invalid value of x.

Returns

Status return value:

0: Success.
1: Null spcprm pointer passed.
2: Invalid spectral parameters.
3: One or more of the x coordinates were invalid, as indicated by the stat vector.

For returns > 1, a detailed error message is set in spcprm::err if enabled, see wcserr_enable().

int spcs2x	(	struct spcprm *	spc,
		int	nspec,
		int	sspec,
		int	sx,
		const double	spec[],
		double	x[],
		int	stat[]
	)

spcs2x() transforms spectral world coordinates to intermediate world coordinates.

Parameters

[in,out]	spc	Spectral transformation parameters.
[in]	nspec	Vector length.
[in]	sspec	Vector stride.
[in]	sx	Vector stride.
[in]	spec	Spectral coordinates, in SI units.
[out]	x	Intermediate world coordinates, in SI units.
[out]	stat	Status return value status for each vector element: 0: Success. 1: Invalid value of spec.

Returns

Status return value:

0: Success.
1: Null spcprm pointer passed.
2: Invalid spectral parameters.
4: One or more of the spec coordinates were invalid, as indicated by the stat vector.

For returns > 1, a detailed error message is set in spcprm::err if enabled, see wcserr_enable().

int spctype	(	const char	ctype[9],
		char	stype[],
		char	scode[],
		char	sname[],
		char	units[],
		char *	ptype,
		char *	xtype,
		int *	restreq,
		struct wcserr **	err
	)

spctype() checks whether a CTYPEia keyvalue is a valid spectral axis type and if so returns information derived from it relating to the associated $S$ -, $P$ -, and $X$ -type spectral variables (see explanation above).

The return arguments are guaranteed not be modified if CTYPEia is not a valid spectral type; zero-pointers may be specified for any that are not of interest.

A deprecated form of this function, spctyp(), lacks the wcserr** parameter.

Parameters

[in]	ctype	The `CTYPEia` keyvalue, (eight characters with null termination).
[out]	stype	The four-letter name of the -type spectral variable copied or translated from ctype. If a non-zero pointer is given, the array must accomodate a null- terminated string of length 5.
[out]	scode	The three-letter spectral algorithm code copied or translated from ctype. Logarithmic ('`LOG`') and tabular ('`TAB`') codes are also recognized. If a non-zero pointer is given, the array must accomodate a null-terminated string of length 4.
[out]	sname	Descriptive name of the -type spectral variable. If a non-zero pointer is given, the array must accomodate a null-terminated string of length 22.
[out]	units	SI units of the -type spectral variable. If a non-zero pointer is given, the array must accomodate a null-terminated string of length 8.
[out]	ptype	Character code for the -type spectral variable derived from ctype, one of 'F', 'W', 'A', or 'V'.
[out]	xtype	Character code for the -type spectral variable derived from ctype, one of 'F', 'W', 'A', or 'V'. Also, 'w' and 'a' are synonymous to 'W' and 'A' for grisms in vacuo and air respectively. Set to 'L' or 'T' for logarithmic ('`LOG`') and tabular ('`TAB`') axes.
[out]	restreq	Multivalued flag that indicates whether rest frequency or wavelength is required to compute spectral variables for this `CTYPEia`: 0: Not required. 1: Required for the conversion between - and -types (e.g. `'ZOPT-F2W'`). 2: Required for the conversion between - and -types (e.g. `'BETA-W2V'`). 3: Required for the conversion between - and -types, and between - and -types, but not between - and -types (this applies only for `'VRAD-V2F'`, `'VOPT-V2W'`, and `'ZOPT-V2W'`). Thus the rest frequency or wavelength is required for spectral coordinate computations (i.e. between - and -types) only if restreq%3 != 0 .
[out]	err	If enabled, for function return values > 1, this struct will contain a detailed error message, see wcserr_enable(). May be NULL if an error message is not desired. Otherwise, the user is responsible for deleting the memory allocated for the wcserr struct.

Returns

Status return value:

0: Success.
2: Invalid spectral parameters (not a spectral CTYPEia).

int spcspxe	(	const char	ctypeS[9],
		double	crvalS,
		double	restfrq,
		double	restwav,
		char *	ptype,
		char *	xtype,
		int *	restreq,
		double *	crvalX,
		double *	dXdS,
		struct wcserr **	err
	)

spcspxe() analyses the CTYPEia and CRVALia FITS spectral axis keyword values and returns information about the associated $X$ -type spectral variable.

A deprecated form of this function, spcspx(), lacks the wcserr** parameter.

Parameters

[in]	ctypeS	Spectral axis type, i.e. the `CTYPEia` keyvalue, (eight characters with null termination). For non-grism axes, the character code for the -type spectral variable in the algorithm code (i.e. the eighth character of `CTYPEia`) may be set to '?' (it will not be reset).
[in]	crvalS	Value of the -type spectral variable at the reference point, i.e. the `CRVALia` keyvalue, SI units.
[in]	restfrq,restwav	Rest frequency [Hz] and rest wavelength in vacuo [m], only one of which need be given, the other should be set to zero.
[out]	ptype	Character code for the -type spectral variable derived from ctypeS, one of 'F', 'W', 'A', or 'V'.
[out]	xtype	Character code for the -type spectral variable derived from ctypeS, one of 'F', 'W', 'A', or 'V'. Also, 'w' and 'a' are synonymous to 'W' and 'A' for grisms in vacuo and air respectively; crvalX and dXdS (see below) will conform to these.
[out]	restreq	Multivalued flag that indicates whether rest frequency or wavelength is required to compute spectral variables for this `CTYPEia`, as for spctype().
[out]	crvalX	Value of the -type spectral variable at the reference point, SI units.
[out]	dXdS	The derivative, , evaluated at the reference point, SI units. Multiply the `CDELTia` keyvalue by this to get the pixel spacing in the -type spectral coordinate.
[out]	err	If enabled, for function return values > 1, this struct will contain a detailed error message, see wcserr_enable(). May be NULL if an error message is not desired. Otherwise, the user is responsible for deleting the memory allocated for the wcserr struct.

Returns

Status return value:

0: Success.
2: Invalid spectral parameters.

int spcxpse	(	const char	ctypeS[9],
		double	crvalX,
		double	restfrq,
		double	restwav,
		char *	ptype,
		char *	xtype,
		int *	restreq,
		double *	crvalS,
		double *	dSdX,
		struct wcserr **	err
	)

spcxpse(), for the spectral axis type specified and the value provided for the $X$ -type spectral variable at the reference point, deduces the value of the FITS spectral axis keyword CRVALia and also the derivative $dS/dX$ which may be used to compute CDELTia. See above for an explanation of the $S$ -, $P$ -, and $X$ -type spectral variables.

A deprecated form of this function, spcxps(), lacks the wcserr** parameter.

Parameters

[in]	ctypeS	The required spectral axis type, i.e. the `CTYPEia` keyvalue, (eight characters with null termination). For non-grism axes, the character code for the -type spectral variable in the algorithm code (i.e. the eighth character of `CTYPEia`) may be set to '?' (it will not be reset).
[in]	crvalX	Value of the -type spectral variable at the reference point (N.B. NOT the `CRVALia` keyvalue), SI units.
[in]	restfrq,restwav	Rest frequency [Hz] and rest wavelength in vacuo [m], only one of which need be given, the other should be set to zero.
[out]	ptype	Character code for the -type spectral variable derived from ctypeS, one of 'F', 'W', 'A', or 'V'.
[out]	xtype	Character code for the -type spectral variable derived from ctypeS, one of 'F', 'W', 'A', or 'V'. Also, 'w' and 'a' are synonymous to 'W' and 'A' for grisms; crvalX and cdeltX must conform to these.
[out]	restreq	Multivalued flag that indicates whether rest frequency or wavelength is required to compute spectral variables for this `CTYPEia`, as for spctype().
[out]	crvalS	Value of the -type spectral variable at the reference point (i.e. the appropriate `CRVALia` keyvalue), SI units.
[out]	dSdX	The derivative, , evaluated at the reference point, SI units. Multiply this by the pixel spacing in the -type spectral coordinate to get the `CDELTia` keyvalue.
[out]	err	If enabled, for function return values > 1, this struct will contain a detailed error message, see wcserr_enable(). May be NULL if an error message is not desired. Otherwise, the user is responsible for deleting the memory allocated for the wcserr struct.

Returns

Status return value:

0: Success.
2: Invalid spectral parameters.

int spctrne	(	const char	ctypeS1[9],
		double	crvalS1,
		double	cdeltS1,
		double	restfrq,
		double	restwav,
		char	ctypeS2[9],
		double *	crvalS2,
		double *	cdeltS2,
		struct wcserr **	err
	)

spctrne() translates a set of FITS spectral axis keywords into the corresponding set for the specified spectral axis type. For example, a 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.

A deprecated form of this function, spctrn(), lacks the wcserr** parameter.

Parameters

[in]	ctypeS1	Spectral axis type, i.e. the `CTYPEia` keyvalue, (eight characters with null termination). For non-grism axes, the character code for the -type spectral variable in the algorithm code (i.e. the eighth character of `CTYPEia`) may be set to '?' (it will not be reset).
[in]	crvalS1	Value of the -type spectral variable at the reference point, i.e. the `CRVALia` keyvalue, SI units.
[in]	cdeltS1	Increment of the -type spectral variable at the reference point, SI units.
[in]	restfrq,restwav	Rest frequency [Hz] and rest wavelength in vacuo [m], only one of which need be given, the other should be set to zero. Neither are required if the translation is between wave-characteristic types, or between velocity-characteristic types. E.g., required for '`FREQ`' -> `'ZOPT-F2W'`, but not required for `'VELO-F2V'` -> `'ZOPT-F2W'`.
[in,out]	ctypeS2	Required spectral axis type (eight characters with null termination). The first four characters are required to be given and are never modified. The remaining four, the algorithm code, are completely determined by, and must be consistent with, ctypeS1 and the first four characters of ctypeS2. A non-zero status value will be returned if they are inconsistent (see below). However, if the final three characters are specified as "???", or if just the eighth character is specified as '?', the correct algorithm code will be substituted (applies for grism axes as well as non-grism).
[out]	crvalS2	Value of the new -type spectral variable at the reference point, i.e. the new `CRVALia` keyvalue, SI units.
[out]	cdeltS2	Increment of the new -type spectral variable at the reference point, i.e. the new `CDELTia` keyvalue, SI units.
[out]	err	If enabled, for function return values > 1, this struct will contain a detailed error message, see wcserr_enable(). May be NULL if an error message is not desired. Otherwise, the user is responsible for deleting the memory allocated for the wcserr struct.

Returns

Status return value:

0: Success.
2: Invalid spectral parameters.

A status value of 2 will be returned if restfrq or restwav are not specified when required, or if ctypeS1 or ctypeS2 are self-inconsistent, or have different spectral $X$

-type variables.

int spcaips	(	const char	ctypeA[9],
		int	velref,
		char	ctype[9],
		char	specsys[9]
	)

spcaips() translates AIPS-convention spectral CTYPEia and VELREF keyvalues.

Parameters

[in]	ctypeA	`CTYPEia` keyvalue possibly containing an AIPS-convention spectral code (eight characters, need not be null-terminated).
[in]	velref	AIPS-convention `VELREF` code. It has the following integer values: 1: LSR kinematic, originally described simply as "LSR" without distinction between the kinematic and dynamic definitions. 2: Barycentric, originally described as "HEL" meaning heliocentric. 3: Topocentric, originally described as "OBS" meaning geocentric but widely interpreted as topocentric. AIPS++ extensions to `VELREF` are also recognized: 4: LSR dynamic. 5: Geocentric. 6: Source rest frame. 7: Galactocentric. For an AIPS '`VELO`' axis, a radio convention velocity (VRAD) is denoted by adding 256 to `VELREF`, otherwise an optical velocity (VOPT) is indicated (this is not applicable to '`FREQ`' or '`FELO`' axes). Setting velref to 0 or 256 chooses between optical and radio velocity without specifying a Doppler frame, provided that a frame is encoded in ctypeA. If not, i.e. for ctypeA = '`VELO`', ctype will be returned as '`VELO`'. `VELREF` takes precedence over `CTYPEia` in defining the Doppler frame, e.g. ctypeA = 'VELO-HEL' velref = 1 returns ctype = '`VOPT`' with specsys set to 'LSRK'.
[out]	ctype	Translated `CTYPEia` keyvalue, or a copy of ctypeA if no translation was performed (in which case any trailing blanks in ctypeA will be replaced with nulls).
[out]	specsys	Doppler reference frame indicated by `VELREF` or else by `CTYPEia` with value corresponding to the SPECSYS keyvalue in the FITS WCS standard. May be returned blank if neither specifies a Doppler frame, e.g. ctypeA = '`FELO`' and velref%256 == 0.

Returns

Status return value:

-1: No translation required (not an error).
0: Success.
2: Invalid value of VELREF.

int spctyp	(	const char	ctype[9],
		char	stype[],
		char	scode[],
		char	sname[],
		char	units[],
		char *	ptype,
		char *	xtype,
		int *	restreq
	)

int spcspx	(	const char	ctypeS[9],
		double	crvalS,
		double	restfrq,
		double	restwav,
		char *	ptype,
		char *	xtype,
		int *	restreq,
		double *	crvalX,
		double *	dXdS
	)

int spcxps	(	const char	ctypeS[9],
		double	crvalX,
		double	restfrq,
		double	restwav,
		char *	ptype,
		char *	xtype,
		int *	restreq,
		double *	crvalS,
		double *	dSdX
	)

int spctrn	(	const char	ctypeS1[9],
		double	crvalS1,
		double	cdeltS1,
		double	restfrq,
		double	restwav,
		char	ctypeS2[9],
		double *	crvalS2,
		double *	cdeltS2
	)

Variable Documentation

const char * spc_errmsg[]

Error messages to match the status value returned from each function.

Data Structures

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation