WCSLIB
7.3
|
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 | OBSFIX 2 |
#define | UNITFIX 3 |
Index of unitfix() status value in vector returned by wcsfix(). More... | |
#define | SPCFIX 4 |
Index of spcfix() status value in vector returned by wcsfix(). More... | |
#define | CELFIX 5 |
Index of celfix() status value in vector returned by wcsfix(). More... | |
#define | CYLFIX 6 |
Index of cylfix() status value in vector returned by wcsfix(). More... | |
#define | NWCSFIX 7 |
Number of elements in the status vector returned by wcsfix(). More... | |
#define | cylfix_errmsg wcsfix_errmsg |
Deprecated. More... | |
Enumerations | |
enum | wcsfix_errmsg_enum { FIXERR_OBSGEO_FIX = -5, 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 | obsfix (int ctrl, struct wcsprm *wcs) |
complete the OBS GEO-[XYZLBH] vector of observatory coordinates. 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... | |
Routines in this suite identify and translate various forms of construct known to occur in FITS headers that violate the FITS World Coordinate System (WCS) standard described in
Repairs effected by these routines range from the translation of non-standard values for standard WCS keywords, to the repair of malformed coordinate representations. Some routines are also provided to check the consistency of pairs of keyvalues that define the same measure in two different ways, for example, as a date and an MJD.
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 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.
Derive dateref from mjdref if not already set. Alternatively, if dateref is set and mjdref isn't, then derive mjdref from it. If both are set, then check consistency. Likewise for dateobs and mjdobs; datebeg and mjdbeg; dateavg and mjdavg; and dateend and mjdend.
obsfix(): if only one half of obsgeo[] is set, then derive the other half from it. If both halves are set, then check consistency.
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
.
#define CDFIX 0 |
#define DATFIX 1 |
#define OBSFIX 2 |
#define UNITFIX 3 |
#define SPCFIX 4 |
#define CELFIX 5 |
#define CYLFIX 6 |
#define NWCSFIX 7 |
Number of elements in the status vector returned by wcsfix().
#define cylfix_errmsg wcsfix_errmsg |
enum wcsfix_errmsg_enum |
int wcsfix | ( | int | ctrl, |
const int | naxis[], | ||
struct wcsprm * | wcs, | ||
int | stat[] | ||
) |
wcsfix() is identical to wcsfixi(), but lacks the info argument.
wcsfixi() applies all of the corrections handled separately by cdfix(), datfix(), obsfix(), unitfix(), spcfix(), celfix(), and cylfix().
[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, OBS FIX, 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, OBS FIX, UNITFIX, SPCFIX, CELFIX, and CYLFIX to access its elements. Note that the memory allocated by wcsfixi() for the message in each wcserr struct (wcserr::msg, if non-zero) must be freed by the user. See wcsdealloc(). |
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.
[in,out] | wcs | Coordinate transformation parameters. |
int datfix | ( | struct wcsprm * | wcs | ) |
datfix() translates the old DATE-OBS
date format set in wcsprm::dateobs to year-2000 standard form (yyyy-mm-ddT
hh:mm:ss).
datfix() derives wcsprm::dateref from wcsprm::mjdref if not already set. Alternatively, if dateref is set and mjdref isn't, then it derives mjdref from it. If both are set but disagree by more than 0.001 day (86.4 seconds) then status 5 is returned. Likewise for wcsprm::dateobs and wcsprm::mjdobs; wcsprm::datebeg and wcsprm::mjdbeg; wcsprm::dateavg and wcsprm::mjdavg; and wcsprm::dateend and wcsprm::mjdend.
If neither dateobs nor mjdobs are set, but wcsprm::jepoch (primarily) or wcsprm::bepoch is, then both are derived from it. If jepoch and/or bepoch are set but disagree with dateobs or mjdobs by more than 0.000002 year (63.2 seconds), an informative message is produced.
[in,out] | wcs | Coordinate transformation parameters. wcsprm::dateref and/or wcsprm::mjdref may be changed. wcsprm::dateobs and/or wcsprm::mjdobs may be changed. wcsprm::datebeg and/or wcsprm::mjdbeg may be changed. wcsprm::dateavg and/or wcsprm::mjdavg may be changed. wcsprm::dateend and/or wcsprm::mjdend may be changed. |
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 obsfix | ( | int | ctrl, |
struct wcsprm * | wcs | ||
) |
obsfix() completes the wcsprm::obsgeo vector of observatory coordinates. That is, if only the (x,y,z) Cartesian coordinate triplet or the (l,b,h) geodetic coordinate triplet are set, then it derives the other triplet from it. If both triplets are set, then it checks for consistency at the level of 1 metre.
[in] | ctrl | Flag that controls behaviour if one triplet is defined and the other is only partially defined:
|
[in,out] | wcs | Coordinate transformation parameters. wcsprm::obsgeo may be changed. |
Notes:
While the International Terrestrial Reference System (ITRS) is based solely on Cartesian coordinates, it recommends the use of the GRS80 ellipsoid in converting to geodetic coordinates. However, while WCS Paper III recommends ITRS Cartesian coordinates, Paper VII prescribes the use of the IAU(1976) ellipsoid for geodetic coordinates, and consequently that is what is used here.
For reference, parameters of commonly used global reference ellipsoids:
where f = (a - b) / a is the flattening, and a and b are the semi-major and semi-minor radii in metres.
The transformation from geodetic (lng,lat,hgt) to Cartesian (x,y,z) is
where the "prime vertical radius", n, is a function of latitude
and a, the equatorial radius, and e^2 = (2 - f)*f, the (first) eccentricity of the ellipsoid, are constants. obsfix() inverts these iteratively by writing
where
and iterating over the value of zeta. Since e is small, a good first approximation is given by zeta = z.
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.
[in] | ctrl | Do potentially unsafe translations described in the usage notes to wcsutrn(). |
[in,out] | wcs | Coordinate transformation parameters. |
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.
[in,out] | wcs | Coordinate transformation parameters. wcsprm::ctype[] and/or wcsprm::specsys may be changed. |
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.
[in,out] | wcs | Coordinate transformation parameters. wcsprm::ctype[] and/or wcsprm::pv[] may be changed. |
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.
[in] | naxis | Image axis lengths. |
[in,out] | wcs | Coordinate transformation parameters. |
const char * wcsfix_errmsg[] |
Error messages to match the status value returned from each function.