WCSLIB 8.4

Loading...
Searching...
No Matches
Data Structures | Macros | Enumerations | Functions | Variables
spc.h File Reference
`#include "spx.h"`

Go to the source code of this file.

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

## Macros
#define | SPCLEN (sizeof(struct spcprm)/sizeof(int))
| Size of the spcprm struct in int units.
#define | spcini_errmsg spc_errmsg
| Deprecated.
#define | spcprt_errmsg spc_errmsg
| Deprecated.
#define | spcset_errmsg spc_errmsg
| Deprecated.
#define | spcx2s_errmsg spc_errmsg
| Deprecated.
#define | spcs2x_errmsg spc_errmsg
| Deprecated.

## Enumerations
enum | spcenq_enum { SPCENQ_SET = 2 , SPCENQ_BYP = 4 }
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.
int | spcfree (struct spcprm *spc)
| Destructor for the spcprm struct.
int | spcsize (const struct spcprm *spc, int sizes[2])
| Compute the size of a spcprm struct.
int | spcenq (const struct spcprm *spc, int enquiry)
| enquire about the state of a spcprm struct.
int | spcprt (const struct spcprm *spc)
| Print routine for the spcprm struct.
int | spcperr (const struct spcprm *spc, const char *prefix)
| Print error messages from a spcprm struct.
int | spcset (struct spcprm *spc)
| Setup routine for the spcprm struct.
int | spcx2s (struct spcprm *spc, int nx, int sx, int sspec, const double x[], double spec[], int stat[])
| Transform to spectral coordinates.
int | spcs2x (struct spcprm *spc, int nspec, int sspec, int sx, const double spec[], double x[], int stat[])
| Transform spectral coordinates.
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.
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.
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.
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.
int | spcaips (const char ctypeA[9], int velref, char ctype[9], char specsys[9])
| Translate AIPS-convention spectral keywords.
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.

## Detailed Description

Routines in this suite implement the part of the FITS World Coordinate System (WCS) standard that deals with spectral coordinates, as described in

"Representations of world coordinates in FITS",
Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
"Representations of spectral coordinates in FITS",
Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
2006, A&A, 446, 747 (WCS Paper III)

These routines 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, spcsize() computes its total size including allocated memory, spcenq() returns information about the state of the struct, and spcprt() prints its contents.

spcperr() prints the error message(s) (if any) stored in a spcprm struct.

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:

-type: the spectral variable in which coordinates are to be expressed. Each -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 -type forms the first four characters of the `CTYPEia` keyvalue, and `CRVALia` and `CDELTia` are expressed as -type quantities so that they provide a first-order approximation to the -type variable at the reference point.

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

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

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

-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 -type is encoded as the sixth character of `CTYPEia`.

Grisms: Grism axes have normal -, and -types but the axis is linear, not in any spectral variable, but in a special "grism parameter". The -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 -type and the -type variables; the transformation between -type and -type variables is always linear.

When the -type and -type variables are the same, the spectral axis is linear in the -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 -type is '`ZOPT`' (redshift), the -type is necessarily 'W' (wavelength), and the -type is 'F' (frequency) by the nature of the instrument.

Air-to-vacuum wavelength conversion:
Please refer to the prologue of spx.h for important comments relating to the air-to-vacuum wavelength conversion.

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

## ◆ SPCLEN

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

Size of the spcprm struct in int units.

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

## ◆ spcini_errmsg

#define spcini_errmsg spc_errmsg

Deprecated.

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

## ◆ spcprt_errmsg

#define spcprt_errmsg spc_errmsg

Deprecated.

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

## ◆ spcset_errmsg

#define spcset_errmsg spc_errmsg

Deprecated.

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

## ◆ spcx2s_errmsg

#define spcx2s_errmsg spc_errmsg

Deprecated.

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

## ◆ spcs2x_errmsg

#define spcs2x_errmsg spc_errmsg

Deprecated.

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

## Enumeration Type Documentation

## ◆ spcenq_enum

enum spcenq_enum

Enumerator
SPCENQ_SET |
SPCENQ_BYP |

## ◆ spc_errmsg_enum

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

## ◆ spcini()

int spcini | ( | struct spcprm * | spc | ) |

Default constructor for the spcprm struct.

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

PLEASE NOTE: If the spcprm struct has already been initialized, then before reinitializing, it spcfree() should be used to free any memory that may have been allocated to store an error message. A memory leak may otherwise result.

Parameters

  [in,out] | spc | Spectral transformation parameters.

Returns
  Status return value:
  - 0: Success.
  - 1: Null spcprm pointer passed.

## ◆ spcfree()

int spcfree | ( | struct spcprm * | spc | ) |

Destructor for the spcprm struct.

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.

## ◆ spcsize()

int spcsize | ( | const struct spcprm * | spc,
|  | int | sizes[2] )

Compute the size of a spcprm struct.

spcsize() computes the full size of a spcprm struct, including allocated memory.

Parameters

  [in] | spc | Spectral transformation parameters. If NULL, the base size of the struct and the allocated size are both set to zero.
  [out] | sizes | The first element is the base size of the struct as returned by sizeof(struct spcprm). The second element is the total allocated size, in bytes. This figure includes memory allocated for the constituent struct, spcprm::err. It is not an error for the struct not to have been set up via spcset().

Returns
  Status return value:
  - 0: Success.

## ◆ spcenq()

int spcenq | ( | const struct spcprm * | spc,
|  | int | enquiry )

enquire about the state of a spcprm struct.

spcenq() may be used to obtain information about the state of a spcprm struct. The function returns a true/false answer for the enquiry asked.

Parameters

  [in] | spc | Spectral transformation parameters.
  [in] | enquiry | Enquiry according to the following parameters: SPCENQ_MEM: memory in the struct is being managed by WCSLIB (see spcini()). SPCENQ_SET: the struct has been set up by spcset(). SPCENQ_BYP: the struct is in bypass mode (see spcset()). These may be combined by logical OR, e.g. SPCENQ_MEM | SPCENQ_SET. The enquiry result will be the logical AND of the individual results.

Returns
  Enquiry result:
  - 0: No.
  - 1: Yes.

## ◆ spcprt()

int spcprt | ( | const struct spcprm * | spc | ) |

Print routine for the spcprm struct.

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.

## ◆ spcperr()

int spcperr | ( | const struct spcprm * | spc,
|  | const char * | prefix )

Print error messages from a spcprm struct.

spcperr() prints the error message(s) (if any) stored in a spcprm struct. If there are no errors then nothing is printed. It uses wcserr_prt(), q.v.

Parameters

  [in] | spc | Spectral transformation parameters.
  [in] | prefix | If non-NULL, each output line will be prefixed with this string.

Returns
  Status return value:
  - 0: Success.
  - 1: Null spcprm pointer passed.

## ◆ spcset()

int spcset | ( | struct spcprm * | spc | ) |

Setup routine for the spcprm struct.

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.

spcset() normally operates regardless of the value of spcprm::flag; i.e. even if a struct was previously set up it will be reset unconditionally. However, a spcprm struct may be put into "bypass" mode by invoking spcset() initially with spcprm::flag == 1 (rather than 0). spcset() will return immediately if invoked on a struct in that state. To take a struct out of bypass mode, simply reset spcprm::flag to zero. See also spcenq().

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().

## ◆ spcx2s()

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

Transform to spectral coordinates.

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().

## ◆ spcs2x()

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

Transform spectral coordinates.

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().

## ◆ spctype()

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.

spctype() checks whether a `CTYPEia` keyvalue is a valid spectral axis type and if so returns information derived from it relating to the associated -, -, and -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`).

## ◆ spcspxe()

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.

spcspxe() analyses the `CTYPEia` and `CRVALia` FITS spectral axis keyword values and returns information about the associated -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.

## ◆ spcxpse()

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.

spcxpse(), for the spectral axis type specified and the value provided for the -type spectral variable at the reference point, deduces the value of the FITS spectral axis keyword `CRVALia` and also the derivative which may be used to compute `CDELTia`. See above for an explanation of the -, -, and -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.

## ◆ spctrne()

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.

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 -type variables.

## ◆ spcaips()

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

Translate AIPS-convention spectral keywords.

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'. If omitted from the header, the default value of `VELREF` is 0.
  [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`.

## ◆ spctyp()

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

## ◆ spcspx()

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

## ◆ spcxps()

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

## ◆ spctrn()

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

## Variable Documentation

## ◆ spc_errmsg

const char* spc_errmsg[]
| extern

Status return messages.

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