- Main Page
- Related Pages
- Data Structures
- Files

# wcsfix.h

Go to the documentation of this file.

    00001 /*============================================================================
    00002
    00003   WCSLIB 4.13 - 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   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.13.1.1 2012/03/14 07:40:37 cal103 Exp cal103 $
    00032 *=============================================================================
    00033 *
    00034 * WCSLIB 4.13 - 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 *   - spcfix(): translate AIPS-convention spectral types, 'FREQ-LSR',
    00107 *     'FELO-HEL', etc., in ctype[] as set from CTYPEia.
    00108 *
    00109 *   - celfix(): translate AIPS-convention celestial projection types, NCP and
    00110 *     GLS, 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 cdfix(),
    00124 * datfix(), unitfix(), spcfix(), celfix(), 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, SPCFIX, CELFIX, 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, SPCFIX, CELFIX, 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 * spcfix() - Translate AIPS-convention spectral types
    00233 * ---------------------------------------------------
    00234 * spcfix() translates AIPS-convention spectral coordinate types,
    00235 * '{FREQ,FELO,VELO}-{LSR,HEL,OBS}' (e.g. 'FREQ-OBS', 'FELO-HEL', 'VELO-LSR')
    00236 * set in wcsprm::ctype[], subject to VELREF set in wcsprm::velref.
    00237 *
    00238 * Note that if wcs::specsys is already set then it will not be overridden.
    00239 *
    00240 * Given and returned:
    00241 *   wcs       struct wcsprm*
    00242 *                       Coordinate transformation parameters.  wcsprm::ctype[]
    00243 *                       and/or wcsprm::specsys may be changed.
    00244 *
    00245 * Function return value:
    00246 *             int       Status return value:
    00247 *                        -1: No change required (not an error).
    00248 *                         0: Success.
    00249 *                         1: Null wcsprm pointer passed.
    00250 *                         2: Memory allocation failed.
    00251 *                         3: Linear transformation matrix is singular.
    00252 *                         4: Inconsistent or unrecognized coordinate axis
    00253 *                            types.
    00254 *                         5: Invalid parameter value.
    00255 *                         6: Invalid coordinate transformation parameters.
    00256 *                         7: Ill-conditioned coordinate transformation
    00257 *                            parameters.
    00258 *
    00259 *                       For returns > 1, a detailed error message is set in
    00260 *                       wcsprm::err if enabled, see wcserr_enable().
    00261 *
    00262 *
    00263 * celfix() - Translate AIPS-convention celestial projection types
    00264 * ---------------------------------------------------------------
    00265 * celfix() translates AIPS-convention celestial projection types, NCP and
    00266 * GLS, set in the ctype[] member of the wcsprm struct.
    00267 *
    00268 * Two additional pv[] keyvalues are created when translating NCP.  If the
    00269 * pv[] array was initially allocated by wcsini() then the array will be
    00270 * expanded if necessary.  Otherwise, error 2 will be returned if two empty
    00271 * slots are not already available for use.
    00272 *
    00273 * Given and returned:
    00274 *   wcs       struct wcsprm*
    00275 *                       Coordinate transformation parameters.  wcsprm::ctype[]
    00276 *                       and/or wcsprm::pv[] may be changed.
    00277 *
    00278 * Function return value:
    00279 *             int       Status return value:
    00280 *                        -1: No change required (not an error).
    00281 *                         0: Success.
    00282 *                         1: Null wcsprm pointer passed.
    00283 *                         2: Memory allocation failed.
    00284 *                         3: Linear transformation matrix is singular.
    00285 *                         4: Inconsistent or unrecognized coordinate axis
    00286 *                            types.
    00287 *                         5: Invalid parameter value.
    00288 *                         6: Invalid coordinate transformation parameters.
    00289 *                         7: Ill-conditioned coordinate transformation
    00290 *                            parameters.
    00291 *
    00292 *                       For returns > 1, a detailed error message is set in
    00293 *                       wcsprm::err if enabled, see wcserr_enable().
    00294 *
    00295 *
    00296 * cylfix() - Fix malformed cylindrical projections
    00297 * ------------------------------------------------
    00298 * cylfix() fixes WCS keyvalues for malformed cylindrical projections that
    00299 * suffer from the problem described in Sect. 7.3.4 of Paper I.
    00300 *
    00301 * Given:
    00302 *   naxis     const int []
    00303 *                       Image axis lengths.
    00304 *
    00305 * Given and returned:
    00306 *   wcs       struct wcsprm*
    00307 *                       Coordinate transformation parameters.
    00308 *
    00309 * Function return value:
    00310 *             int       Status return value:
    00311 *                        -1: No change required (not an error).
    00312 *                         0: Success.
    00313 *                         1: Null wcsprm pointer passed.
    00314 *                         2: Memory allocation failed.
    00315 *                         3: Linear transformation matrix is singular.
    00316 *                         4: Inconsistent or unrecognized coordinate axis
    00317 *                            types.
    00318 *                         5: Invalid parameter value.
    00319 *                         6: Invalid coordinate transformation parameters.
    00320 *                         7: Ill-conditioned coordinate transformation
    00321 *                            parameters.
    00322 *                         8: All of the corner pixel coordinates are invalid.
    00323 *                         9: Could not determine reference pixel coordinate.
    00324 *                        10: Could not determine reference pixel value.
    00325 *
    00326 *                       For returns > 1, a detailed error message is set in
    00327 *                       wcsprm::err if enabled, see wcserr_enable().
    00328 *
    00329 *
    00330 * Global variable: const char *wcsfix_errmsg[] - Status return messages
    00331 * ---------------------------------------------------------------------
    00332 * Error messages to match the status value returned from each function.
    00333 *
    00334 *===========================================================================*/
    00335
    00336 #ifndef WCSLIB_WCSFIX
    00337 #define WCSLIB_WCSFIX
    00338
    00339 #include "wcs.h"
    00340 #include "wcserr.h"
    00341
    00342 #ifdef __cplusplus
    00343 extern "C" {
    00344 #endif
    00345
    00346 #define CDFIX    0
    00347 #define DATFIX   1
    00348 #define UNITFIX  2
    00349 #define SPCFIX   3
    00350 #define CELFIX   4
    00351 #define CYLFIX   5
    00352 #define NWCSFIX  6
    00353
    00354 extern const char *wcsfix_errmsg[];
    00355 #define cylfix_errmsg wcsfix_errmsg
    00356
    00357 enum wcsfix_errmsg_enum {
    00358   FIXERR_DATE_FIX         = -4, /* The date formatting has been fixed up. */
    00359   FIXERR_SPC_UPDATE       = -3, /* Spectral axis type modified. */
    00360   FIXERR_UNITS_ALIAS      = -2, /* Units alias translation. */
    00361   FIXERR_NO_CHANGE        = -1, /* No change. */
    00362   FIXERR_SUCCESS          =  0, /* Success. */
    00363   FIXERR_NULL_POINTER     =  1, /* Null wcsprm pointer passed. */
    00364   FIXERR_MEMORY           =  2, /* Memory allocation failed. */
    00365   FIXERR_SINGULAR_MTX     =  3, /* Linear transformation matrix is
    00366                                    singular. */
    00367   FIXERR_BAD_CTYPE        =  4, /* Inconsistent or unrecognized coordinate
    00368                                    axis types. */
    00369   FIXERR_BAD_PARAM        =  5, /* Invalid parameter value. */
    00370   FIXERR_BAD_COORD_TRANS  =  6, /* Invalid coordinate transformation
    00371                                    parameters. */
    00372   FIXERR_ILL_COORD_TRANS  =  7, /* Ill-conditioned coordinate transformation
    00373                                    parameters. */
    00374   FIXERR_BAD_CORNER_PIX   =  8, /* All of the corner pixel coordinates are
    00375                                    invalid. */
    00376   FIXERR_NO_REF_PIX_COORD =  9, /* Could not determine reference pixel
    00377                                    coordinate. */
    00378   FIXERR_NO_REF_PIX_VAL   = 10  /* Could not determine reference pixel
    00379                                    value. */
    00380 };
    00381
    00382 int wcsfix(int ctrl, const int naxis[], struct wcsprm *wcs, int stat[]);
    00383
    00384 int wcsfixi(int ctrl, const int naxis[], struct wcsprm *wcs, int stat[],
    00385             struct wcserr info[]);
    00386
    00387 int cdfix(struct wcsprm *wcs);
    00388
    00389 int datfix(struct wcsprm *wcs);
    00390
    00391 int unitfix(int ctrl, struct wcsprm *wcs);
    00392
    00393 int spcfix(struct wcsprm *wcs);
    00394
    00395 int celfix(struct wcsprm *wcs);
    00396
    00397 int cylfix(const int naxis[], struct wcsprm *wcs);
    00398
    00399
    00400 #ifdef __cplusplus
    00401 }
    00402 #endif
    00403
    00404 #endif /* WCSLIB_WCSFIX */