wcsfix.h File Reference

#include "wcs.h"

Go to the source code of this file.

Defines

#define CDFIX   0
 Index of cdfix() status value in vector returned by wcsfix().
#define DATFIX   1
 Index of datfix() status value in vector returned by wcsfix().
#define UNITFIX   2
 Index of unitfix() status value in vector returned by wcsfix().
#define CELFIX   3
 Index of celfix() status value in vector returned by wcsfix().
#define SPCFIX   4
 Index of spcfix() status value in vector returned by wcsfix().
#define CYLFIX   5
 Index of cylfix() status value in vector returned by wcsfix().
#define NWCSFIX   6
 Number of elements in the status vector returned by wcsfix().
#define cylfix_errmsg   wcsfix_errmsg
 Deprecated.

Functions

int wcsfix (int ctrl, const int naxis[], struct wcsprm *wcs, int stat[])
 Translate a non-standard WCS struct.
int cdfix (struct wcsprm *wcs)
 Fix erroneously omitted CDi_ja keywords.
int datfix (struct wcsprm *wcs)
 Translate DATE-OBS and derive MJD-OBS or vice versa.
int unitfix (int ctrl, struct wcsprm *wcs)
 Correct aberrant CUNITia keyvalues.
int celfix (struct wcsprm *wcs)
 Translate AIPS-convention celestial projection types.
int spcfix (struct wcsprm *wcs)
 Translate AIPS-convention spectral types.
int cylfix (const int naxis[], struct wcsprm *wcs)
 Fix malformed cylindrical projections.

Variables

const char * wcsfix_errmsg []
 Status return messages.

Detailed Description

Routines in this suite identify and translate various forms of non-standard construct that are known to occur in FITS WCS headers. These range from the translation of non-standard values for standard WCS keywords, to the repair of malformed coordinate representations.

Non-standard keyvalues:
AIPS-convention celestial projection types, NCP and GLS, and spectral types, 'FREQ-LSR', 'FELO-HEL', etc., set in CTYPEia are translated on-the-fly by wcsset() but without modifying the relevant ctype[], pv[] or specsys members of the wcsprm struct. That is, only the information extracted from ctype[] is translated when wcsset() fills in wcsprm::cel (celprm struct) or wcsprm::spc (spcprm struct).

On the other hand, these routines do change the values of wcsprm::ctype[], wcsprm::pv[], wcsprm::specsys and other wcsprm struct members as appropriate to produce the same result as if the FITS header itself had been translated.

Auxiliary WCS header information not used directly by WCSLIB may also be translated. For example, the older DATE-OBS date format (wcsprm::dateobs) is recast to year-2000 standard form, and MJD-OBS (wcsprm::mjdobs) will be deduced from it if not already set.

Certain combinations of keyvalues that result in malformed coordinate systems, as described in Sect. 7.3.4 of Paper I, may also be repaired. These are handled by cylfix().

Non-standard keywords:
The AIPS-convention CROTAn keywords are recognized as quasi-standard and as such are accomodated by the wcsprm::crota[] and translated to wcsprm::pc[][] by wcsset(). These are not dealt with here, nor are any other non-standard keywords since these routines work only on the contents of a wcsprm struct and do not deal with FITS headers per se. In particular, they do not identify or translate CD00i00j, PC00i00j, PROJPn, EPOCH, VELREF or VSOURCEa keywords; this may be done by the FITS WCS header parser supplied with WCSLIB, refer to wcshdr.h.

wcsfix() applies all of the corrections handled by the following specific functions which may also be invoked separately:

Define Documentation

#define CDFIX   0

Index of the status value returned by cdfix() in the status vector returned by wcsfix().

#define DATFIX   1

Index of the status value returned by datfix() in the status vector returned by wcsfix().

#define UNITFIX   2

Index of the status value returned by unitfix() in the status vector returned by wcsfix().

#define CELFIX   3

Index of the status value returned by celfix() in the status vector returned by wcsfix().

#define SPCFIX   4

Index of the status value returned by spcfix() in the status vector returned by wcsfix().

#define CYLFIX   5

Index of the status value returned by cylfix() in the status vector returned by wcsfix().

#define NWCSFIX   6

Number of elements in the status vector returned by wcsfix().

#define cylfix_errmsg   wcsfix_errmsg

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

Function Documentation

int wcsfix ( int  ctrl,
const int  naxis[],
struct wcsprm *  wcs,
int  stat[] 
)

wcsfix() applies all of the corrections handled separately by datfix(), unitfix(), celfix(), spcfix() and cylfix().

Parameters:
[in] ctrl Do potentially unsafe translations of non-standard unit strings as described in the usage notes to wcsutrn().
[in] naxis Image axis lengths. If this array pointer is set to zero then cylfix() will not be invoked.
[in,out] wcs Coordinate transformation parameters.
[out] stat Status returns from each of the functions. Use the preprocessor macros NWCSFIX to dimension this vector and CDFIX, DATFIX, UNITFIX, CELFIX, SPCFIX and CYLFIX to access its elements. A status value of -2 is set for functions that were not invoked.
Returns:
Status return value:
  • 0: Success.
  • 1: One or more of the translation functions returned an error.

int cdfix ( struct wcsprm *  wcs  ) 

cdfix() sets the diagonal element of the CDi_ja matrix to unity if all CDi_ja keywords associated with a given axis were omitted. According to Paper I, if any CDi_ja keywords at all are given in a FITS header then those not given default to zero. This results in a singular matrix with an intersecting row and column of zeros.

Parameters:
[in,out] wcs Coordinate transformation parameters.
Returns:
Status return value:
  • -1: No change required (not an error).
  • 0: Success.
  • 1: Null wcsprm pointer passed.

int datfix ( struct wcsprm *  wcs  ) 

datfix() translates the old DATE-OBS date format set in wcsprm::dateobs to year-2000 standard form (yyyy-mm-ddThh:mm:ss) and derives MJD-OBS from it if not already set. Alternatively, if wcsprm::mjdobs is set and wcsprm::dateobs isn't, then datfix() derives wcsprm::dateobs from it. If both are set but disagree by more than half a day then status 5 is returned.

Parameters:
[in,out] wcs Coordinate transformation parameters. wcsprm::dateobs and/or wcsprm::mjdobs may be changed.
Returns:
Status return value:
  • -1: No change required (not an error).
  • 0: Success.
  • 1: Null wcsprm pointer passed.
  • 5: Invalid parameter value.
Notes:
The MJD algorithms used by datfix() are from D.A. Hatcher, 1984, QJRAS, 25, 53-55, as modified by P.T. Wallace for use in SLALIB subroutines CLDJ and DJCL.

int unitfix ( int  ctrl,
struct wcsprm *  wcs 
)

unitfix() applies wcsutrn() to translate non-standard CUNITia keyvalues, e.g. 'DEG' -> 'deg', also stripping off unnecessary whitespace.

Parameters:
[in] ctrl Do potentially unsafe translations described in the usage notes to wcsutrn().
[in,out] wcs Coordinate transformation parameters.
Returns:
Status return value:
  • -1: No change required (not an error).
  • 0: Success.
  • 1: Null wcsprm pointer passed.

int celfix ( struct wcsprm *  wcs  ) 

celfix() translates AIPS-convention celestial projection types, NCP and GLS, set in the ctype[] member of the wcsprm struct.

Two additional pv[] keyvalues are created when translating NCP. If the pv[] array was initially allocated by wcsini() then the array will be expanded if necessary. Otherwise, error 2 will be returned if two empty slots are not already available for use.

Parameters:
[in,out] wcs Coordinate transformation parameters. wcsprm::ctype[] and/or wcsprm::pv[] may be changed.
Returns:
Status return value:
  • -1: No change required (not an error).
  • 0: Success.
  • 1: Null wcsprm pointer passed.
  • 2: Memory allocation failed.
  • 3: Linear transformation matrix is singular.
  • 4: Inconsistent or unrecognized coordinate axis types.
  • 5: Invalid parameter value.
  • 6: Invalid coordinate transformation parameters.
  • 7: Ill-conditioned coordinate transformation parameters.

int spcfix ( struct wcsprm *  wcs  ) 

spcfix() translates AIPS-convention spectral coordinate types, '{FREQ,FELO,VELO}-{OBS,HEL,LSR}' (e.g. 'FREQ-LSR', 'FELO-HEL', 'VELO-OBS') set in wcsprm::ctype[].

Parameters:
[in,out] wcs Coordinate transformation parameters. wcsprm::ctype[] and/or wcsprm::specsys may be changed.
Returns:
tatus return value:
  • -1: No change required (not an error).
  • 0: Success.
  • 1: Null wcsprm pointer passed.
  • 2: Memory allocation failed.
  • 3: Linear transformation matrix is singular.
  • 4: Inconsistent or unrecognized coordinate axis types.
  • 5: Invalid parameter value.
  • 6: Invalid coordinate transformation parameters.
  • 7: Ill-conditioned coordinate transformation parameters.

int cylfix ( const int  naxis[],
struct wcsprm *  wcs 
)

cylfix() fixes WCS keyvalues for malformed cylindrical projections that suffer from the problem described in Sect. 7.3.4 of Paper I.

Parameters:
[in] naxis Image axis lengths.
[in,out] wcs Coordinate transformation parameters.
Returns:
tatus return value: -1: No change required (not an error).
  • 0: Success.
  • 1: Null wcsprm pointer passed.
  • 2: Memory allocation failed.
  • 3: Linear transformation matrix is singular.
  • 4: Inconsistent or unrecognized coordinate axis types.
  • 5: Invalid parameter value.
  • 6: Invalid coordinate transformation parameters.
  • 7: Ill-conditioned coordinate transformation parameters.
  • 8: All of the corner pixel coordinates are invalid.
  • 9: Could not determine reference pixel coordinate.
10: Could not determine reference pixel value.

Variable Documentation

const char * wcsfix_errmsg[]

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

Generated on Mon Sep 14 17:03:55 2009 for WCSLIB 4.4 by  doxygen 1.5.1