00001 /*============================================================================ 00002 00003 WCSLIB 4.15 - an implementation of the FITS WCS standard. 00004 Copyright (C) 1995-2012, Mark Calabretta 00005 00006 This file is part of WCSLIB. 00007 00008 WCSLIB is free software: you can redistribute it and/or modify it under the 00009 terms of the GNU Lesser General Public License as published by the Free 00010 Software Foundation, either version 3 of the License, or (at your option) 00011 any later version. 00012 00013 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY 00014 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00015 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for 00016 more details. 00017 00018 You should have received a copy of the GNU Lesser General Public License 00019 along with WCSLIB. If not, see http://www.gnu.org/licenses. 00020 00021 Direct correspondence concerning WCSLIB to mark@calabretta.id.au 00022 00023 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO. 00024 http://www.atnf.csiro.au/people/Mark.Calabretta 00025 $Id: wcsfix.h,v 4.15 2012/09/26 14:26:05 cal103 Exp $ 00026 *============================================================================= 00027 * 00028 * WCSLIB 4.15 - C routines that implement the FITS World Coordinate System 00029 * (WCS) standard. Refer to 00030 * 00031 * "Representations of world coordinates in FITS", 00032 * Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I) 00033 * 00034 * "Representations of celestial coordinates in FITS", 00035 * Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (Paper II) 00036 * 00037 * "Representations of spectral coordinates in FITS", 00038 * Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L. 00039 * 2006, A&A, 446, 747 (Paper III) 00040 * 00041 * Refer to the README file provided with WCSLIB for an overview of the 00042 * library. 00043 * 00044 * 00045 * Summary of the wcsfix routines 00046 * ------------------------------ 00047 * Routines in this suite identify and translate various forms of non-standard 00048 * construct that are known to occur in FITS WCS headers. These range from the 00049 * translation of non-standard values for standard WCS keywords, to the repair 00050 * of malformed coordinate representations. 00051 * 00052 * Non-standard keyvalues: 00053 * ----------------------- 00054 * AIPS-convention celestial projection types, NCP and GLS, and spectral 00055 * types, 'FREQ-LSR', 'FELO-HEL', etc., set in CTYPEia are translated 00056 * on-the-fly by wcsset() but without modifying the relevant ctype[], pv[] or 00057 * specsys members of the wcsprm struct. That is, only the information 00058 * extracted from ctype[] is translated when wcsset() fills in wcsprm::cel 00059 * (celprm struct) or wcsprm::spc (spcprm struct). 00060 * 00061 * On the other hand, these routines do change the values of wcsprm::ctype[], 00062 * wcsprm::pv[], wcsprm::specsys and other wcsprm struct members as 00063 * appropriate to produce the same result as if the FITS header itself had 00064 * been translated. 00065 * 00066 * Auxiliary WCS header information not used directly by WCSLIB may also be 00067 * translated. For example, the older DATE-OBS date format (wcsprm::dateobs) 00068 * is recast to year-2000 standard form, and MJD-OBS (wcsprm::mjdobs) will be 00069 * deduced from it if not already set. 00070 * 00071 * Certain combinations of keyvalues that result in malformed coordinate 00072 * systems, as described in Sect. 7.3.4 of Paper I, may also be repaired. 00073 * These are handled by cylfix(). 00074 * 00075 * Non-standard keywords: 00076 * ---------------------- 00077 * The AIPS-convention CROTAn keywords are recognized as quasi-standard and 00078 * as such are accomodated by the wcsprm::crota[] and translated to 00079 * wcsprm::pc[][] by wcsset(). These are not dealt with here, nor are any 00080 * other non-standard keywords since these routines work only on the contents 00081 * of a wcsprm struct and do not deal with FITS headers per se. In 00082 * particular, they do not identify or translate CD00i00j, PC00i00j, PROJPn, 00083 * EPOCH, VELREF or VSOURCEa keywords; this may be done by the FITS WCS 00084 * header parser supplied with WCSLIB, refer to wcshdr.h. 00085 * 00086 * wcsfix() and wcsfixi() apply all of the corrections handled by the following 00087 * specific functions which may also be invoked separately: 00088 * 00089 * - cdfix(): Sets the diagonal element of the CDi_ja matrix to 1.0 if all 00090 * CDi_ja keywords associated with a particular axis are omitted. 00091 * 00092 * - datfix(): recast an older DATE-OBS date format in dateobs to year-2000 00093 * standard form and derive mjdobs from it if not already set. 00094 * Alternatively, if mjdobs is set and dateobs isn't, then derive dateobs 00095 * from it. 00096 * 00097 * - unitfix(): translate some commonly used but non-standard unit strings in 00098 * the CUNITia keyvalues, e.g. 'DEG' -> 'deg'. 00099 * 00100 * - spcfix(): translate AIPS-convention spectral types, 'FREQ-LSR', 00101 * 'FELO-HEL', etc., in ctype[] as set from CTYPEia. 00102 * 00103 * - celfix(): translate AIPS-convention celestial projection types, NCP and 00104 * GLS, in ctype[] as set from CTYPEia. 00105 * 00106 * - cylfix(): fixes WCS keyvalues for malformed cylindrical projections that 00107 * suffer from the problem described in Sect. 7.3.4 of Paper I. 00108 * 00109 * 00110 * wcsfix() - Translate a non-standard WCS struct 00111 * ---------------------------------------------- 00112 * wcsfix() is identical to wcsfixi(), but lacks the info argument. 00113 * 00114 * 00115 * wcsfixi() - Translate a non-standard WCS struct 00116 * ----------------------------------------------- 00117 * wcsfix() applies all of the corrections handled separately by cdfix(), 00118 * datfix(), unitfix(), spcfix(), celfix(), and cylfix(). 00119 * 00120 * Given: 00121 * ctrl int Do potentially unsafe translations of non-standard 00122 * unit strings as described in the usage notes to 00123 * wcsutrn(). 00124 * 00125 * naxis const int [] 00126 * Image axis lengths. If this array pointer is set to 00127 * zero then cylfix() will not be invoked. 00128 * 00129 * Given and returned: 00130 * wcs struct wcsprm* 00131 * Coordinate transformation parameters. 00132 * 00133 * Returned: 00134 * stat int [NWCSFIX] 00135 * Status returns from each of the functions. Use the 00136 * preprocessor macros NWCSFIX to dimension this vector 00137 * and CDFIX, DATFIX, UNITFIX, SPCFIX, CELFIX, and CYLFIX 00138 * to access its elements. A status value of -2 is set 00139 * for functions that were not invoked. 00140 * 00141 * info struct wcserr [NWCSFIX] 00142 * Status messages from each of the functions. Use the 00143 * preprocessor macros NWCSFIX to dimension this vector 00144 * and CDFIX, DATFIX, UNITFIX, SPCFIX, CELFIX, and CYLFIX 00145 * to access its elements. 00146 * 00147 * Function return value: 00148 * int Status return value: 00149 * 0: Success. 00150 * 1: One or more of the translation functions 00151 * returned an error. 00152 * 00153 * 00154 * cdfix() - Fix erroneously omitted CDi_ja keywords 00155 * ------------------------------------------------- 00156 * cdfix() sets the diagonal element of the CDi_ja matrix to unity if all 00157 * CDi_ja keywords associated with a given axis were omitted. According to 00158 * Paper I, if any CDi_ja keywords at all are given in a FITS header then those 00159 * not given default to zero. This results in a singular matrix with an 00160 * intersecting row and column of zeros. 00161 * 00162 * Given and returned: 00163 * wcs struct wcsprm* 00164 * Coordinate transformation parameters. 00165 * 00166 * Function return value: 00167 * int Status return value: 00168 * -1: No change required (not an error). 00169 * 0: Success. 00170 * 1: Null wcsprm pointer passed. 00171 * 00172 * 00173 * datfix() - Translate DATE-OBS and derive MJD-OBS or vice versa 00174 * -------------------------------------------------------------- 00175 * datfix() translates the old DATE-OBS date format set in wcsprm::dateobs to 00176 * year-2000 standard form (yyyy-mm-ddThh:mm:ss) and derives MJD-OBS from it if 00177 * not already set. Alternatively, if wcsprm::mjdobs is set and 00178 * wcsprm::dateobs isn't, then datfix() derives wcsprm::dateobs from it. If 00179 * both are set but disagree by more than half a day then status 5 is returned. 00180 * 00181 * Given and returned: 00182 * wcs struct wcsprm* 00183 * Coordinate transformation parameters. wcsprm::dateobs 00184 * and/or wcsprm::mjdobs may be changed. 00185 * 00186 * Function return value: 00187 * int Status return value: 00188 * -1: No change required (not an error). 00189 * 0: Success. 00190 * 1: Null wcsprm pointer passed. 00191 * 5: Invalid parameter value. 00192 * 00193 * For returns > 1, a detailed error message is set in 00194 * wcsprm::err if enabled, see wcserr_enable(). 00195 * 00196 * Notes: 00197 * The MJD algorithms used by datfix() are from D.A. Hatcher, 1984, QJRAS, 00198 * 25, 53-55, as modified by P.T. Wallace for use in SLALIB subroutines CLDJ 00199 * and DJCL. 00200 * 00201 * 00202 * unitfix() - Correct aberrant CUNITia keyvalues 00203 * ---------------------------------------------- 00204 * unitfix() applies wcsutrn() to translate non-standard CUNITia keyvalues, 00205 * e.g. 'DEG' -> 'deg', also stripping off unnecessary whitespace. 00206 * 00207 * Given: 00208 * ctrl int Do potentially unsafe translations described in the 00209 * usage notes to wcsutrn(). 00210 * 00211 * Given and returned: 00212 * wcs struct wcsprm* 00213 * Coordinate transformation parameters. 00214 * 00215 * Function return value: 00216 * int Status return value: 00217 * -1: No change required (not an error). 00218 * 0: Success (an alias was applied). 00219 * 1: Null wcsprm pointer passed. 00220 * 00221 * When units are translated (i.e. status 0), status -2 00222 * is set in the wcserr struct to allow an informative 00223 * message to be returned. 00224 * 00225 * 00226 * spcfix() - Translate AIPS-convention spectral types 00227 * --------------------------------------------------- 00228 * spcfix() translates AIPS-convention spectral coordinate types, 00229 * '{FREQ,FELO,VELO}-{LSR,HEL,OBS}' (e.g. 'FREQ-OBS', 'FELO-HEL', 'VELO-LSR') 00230 * set in wcsprm::ctype[], subject to VELREF set in wcsprm::velref. 00231 * 00232 * Note that if wcs::specsys is already set then it will not be overridden. 00233 * 00234 * Given and returned: 00235 * wcs struct wcsprm* 00236 * Coordinate transformation parameters. wcsprm::ctype[] 00237 * and/or wcsprm::specsys may be changed. 00238 * 00239 * Function return value: 00240 * int Status return value: 00241 * -1: No change required (not an error). 00242 * 0: Success. 00243 * 1: Null wcsprm pointer passed. 00244 * 2: Memory allocation failed. 00245 * 3: Linear transformation matrix is singular. 00246 * 4: Inconsistent or unrecognized coordinate axis 00247 * types. 00248 * 5: Invalid parameter value. 00249 * 6: Invalid coordinate transformation parameters. 00250 * 7: Ill-conditioned coordinate transformation 00251 * parameters. 00252 * 00253 * For returns > 1, a detailed error message is set in 00254 * wcsprm::err if enabled, see wcserr_enable(). 00255 * 00256 * 00257 * celfix() - Translate AIPS-convention celestial projection types 00258 * --------------------------------------------------------------- 00259 * celfix() translates AIPS-convention celestial projection types, NCP and 00260 * GLS, set in the ctype[] member of the wcsprm struct. 00261 * 00262 * Two additional pv[] keyvalues are created when translating NCP. If the 00263 * pv[] array was initially allocated by wcsini() then the array will be 00264 * expanded if necessary. Otherwise, error 2 will be returned if two empty 00265 * slots are not already available for use. 00266 * 00267 * Given and returned: 00268 * wcs struct wcsprm* 00269 * Coordinate transformation parameters. wcsprm::ctype[] 00270 * and/or wcsprm::pv[] may be changed. 00271 * 00272 * Function return value: 00273 * int Status return value: 00274 * -1: No change required (not an error). 00275 * 0: Success. 00276 * 1: Null wcsprm pointer passed. 00277 * 2: Memory allocation failed. 00278 * 3: Linear transformation matrix is singular. 00279 * 4: Inconsistent or unrecognized coordinate axis 00280 * types. 00281 * 5: Invalid parameter value. 00282 * 6: Invalid coordinate transformation parameters. 00283 * 7: Ill-conditioned coordinate transformation 00284 * parameters. 00285 * 00286 * For returns > 1, a detailed error message is set in 00287 * wcsprm::err if enabled, see wcserr_enable(). 00288 * 00289 * 00290 * cylfix() - Fix malformed cylindrical projections 00291 * ------------------------------------------------ 00292 * cylfix() fixes WCS keyvalues for malformed cylindrical projections that 00293 * suffer from the problem described in Sect. 7.3.4 of Paper I. 00294 * 00295 * Given: 00296 * naxis const int [] 00297 * Image axis lengths. 00298 * 00299 * Given and returned: 00300 * wcs struct wcsprm* 00301 * Coordinate transformation parameters. 00302 * 00303 * Function return value: 00304 * int Status return value: 00305 * -1: No change required (not an error). 00306 * 0: Success. 00307 * 1: Null wcsprm pointer passed. 00308 * 2: Memory allocation failed. 00309 * 3: Linear transformation matrix is singular. 00310 * 4: Inconsistent or unrecognized coordinate axis 00311 * types. 00312 * 5: Invalid parameter value. 00313 * 6: Invalid coordinate transformation parameters. 00314 * 7: Ill-conditioned coordinate transformation 00315 * parameters. 00316 * 8: All of the corner pixel coordinates are invalid. 00317 * 9: Could not determine reference pixel coordinate. 00318 * 10: Could not determine reference pixel value. 00319 * 00320 * For returns > 1, a detailed error message is set in 00321 * wcsprm::err if enabled, see wcserr_enable(). 00322 * 00323 * 00324 * Global variable: const char *wcsfix_errmsg[] - Status return messages 00325 * --------------------------------------------------------------------- 00326 * Error messages to match the status value returned from each function. 00327 * 00328 *===========================================================================*/ 00329 00330 #ifndef WCSLIB_WCSFIX 00331 #define WCSLIB_WCSFIX 00332 00333 #include "wcs.h" 00334 #include "wcserr.h" 00335 00336 #ifdef __cplusplus 00337 extern "C" { 00338 #endif 00339 00340 #define CDFIX 0 00341 #define DATFIX 1 00342 #define UNITFIX 2 00343 #define SPCFIX 3 00344 #define CELFIX 4 00345 #define CYLFIX 5 00346 #define NWCSFIX 6 00347 00348 extern const char *wcsfix_errmsg[]; 00349 #define cylfix_errmsg wcsfix_errmsg 00350 00351 enum wcsfix_errmsg_enum { 00352 FIXERR_DATE_FIX = -4, /* The date formatting has been fixed up. */ 00353 FIXERR_SPC_UPDATE = -3, /* Spectral axis type modified. */ 00354 FIXERR_UNITS_ALIAS = -2, /* Units alias translation. */ 00355 FIXERR_NO_CHANGE = -1, /* No change. */ 00356 FIXERR_SUCCESS = 0, /* Success. */ 00357 FIXERR_NULL_POINTER = 1, /* Null wcsprm pointer passed. */ 00358 FIXERR_MEMORY = 2, /* Memory allocation failed. */ 00359 FIXERR_SINGULAR_MTX = 3, /* Linear transformation matrix is 00360 singular. */ 00361 FIXERR_BAD_CTYPE = 4, /* Inconsistent or unrecognized coordinate 00362 axis types. */ 00363 FIXERR_BAD_PARAM = 5, /* Invalid parameter value. */ 00364 FIXERR_BAD_COORD_TRANS = 6, /* Invalid coordinate transformation 00365 parameters. */ 00366 FIXERR_ILL_COORD_TRANS = 7, /* Ill-conditioned coordinate transformation 00367 parameters. */ 00368 FIXERR_BAD_CORNER_PIX = 8, /* All of the corner pixel coordinates are 00369 invalid. */ 00370 FIXERR_NO_REF_PIX_COORD = 9, /* Could not determine reference pixel 00371 coordinate. */ 00372 FIXERR_NO_REF_PIX_VAL = 10 /* Could not determine reference pixel 00373 value. */ 00374 }; 00375 00376 int wcsfix(int ctrl, const int naxis[], struct wcsprm *wcs, int stat[]); 00377 00378 int wcsfixi(int ctrl, const int naxis[], struct wcsprm *wcs, int stat[], 00379 struct wcserr info[]); 00380 00381 int cdfix(struct wcsprm *wcs); 00382 00383 int datfix(struct wcsprm *wcs); 00384 00385 int unitfix(int ctrl, struct wcsprm *wcs); 00386 00387 int spcfix(struct wcsprm *wcs); 00388 00389 int celfix(struct wcsprm *wcs); 00390 00391 int cylfix(const int naxis[], struct wcsprm *wcs); 00392 00393 00394 #ifdef __cplusplus 00395 } 00396 #endif 00397 00398 #endif /* WCSLIB_WCSFIX */