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 $X$-type spectral variables for the $S$-type variables supplied.

  • Spectral keyword synthesis routine, spcxpse(), computes the $S$-type variables for the $X$-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 - $S$, $P$, and $X$:
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.

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]spcSpectral 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]spcSpectral 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]spcSpectral transformation parameters.
If NULL, the base size of the struct and the allocated size are both set to zero.
[out]sizesThe 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]spcSpectral transformation parameters.
[in]enquiryEnquiry 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]spcSpectral 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]spcSpectral transformation parameters.
[in]prefixIf 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]spcSpectral 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]spcSpectral transformation parameters.
[in]nxVector length.
[in]sxVector stride.
[in]sspecVector stride.
[in]xIntermediate world coordinates, in SI units.
[out]specSpectral coordinates, in SI units.
[out]statStatus 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]spcSpectral transformation parameters.
[in]nspecVector length.
[in]sspecVector stride.
[in]sxVector stride.
[in]specSpectral coordinates, in SI units.
[out]xIntermediate world coordinates, in SI units.
[out]statStatus 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 $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]ctypeThe CTYPEia keyvalue, (eight characters with null termination).
[out]stypeThe four-letter name of the $S$-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]scodeThe 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]snameDescriptive name of the $S$-type spectral variable. If a non-zero pointer is given, the array must accomodate a null-terminated string of length 22.
[out]unitsSI units of the $S$-type spectral variable. If a non-zero pointer is given, the array must accomodate a null-terminated string of length 8.
[out]ptypeCharacter code for the $P$-type spectral variable derived from ctype, one of 'F', 'W', 'A', or 'V'.
[out]xtypeCharacter code for the $X$-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]restreqMultivalued 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 $S$- and $P$-types (e.g. 'ZOPT-F2W').
  • 2: Required for the conversion between $P$- and $X$-types (e.g. 'BETA-W2V').
  • 3: Required for the conversion between $S$- and $P$-types, and between $P$- and $X$-types, but not between $S$- and $X$-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 $S$- and $X$-types) only if
restreq%3 != 0
.
[out]errIf 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 $X$-type spectral variable.

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

Parameters
[in]ctypeSSpectral axis type, i.e. the CTYPEia keyvalue, (eight characters with null termination). For non-grism axes, the character code for the $P$-type spectral variable in the algorithm code (i.e. the eighth character of CTYPEia) may be set to '?' (it will not be reset).
[in]crvalSValue of the $S$-type spectral variable at the reference point, i.e. the CRVALia keyvalue, SI units.
[in]restfrq,restwavRest frequency [Hz] and rest wavelength in vacuo [m], only one of which need be given, the other should be set to zero.
[out]ptypeCharacter code for the $P$-type spectral variable derived from ctypeS, one of 'F', 'W', 'A', or 'V'.
[out]xtypeCharacter code for the $X$-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]restreqMultivalued flag that indicates whether rest frequency or wavelength is required to compute spectral variables for this CTYPEia, as for spctype().
[out]crvalXValue of the $X$-type spectral variable at the reference point, SI units.
[out]dXdSThe derivative, $dX/dS$, evaluated at the reference point, SI units. Multiply the CDELTia keyvalue by this to get the pixel spacing in the $X$-type spectral coordinate.
[out]errIf 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 $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]ctypeSThe required spectral axis type, i.e. the CTYPEia keyvalue, (eight characters with null termination). For non-grism axes, the character code for the $P$-type spectral variable in the algorithm code (i.e. the eighth character of CTYPEia) may be set to '?' (it will not be reset).
[in]crvalXValue of the $X$-type spectral variable at the reference point (N.B. NOT the CRVALia keyvalue), SI units.
[in]restfrq,restwavRest frequency [Hz] and rest wavelength in vacuo [m], only one of which need be given, the other should be set to zero.
[out]ptypeCharacter code for the $P$-type spectral variable derived from ctypeS, one of 'F', 'W', 'A', or 'V'.
[out]xtypeCharacter code for the $X$-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]restreqMultivalued flag that indicates whether rest frequency or wavelength is required to compute spectral variables for this CTYPEia, as for spctype().
[out]crvalSValue of the $S$-type spectral variable at the reference point (i.e. the appropriate CRVALia keyvalue), SI units.
[out]dSdXThe derivative, $dS/dX$, evaluated at the reference point, SI units. Multiply this by the pixel spacing in the $X$-type spectral coordinate to get the CDELTia keyvalue.
[out]errIf 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]ctypeS1Spectral axis type, i.e. the CTYPEia keyvalue, (eight characters with null termination). For non-grism axes, the character code for the $P$-type spectral variable in the algorithm code (i.e. the eighth character of CTYPEia) may be set to '?' (it will not be reset).
[in]crvalS1Value of the $S$-type spectral variable at the reference point, i.e. the CRVALia keyvalue, SI units.
[in]cdeltS1Increment of the $S$-type spectral variable at the reference point, SI units.
[in]restfrq,restwavRest 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]ctypeS2Required 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]crvalS2Value of the new $S$-type spectral variable at the reference point, i.e. the new CRVALia keyvalue, SI units.
[out]cdeltS2Increment of the new $S$-type spectral variable at the reference point, i.e. the new CDELTia keyvalue, SI units.
[out]errIf 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.

◆ 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]ctypeACTYPEia keyvalue possibly containing an AIPS-convention spectral code (eight characters, need not be null-terminated).
[in]velrefAIPS-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]ctypeTranslated 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]specsysDoppler 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.

Generated on Tue Oct 29 2024 00:57:38 for WCSLIB by doxygen 1.12.0