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