WCSLIB 4.17: wcsfix.h Source File

- Main Page
- Related Pages
- Data Structures
- Files

# wcsfix.h

Go to the documentation of this file.

    00001 /*============================================================================
    00002
    00003   WCSLIB 4.17 - an implementation of the FITS WCS standard.
    00004   Copyright (C) 1995-2013, 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.17 2013/01/29 05:29:20 cal103 Exp $
    00026 *=============================================================================
    00027 *
    00028 * WCSLIB 4.17 - 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 */