wcsfix.h File Reference

#include "wcs.h"
#include "wcserr.h"

Go to the source code of this file.

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

Enumerations
enum	wcsfix_errmsg_enum {   FIXERR_DATE_FIX = -4, FIXERR_SPC_UPDATE = -3, FIXERR_UNITS_ALIAS = -2, FIXERR_NO_CHANGE = -1,   FIXERR_SUCCESS = 0, FIXERR_NULL_POINTER = 1, FIXERR_MEMORY = 2, FIXERR_SINGULAR_MTX = 3,   FIXERR_BAD_CTYPE = 4, FIXERR_BAD_PARAM = 5, FIXERR_BAD_COORD_TRANS = 6, FIXERR_ILL_COORD_TRANS = 7,   FIXERR_BAD_CORNER_PIX = 8, FIXERR_NO_REF_PIX_COORD = 9, FIXERR_NO_REF_PIX_VAL = 10 }

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

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

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() and wcsfixi() apply all of the corrections handled by the following specific functions which may also be invoked separately:

• cdfix(): Sets the diagonal element of the CDi_ja matrix to 1.0 if all CDi_ja keywords associated with a particular axis are omitted.

• datfix(): recast an older DATE-OBS date format in dateobs to year-2000 standard form and derive mjdobs from it if not already set. Alternatively, if mjdobs is set and dateobs isn't, then derive dateobs from it.

• unitfix(): translate some commonly used but non-standard unit strings in the CUNITia keyvalues, e.g. 'DEG' -> 'deg'.

• spcfix(): translate AIPS-convention spectral types, 'FREQ-LSR', 'FELO-HEL', etc., in ctype[] as set from CTYPEia.

• celfix(): translate AIPS-convention celestial projection types, NCP and GLS, in ctype[] as set from CTYPEia.

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

Macro Definition 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 SPCFIX   3

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

#define CELFIX   4

Index of the status value returned by celfix() 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.

Enumeration Type Documentation

enum wcsfix_errmsg_enum

Enumerator
FIXERR_DATE_FIX
FIXERR_SPC_UPDATE
FIXERR_UNITS_ALIAS
FIXERR_NO_CHANGE
FIXERR_SUCCESS
FIXERR_NULL_POINTER
FIXERR_MEMORY
FIXERR_SINGULAR_MTX
FIXERR_BAD_CTYPE
FIXERR_BAD_PARAM
FIXERR_BAD_COORD_TRANS
FIXERR_ILL_COORD_TRANS
FIXERR_BAD_CORNER_PIX
FIXERR_NO_REF_PIX_COORD
FIXERR_NO_REF_PIX_VAL

Function Documentation

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

wcsfix() is identical to wcsfixi(), but lacks the info argument.

int wcsfixi	(	int	ctrl,
		const int	naxis[],
		struct wcsprm *	wcs,
		int	stat[],
		struct wcserr	info[]
	)

wcsfix() applies all of the corrections handled separately by cdfix(), datfix(), unitfix(), spcfix(), celfix(), 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, SPCFIX, CELFIX, and CYLFIX to access its elements. A status value of -2 is set for functions that were not invoked.
[out]	info	Status messages from each of the functions. Use the preprocessor macros NWCSFIX to dimension this vector and CDFIX, DATFIX, UNITFIX, SPCFIX, CELFIX, and CYLFIX to access its elements.

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.

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

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 (an alias was applied).
• 1: Null wcsprm pointer passed.

When units are translated (i.e. status 0), status -2 is set in the wcserr struct to allow an informative message to be returned.

int spcfix

(

struct wcsprm *

wcs)

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

Note that if wcs::specsys is already set then it will not be overridden.

Parameters

[in,out]

wcs

Coordinate transformation parameters. wcsprm::ctype[] and/or wcsprm::specsys 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.

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

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, and three are created when translating GLS with non-zero reference point. If the pv[] array was initially allocated by wcsini() then the array will be expanded if necessary. Otherwise, error 2 will be returned if sufficient 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.

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

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

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.
• 8: All of the corner pixel coordinates are invalid.
• 9: Could not determine reference pixel coordinate.
• 10: Could not determine reference pixel value.

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

Variable Documentation

const char * wcsfix_errmsg[]

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