WCSLIB 4.17: wcs.h Source File

- Main Page
- Related Pages
- Data Structures
- Files

# wcs.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: wcs.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 wcs routines
    00046 * ---------------------------
    00047 * These routines implement the FITS World Coordinate System (WCS) standard
    00048 * which defines methods to be used for computing world coordinates from image
    00049 * pixel coordinates, and vice versa.  They are based on the wcsprm struct
    00050 * which contains all information needed for the computations.  The struct
    00051 * contains some members that must be set by the user, and others that are
    00052 * maintained by these routines, somewhat like a C++ class but with no
    00053 * encapsulation.
    00054 *
    00055 * Three routines, wcsini(), wcssub(), and wcsfree() are provided to manage the
    00056 * wcsprm struct and another, wcsprt(), to prints its contents.  Refer to the
    00057 * description of the wcsprm struct for an explanation of the anticipated usage
    00058 * of these routines.  wcscopy(), which does a deep copy of one wcsprm struct
    00059 * to another, is defined as a preprocessor macro function that invokes
    00060 * wcssub().
    00061 *
    00062 * wcsperr() prints the error message(s) (if any) stored in a wcsprm struct,
    00063 * and the linprm, celprm, prjprm, spcprm, and tabprm structs that it contains.
    00064 *
    00065 * A setup routine, wcsset(), computes intermediate values in the wcsprm struct
    00066 * from parameters in it that were supplied by the user.  The struct always
    00067 * needs to be set up by wcsset() but this need not be called explicitly -
    00068 * refer to the explanation of wcsprm::flag.
    00069 *
    00070 * wcsp2s() and wcss2p() implement the WCS world coordinate transformations.
    00071 * In fact, they are high level driver routines for the WCS linear,
    00072 * logarithmic, celestial, spectral and tabular transformation routines
    00073 * described in lin.h, log.h, cel.h, spc.h and tab.h.
    00074 *
    00075 * Given either the celestial longitude or latitude plus an element of the
    00076 * pixel coordinate a hybrid routine, wcsmix(), iteratively solves for the
    00077 * unknown elements.
    00078 *
    00079 * wcssptr() translates the spectral axis in a wcsprm struct.  For example, a
    00080 * 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.
    00081 *
    00082 * Quadcube projections:
    00083 * ---------------------
    00084 *   The quadcube projections (TSC, CSC, QSC) may be represented in FITS in
    00085 *   either of two ways:
    00086 *
    00087 *     a: The six faces may be laid out in one plane and numbered as follows:
    00088 *
    00089 =                                 0
    00090 =
    00091 =                        4  3  2  1  4  3  2
    00092 =
    00093 =                                 5
    00094 *
    00095 *        Faces 2, 3 and 4 may appear on one side or the other (or both).  The
    00096 *        world-to-pixel routines map faces 2, 3 and 4 to the left but the
    00097 *        pixel-to-world routines accept them on either side.
    00098 *
    00099 *     b: The "COBE" convention in which the six faces are stored in a
    00100 *        three-dimensional structure using a CUBEFACE axis indexed from
    00101 *        0 to 5 as above.
    00102 *
    00103 *   These routines support both methods; wcsset() determines which is being
    00104 *   used by the presence or absence of a CUBEFACE axis in ctype[].  wcsp2s()
    00105 *   and wcss2p() translate the CUBEFACE axis representation to the single
    00106 *   plane representation understood by the lower-level WCSLIB projection
    00107 *   routines.
    00108 *
    00109 *
    00110 * wcsini() - Default constructor for the wcsprm struct
    00111 * ----------------------------------------------------
    00112 * wcsini() optionally allocates memory for arrays in a wcsprm struct and sets
    00113 * all members of the struct to default values.  Memory is allocated for up to
    00114 * NPVMAX PVi_ma keywords or NPSMAX PSi_ma keywords per WCS representation.
    00115 * These may be changed via wcsnpv() and wcsnps() before wcsini() is called.
    00116 *
    00117 * PLEASE NOTE: every wcsprm struct should be initialized by wcsini(), possibly
    00118 * repeatedly.  On the first invokation, and only the first invokation,
    00119 * wcsprm::flag must be set to -1 to initialize memory management, regardless
    00120 * of whether wcsini() will actually be used to allocate memory.
    00121 *
    00122 * Given:
    00123 *   alloc     int       If true, allocate memory unconditionally for the
    00124 *                       crpix, etc. arrays.
    00125 *
    00126 *                       If false, it is assumed that pointers to these arrays
    00127 *                       have been set by the user except if they are null
    00128 *                       pointers in which case memory will be allocated for
    00129 *                       them regardless.  (In other words, setting alloc true
    00130 *                       saves having to initalize these pointers to zero.)
    00131 *
    00132 *   naxis     int       The number of world coordinate axes.  This is used to
    00133 *                       determine the length of the various wcsprm vectors and
    00134 *                       matrices and therefore the amount of memory to
    00135 *                       allocate for them.
    00136 *
    00137 * Given and returned:
    00138 *   wcs       struct wcsprm*
    00139 *                       Coordinate transformation parameters.
    00140 *
    00141 *                       Note that, in order to initialize memory management,
    00142 *                       wcsprm::flag should be set to -1 when wcs is
    00143 *                       initialized for the first time (memory leaks may
    00144 *                       result if it had already been initialized).
    00145 *
    00146 * Function return value:
    00147 *             int       Status return value:
    00148 *                         0: Success.
    00149 *                         1: Null wcsprm pointer passed.
    00150 *                         2: Memory allocation failed.
    00151 *
    00152 *                       For returns > 1, a detailed error message is set in
    00153 *                       wcsprm::err if enabled, see wcserr_enable().
    00154 *
    00155 *
    00156 * wcsnpv() - Memory allocation for PVi_ma
    00157 * ---------------------------------------
    00158 * wcsnpv() changes the value of NPVMAX (default 64).  This global variable
    00159 * controls the number of PVi_ma keywords that wcsini() should allocate space
    00160 * for.
    00161 *
    00162 * PLEASE NOTE: This function is not thread-safe.
    00163 *
    00164 * Given:
    00165 *   n         int       Value of NPVMAX; ignored if < 0.
    00166 *
    00167 * Function return value:
    00168 *             int       Current value of NPVMAX.
    00169 *
    00170 *
    00171 * wcsnps() - Memory allocation for PSi_ma
    00172 * ---------------------------------------
    00173 * wcsnps() changes the values of NPSMAX (default 8).  This global variable
    00174 * controls the number of PSi_ma keywords that wcsini() should allocate space
    00175 * for.
    00176 *
    00177 * PLEASE NOTE: This function is not thread-safe.
    00178 *
    00179 * Given:
    00180 *   n         int       Value of NPSMAX; ignored if < 0.
    00181 *
    00182 * Function return value:
    00183 *             int       Current value of NPSMAX.
    00184 *
    00185 *
    00186 * wcssub() - Subimage extraction routine for the wcsprm struct
    00187 * ------------------------------------------------------------
    00188 * wcssub() extracts the coordinate description for a subimage from a wcsprm
    00189 * struct.  It does a deep copy, using wcsini() to allocate memory for its
    00190 * arrays if required.  Only the "information to be provided" part of the
    00191 * struct is extracted; a call to wcsset() is required to set up the remainder.
    00192 *
    00193 * The world coordinate system of the subimage must be separable in the sense
    00194 * that the world coordinates at any point in the subimage must depend only on
    00195 * the pixel coordinates of the axes extracted.  In practice, this means that
    00196 * the PCi_ja matrix of the original image must not contain non-zero
    00197 * off-diagonal terms that associate any of the subimage axes with any of the
    00198 * non-subimage axes.
    00199 *
    00200 * Note that while the required elements of the tabprm array are extracted, the
    00201 * wtbarr array is not.  (Thus it is not appropriate to call wcssub() after
    00202 * wcstab() but before filling the tabprm structs - refer to wcshdr.h.)
    00203 *
    00204 * wcssub() can also add axes to a wcsprm struct.  The new axes will be created
    00205 * using the defaults set by wcsini() which produce a simple, unnamed, linear
    00206 * axis with world coordinate equal to the pixel coordinate.  These default
    00207 * values can be changed in before invoking wcsset().
    00208 *
    00209 * Given:
    00210 *   alloc     int       If true, allocate memory for the crpix, etc. arrays in
    00211 *                       the destination.  Otherwise, it is assumed that
    00212 *                       pointers to these arrays have been set by the user
    00213 *                       except if they are null pointers in which case memory
    00214 *                       will be allocated for them regardless.
    00215 *
    00216 *   wcssrc    const struct wcsprm*
    00217 *                       Struct to extract from.
    00218 *
    00219 * Given and returned:
    00220 *   nsub      int*
    00221 *   axes      int[]     Vector of length *nsub containing the image axis
    00222 *                       numbers (1-relative) to extract.  Order is
    00223 *                       significant; axes[0] is the axis number of the input
    00224 *                       image that corresponds to the first axis in the
    00225 *                       subimage, etc.
    00226 *
    00227 *                       Use an axis number of 0 to create a new axis using
    00228 *                       the defaults set by wcsini().
    00229 *
    00230 *                       nsub (the pointer) may be set to zero, and so also may
    00231 *                       nsub, to indicate the number of axes in the input
    00232 *                       image; the number of axes will be returned if
    00233 *                       nsub != 0x0.  axes itself (the pointer) may be set to
    00234 *                       zero to indicate the first *nsub axes in their
    00235 *                       original order.
    00236 *
    00237 *                       Set both nsub and axes to zero to do a deep copy of
    00238 *                       one wcsprm struct to another.
    00239 *
    00240 *                       Subimage extraction by coordinate axis type may be
    00241 *                       done by setting the elements of axes[] to the
    00242 *                       following special preprocessor macro values:
    00243 *
    00244 *                         WCSSUB_LONGITUDE: Celestial longitude.
    00245 *                         WCSSUB_LATITUDE:  Celestial latitude.
    00246 *                         WCSSUB_CUBEFACE:  Quadcube CUBEFACE axis.
    00247 *                         WCSSUB_SPECTRAL:  Spectral axis.
    00248 *                         WCSSUB_STOKES:    Stokes axis.
    00249 *
    00250 *                       Refer to the notes (below) for further usage examples.
    00251 *
    00252 *                       On return, *nsub will contain the number of axes in
    00253 *                       the subimage; this may be zero if there were no axes
    00254 *                       of the required type(s) (in which case no memory will
    00255 *                       be allocated).  axes[] will contain the axis numbers
    00256 *                       that were extracted, or 0 for newly created axes.  The
    00257 *                       vector length must be sufficient to contain all axis
    00258 *                       numbers.  No checks are performed to verify that the
    00259 *                       coordinate axes are consistent, this is done by
    00260 *                       wcsset().
    00261 *
    00262 *   wcsdst    struct wcsprm*
    00263 *                       Struct describing the subimage.  wcsprm::flag should
    00264 *                       be set to -1 if wcsdst was not previously initialized
    00265 *                       (memory leaks may result if it was previously
    00266 *                       initialized).
    00267 *
    00268 * Function return value:
    00269 *             int       Status return value:
    00270 *                         0: Success.
    00271 *                         1: Null wcsprm pointer passed.
    00272 *                         2: Memory allocation failed.
    00273 *                        12: Invalid subimage specification.
    00274 *                        13: Non-separable subimage coordinate system.
    00275 *
    00276 *                       For returns > 1, a detailed error message is set in
    00277 *                       wcsprm::err if enabled, see wcserr_enable().
    00278 *
    00279 * Notes:
    00280 *   Combinations of subimage axes of particular types may be extracted in the
    00281 *   same order as they occur in the input image by combining preprocessor
    00282 *   codes, for example
    00283 *
    00284 =     *nsub = 1;
    00285 =     axes[0] = WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_SPECTRAL;
    00286 *
    00287 *   would extract the longitude, latitude, and spectral axes in the same order
    00288 *   as the input image.  If one of each were present, *nsub = 3 would be
    00289 *   returned.
    00290 *
    00291 *   For convenience, WCSSUB_CELESTIAL is defined as the combination
    00292 *   WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_CUBEFACE.
    00293 *
    00294 *   The codes may also be negated to extract all but the types specified, for
    00295 *   example
    00296 *
    00297 =     *nsub = 4;
    00298 =     axes[0] = WCSSUB_LONGITUDE;
    00299 =     axes[1] = WCSSUB_LATITUDE;
    00300 =     axes[2] = WCSSUB_CUBEFACE;
    00301 =     axes[3] = -(WCSSUB_SPECTRAL | WCSSUB_STOKES);
    00302 *
    00303 *   The last of these specifies all axis types other than spectral or Stokes.
    00304 *   Extraction is done in the order specified by axes[] a longitude axis (if
    00305 *   present) would be extracted first (via axes[0]) and not subsequently (via
    00306 *   axes[3]).  Likewise for the latitude and cubeface axes in this example.
    00307 *
    00308 *   From the foregoing, it is apparent that the value of *nsub returned may be
    00309 *   less than or greater than that given.  However, it will never exceed the
    00310 *   number of axes in the input image (plus the number of newly-created axes
    00311 *   if any were specified on input).
    00312 *
    00313 *
    00314 * wcscopy() macro - Copy routine for the wcsprm struct
    00315 * ----------------------------------------------------
    00316 * wcscopy() does a deep copy of one wcsprm struct to another.  As of
    00317 * WCSLIB 3.6, it is implemented as a preprocessor macro that invokes
    00318 * wcssub() with the nsub and axes pointers both set to zero.
    00319 *
    00320 *
    00321 * wcsfree() - Destructor for the wcsprm struct
    00322 * --------------------------------------------
    00323 * wcsfree() frees memory allocated for the wcsprm arrays by wcsini() and/or
    00324 * wcsset().  wcsini() records the memory it allocates and wcsfree() will only
    00325 * attempt to free this.
    00326 *
    00327 * PLEASE NOTE: wcsfree() must not be invoked on a wcsprm struct that was not
    00328 * initialized by wcsini().
    00329 *
    00330 * Returned:
    00331 *   wcs       struct wcsprm*
    00332 *                       Coordinate transformation parameters.
    00333 *
    00334 * Function return value:
    00335 *             int       Status return value:
    00336 *                         0: Success.
    00337 *                         1: Null wcsprm pointer passed.
    00338 *
    00339 *
    00340 * wcsprt() - Print routine for the wcsprm struct
    00341 * ----------------------------------------------
    00342 * wcsprt() prints the contents of a wcsprm struct using wcsprintf().  Mainly
    00343 * intended for diagnostic purposes.
    00344 *
    00345 * Given:
    00346 *   wcs       const struct wcsprm*
    00347 *                       Coordinate transformation parameters.
    00348 *
    00349 * Function return value:
    00350 *             int       Status return value:
    00351 *                         0: Success.
    00352 *                         1: Null wcsprm pointer passed.
    00353 *
    00354 *
    00355 * wcsperr() - Print error messages from a wcsprm struct
    00356 * -----------------------------------------------------
    00357 * wcsperr() prints the error message(s), if any, stored in a wcsprm struct,
    00358 * and the linprm, celprm, prjprm, spcprm, and tabprm structs that it contains.
    00359 * If there are no errors then nothing is printed.  It uses wcserr_prt(), q.v.
    00360 *
    00361 * Given:
    00362 *   wcs       const struct wcsprm*
    00363 *                       Coordinate transformation parameters.
    00364 *
    00365 *   prefix    const char *
    00366 *                       If non-NULL, each output line will be prefixed with
    00367 *                       this string.
    00368 *
    00369 * Function return value:
    00370 *             int       Status return value:
    00371 *                         0: Success.
    00372 *                         1: Null wcsprm pointer passed.
    00373 *
    00374 *
    00375 * wcsset() - Setup routine for the wcsprm struct
    00376 * ----------------------------------------------
    00377 * wcsset() sets up a wcsprm struct according to information supplied within
    00378 * it (refer to the description of the wcsprm struct).
    00379 *
    00380 * wcsset() recognizes the NCP projection and converts it to the equivalent SIN
    00381 * projection and likewise translates GLS into SFL.  It also translates the
    00382 * AIPS spectral types ('FREQ-LSR', 'FELO-HEL', etc.), possibly changing the
    00383 * input header keywords wcsprm::ctype and/or wcsprm::specsys if necessary.
    00384 *
    00385 * Note that this routine need not be called directly; it will be invoked by
    00386 * wcsp2s() and wcss2p() if the wcsprm::flag is anything other than a
    00387 * predefined magic value.
    00388 *
    00389 * Given and returned:
    00390 *   wcs       struct wcsprm*
    00391 *                       Coordinate transformation parameters.
    00392 *
    00393 * Function return value:
    00394 *             int       Status return value:
    00395 *                         0: Success.
    00396 *                         1: Null wcsprm pointer passed.
    00397 *                         2: Memory allocation failed.
    00398 *                         3: Linear transformation matrix is singular.
    00399 *                         4: Inconsistent or unrecognized coordinate axis
    00400 *                            types.
    00401 *                         5: Invalid parameter value.
    00402 *                         6: Invalid coordinate transformation parameters.
    00403 *                         7: Ill-conditioned coordinate transformation
    00404 *                            parameters.
    00405 *
    00406 *                       For returns > 1, a detailed error message is set in
    00407 *                       wcsprm::err if enabled, see wcserr_enable().
    00408 *
    00409 *
    00410 * wcsp2s() - Pixel-to-world transformation
    00411 * ----------------------------------------
    00412 * wcsp2s() transforms pixel coordinates to world coordinates.
    00413 *
    00414 * Given and returned:
    00415 *   wcs       struct wcsprm*
    00416 *                       Coordinate transformation parameters.
    00417 *
    00418 * Given:
    00419 *   ncoord,
    00420 *   nelem     int       The number of coordinates, each of vector length
    00421 *                       nelem but containing wcs.naxis coordinate elements.
    00422 *                       Thus nelem must equal or exceed the value of the
    00423 *                       NAXIS keyword unless ncoord == 1, in which case nelem
    00424 *                       is not used.
    00425 *
    00426 *   pixcrd    const double[ncoord][nelem]
    00427 *                       Array of pixel coordinates.
    00428 *
    00429 * Returned:
    00430 *   imgcrd    double[ncoord][nelem]
    00431 *                       Array of intermediate world coordinates.  For
    00432 *                       celestial axes, imgcrd[][wcs.lng] and
    00433 *                       imgcrd[][wcs.lat] are the projected x-, and
    00434 *                       y-coordinates in pseudo "degrees".  For spectral
    00435 *                       axes, imgcrd[][wcs.spec] is the intermediate spectral
    00436 *                       coordinate, in SI units.
    00437 *
    00438 *   phi,theta double[ncoord]
    00439 *                       Longitude and latitude in the native coordinate system
    00440 *                       of the projection [deg].
    00441 *
    00442 *   world     double[ncoord][nelem]
    00443 *                       Array of world coordinates.  For celestial axes,
    00444 *                       world[][wcs.lng] and world[][wcs.lat] are the
    00445 *                       celestial longitude and latitude [deg].  For
    00446 *                       spectral axes, imgcrd[][wcs.spec] is the intermediate
    00447 *                       spectral coordinate, in SI units.
    00448 *
    00449 *   stat      int[ncoord]
    00450 *                       Status return value for each coordinate:
    00451 *                         0: Success.
    00452 *                         1+: A bit mask indicating invalid pixel coordinate
    00453 *                            element(s).
    00454 *
    00455 * Function return value:
    00456 *             int       Status return value:
    00457 *                         0: Success.
    00458 *                         1: Null wcsprm pointer passed.
    00459 *                         2: Memory allocation failed.
    00460 *                         3: Linear transformation matrix is singular.
    00461 *                         4: Inconsistent or unrecognized coordinate axis
    00462 *                            types.
    00463 *                         5: Invalid parameter value.
    00464 *                         6: Invalid coordinate transformation parameters.
    00465 *                         7: Ill-conditioned coordinate transformation
    00466 *                            parameters.
    00467 *                         8: One or more of the pixel coordinates were
    00468 *                            invalid, as indicated by the stat vector.
    00469 *
    00470 *                       For returns > 1, a detailed error message is set in
    00471 *                       wcsprm::err if enabled, see wcserr_enable().
    00472 *
    00473 *
    00474 * wcss2p() - World-to-pixel transformation
    00475 * ----------------------------------------
    00476 * wcss2p() transforms world coordinates to pixel coordinates.
    00477 *
    00478 * Given and returned:
    00479 *   wcs       struct wcsprm*
    00480 *                       Coordinate transformation parameters.
    00481 *
    00482 * Given:
    00483 *   ncoord,
    00484 *   nelem     int       The number of coordinates, each of vector length nelem
    00485 *                       but containing wcs.naxis coordinate elements.  Thus
    00486 *                       nelem must equal or exceed the value of the NAXIS
    00487 *                       keyword unless ncoord == 1, in which case nelem is not
    00488 *                       used.
    00489 *
    00490 *   world     const double[ncoord][nelem]
    00491 *                       Array of world coordinates.  For celestial axes,
    00492 *                       world[][wcs.lng] and world[][wcs.lat] are the
    00493 *                       celestial longitude and latitude [deg]. For spectral
    00494 *                       axes, world[][wcs.spec] is the spectral coordinate, in
    00495 *                       SI units.
    00496 *
    00497 * Returned:
    00498 *   phi,theta double[ncoord]
    00499 *                       Longitude and latitude in the native coordinate
    00500 *                       system of the projection [deg].
    00501 *
    00502 *   imgcrd    double[ncoord][nelem]
    00503 *                       Array of intermediate world coordinates.  For
    00504 *                       celestial axes, imgcrd[][wcs.lng] and
    00505 *                       imgcrd[][wcs.lat] are the projected x-, and
    00506 *                       y-coordinates in pseudo "degrees".  For quadcube
    00507 *                       projections with a CUBEFACE axis the face number is
    00508 *                       also returned in imgcrd[][wcs.cubeface].  For
    00509 *                       spectral axes, imgcrd[][wcs.spec] is the intermediate
    00510 *                       spectral coordinate, in SI units.
    00511 *
    00512 *   pixcrd    double[ncoord][nelem]
    00513 *                       Array of pixel coordinates.
    00514 *
    00515 *   stat      int[ncoord]
    00516 *                       Status return value for each coordinate:
    00517 *                         0: Success.
    00518 *                         1+: A bit mask indicating invalid world coordinate
    00519 *                            element(s).
    00520 *
    00521 * Function return value:
    00522 *             int       Status return value:
    00523 *                         0: Success.
    00524 *                         1: Null wcsprm pointer passed.
    00525 *                         2: Memory allocation failed.
    00526 *                         3: Linear transformation matrix is singular.
    00527 *                         4: Inconsistent or unrecognized coordinate axis
    00528 *                            types.
    00529 *                         5: Invalid parameter value.
    00530 *                         6: Invalid coordinate transformation parameters.
    00531 *                         7: Ill-conditioned coordinate transformation
    00532 *                            parameters.
    00533 *                         9: One or more of the world coordinates were
    00534 *                            invalid, as indicated by the stat vector.
    00535 *
    00536 *                       For returns > 1, a detailed error message is set in
    00537 *                       wcsprm::err if enabled, see wcserr_enable().
    00538 *
    00539 *
    00540 * wcsmix() - Hybrid coordinate transformation
    00541 * -------------------------------------------
    00542 * wcsmix(), given either the celestial longitude or latitude plus an element
    00543 * of the pixel coordinate, solves for the remaining elements by iterating on
    00544 * the unknown celestial coordinate element using wcss2p().  Refer also to the
    00545 * notes below.
    00546 *
    00547 * Given and returned:
    00548 *   wcs       struct wcsprm*
    00549 *                       Indices for the celestial coordinates obtained
    00550 *                       by parsing the wcsprm::ctype[].
    00551 *
    00552 * Given:
    00553 *   mixpix    int       Which element of the pixel coordinate is given.
    00554 *
    00555 *   mixcel    int       Which element of the celestial coordinate is given:
    00556 *                         1: Celestial longitude is given in
    00557 *                            world[wcs.lng], latitude returned in
    00558 *                            world[wcs.lat].
    00559 *                         2: Celestial latitude is given in
    00560 *                            world[wcs.lat], longitude returned in
    00561 *                            world[wcs.lng].
    00562 *
    00563 *   vspan     const double[2]
    00564 *                       Solution interval for the celestial coordinate [deg].
    00565 *                       The ordering of the two limits is irrelevant.
    00566 *                       Longitude ranges may be specified with any convenient
    00567 *                       normalization, for example [-120,+120] is the same as
    00568 *                       [240,480], except that the solution will be returned
    00569 *                       with the same normalization, i.e. lie within the
    00570 *                       interval specified.
    00571 *
    00572 *   vstep     const double
    00573 *                       Step size for solution search [deg].  If zero, a
    00574 *                       sensible, although perhaps non-optimal default will be
    00575 *                       used.
    00576 *
    00577 *   viter     int       If a solution is not found then the step size will be
    00578 *                       halved and the search recommenced.  viter controls how
    00579 *                       many times the step size is halved.  The allowed range
    00580 *                       is 5 - 10.
    00581 *
    00582 * Given and returned:
    00583 *   world     double[naxis]
    00584 *                       World coordinate elements.  world[wcs.lng] and
    00585 *                       world[wcs.lat] are the celestial longitude and
    00586 *                       latitude [deg].  Which is given and which returned
    00587 *                       depends on the value of mixcel.  All other elements
    00588 *                       are given.
    00589 *
    00590 * Returned:
    00591 *   phi,theta double[naxis]
    00592 *                       Longitude and latitude in the native coordinate
    00593 *                       system of the projection [deg].
    00594 *
    00595 *   imgcrd    double[naxis]
    00596 *                       Image coordinate elements.  imgcrd[wcs.lng] and
    00597 *                       imgcrd[wcs.lat] are the projected x-, and
    00598 *                       y-coordinates in pseudo "degrees".
    00599 *
    00600 * Given and returned:
    00601 *   pixcrd    double[naxis]
    00602 *                       Pixel coordinate.  The element indicated by mixpix is
    00603 *                       given and the remaining elements are returned.
    00604 *
    00605 * Function return value:
    00606 *             int       Status return value:
    00607 *                         0: Success.
    00608 *                         1: Null wcsprm pointer passed.
    00609 *                         2: Memory allocation failed.
    00610 *                         3: Linear transformation matrix is singular.
    00611 *                         4: Inconsistent or unrecognized coordinate axis
    00612 *                            types.
    00613 *                         5: Invalid parameter value.
    00614 *                         6: Invalid coordinate transformation parameters.
    00615 *                         7: Ill-conditioned coordinate transformation
    00616 *                            parameters.
    00617 *                        10: Invalid world coordinate.
    00618 *                        11: No solution found in the specified interval.
    00619 *
    00620 *                       For returns > 1, a detailed error message is set in
    00621 *                       wcsprm::err if enabled, see wcserr_enable().
    00622 *
    00623 * Notes:
    00624 *   Initially the specified solution interval is checked to see if it's a
    00625 *   "crossing" interval.  If it isn't, a search is made for a crossing
    00626 *   solution by iterating on the unknown celestial coordinate starting at the
    00627 *   upper limit of the solution interval and decrementing by the specified
    00628 *   step size.  A crossing is indicated if the trial value of the pixel
    00629 *   coordinate steps through the value specified.  If a crossing interval is
    00630 *   found then the solution is determined by a modified form of "regula falsi"
    00631 *   division of the crossing interval.  If no crossing interval was found
    00632 *   within the specified solution interval then a search is made for a
    00633 *   "non-crossing" solution as may arise from a point of tangency.  The
    00634 *   process is complicated by having to make allowance for the discontinuities
    00635 *   that occur in all map projections.
    00636 *
    00637 *   Once one solution has been determined others may be found by subsequent
    00638 *   invokations of wcsmix() with suitably restricted solution intervals.
    00639 *
    00640 *   Note the circumstance that arises when the solution point lies at a native
    00641 *   pole of a projection in which the pole is represented as a finite curve,
    00642 *   for example the zenithals and conics.  In such cases two or more valid
    00643 *   solutions may exist but wcsmix() only ever returns one.
    00644 *
    00645 *   Because of its generality wcsmix() is very compute-intensive.  For
    00646 *   compute-limited applications more efficient special-case solvers could be
    00647 *   written for simple projections, for example non-oblique cylindrical
    00648 *   projections.
    00649 *
    00650 *
    00651 * wcssptr() - Spectral axis translation
    00652 * -------------------------------------
    00653 * wcssptr() translates the spectral axis in a wcsprm struct.  For example, a
    00654 * 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.
    00655 *
    00656 * Given and returned:
    00657 *   wcs       struct wcsprm*
    00658 *                       Coordinate transformation parameters.
    00659 *
    00660 *   i         int*      Index of the spectral axis (0-relative).  If given < 0
    00661 *                       it will be set to the first spectral axis identified
    00662 *                       from the ctype[] keyvalues in the wcsprm struct.
    00663 *
    00664 *   ctype     char[9]   Desired spectral CTYPEia.  Wildcarding may be used as
    00665 *                       for the ctypeS2 argument to spctrn() as described in
    00666 *                       the prologue of spc.h, i.e. if the final three
    00667 *                       characters are specified as "???", or if just the
    00668 *                       eighth character is specified as '?', the correct
    00669 *                       algorithm code will be substituted and returned.
    00670 *
    00671 * Function return value:
    00672 *             int       Status return value:
    00673 *                         0: Success.
    00674 *                         1: Null wcsprm pointer passed.
    00675 *                         2: Memory allocation failed.
    00676 *                         3: Linear transformation matrix is singular.
    00677 *                         4: Inconsistent or unrecognized coordinate axis
    00678 *                            types.
    00679 *                         5: Invalid parameter value.
    00680 *                         6: Invalid coordinate transformation parameters.
    00681 *                         7: Ill-conditioned coordinate transformation
    00682 *                            parameters.
    00683 *                        12: Invalid subimage specification (no spectral
    00684 *                            axis).
    00685 *
    00686 *                       For returns > 1, a detailed error message is set in
    00687 *                       wcsprm::err if enabled, see wcserr_enable().
    00688 *
    00689 *
    00690 * wcsprm struct - Coordinate transformation parameters
    00691 * ----------------------------------------------------
    00692 * The wcsprm struct contains information required to transform world
    00693 * coordinates.  It consists of certain members that must be set by the user
    00694 * ("given") and others that are set by the WCSLIB routines ("returned").
    00695 * Some of the former are not actually required for transforming coordinates.
    00696 * These are described as "auxiliary"; the struct simply provides a place to
    00697 * store them, though they may be used by wcshdo() in constructing a FITS
    00698 * header from a wcsprm struct.  Some of the returned values are supplied for
    00699 * informational purposes and others are for internal use only as indicated.
    00700 *
    00701 * In practice, it is expected that a WCS parser would scan the FITS header to
    00702 * determine the number of coordinate axes.  It would then use wcsini() to
    00703 * allocate memory for arrays in the wcsprm struct and set default values.
    00704 * Then as it reread the header and identified each WCS keyrecord it would load
    00705 * the value into the relevant wcsprm array element.  This is essentially what
    00706 * wcspih() does - refer to the prologue of wcshdr.h.  As the final step,
    00707 * wcsset() is invoked, either directly or indirectly, to set the derived
    00708 * members of the wcsprm struct.  wcsset() strips off trailing blanks in all
    00709 * string members and null-fills the character array.
    00710 *
    00711 *   int flag
    00712 *     (Given and returned) This flag must be set to zero whenever any of the
    00713 *     following wcsprm struct members are set or changed:
    00714 *
    00715 *       - wcsprm::naxis (q.v., not normally set by the user),
    00716 *       - wcsprm::crpix,
    00717 *       - wcsprm::pc,
    00718 *       - wcsprm::cdelt,
    00719 *       - wcsprm::crval,
    00720 *       - wcsprm::cunit,
    00721 *       - wcsprm::ctype,
    00722 *       - wcsprm::lonpole,
    00723 *       - wcsprm::latpole,
    00724 *       - wcsprm::restfrq,
    00725 *       - wcsprm::restwav,
    00726 *       - wcsprm::npv,
    00727 *       - wcsprm::pv,
    00728 *       - wcsprm::nps,
    00729 *       - wcsprm::ps,
    00730 *       - wcsprm::cd,
    00731 *       - wcsprm::crota,
    00732 *       - wcsprm::altlin.
    00733 *
    00734 *     This signals the initialization routine, wcsset(), to recompute the
    00735 *     returned members of the celprm struct.  celset() will reset flag to
    00736 *     indicate that this has been done.
    00737 *
    00738 *     PLEASE NOTE: flag should be set to -1 when wcsini() is called for the
    00739 *     first time for a particular wcsprm struct in order to initialize memory
    00740 *     management.  It must ONLY be used on the first initialization otherwise
    00741 *     memory leaks may result.
    00742 *
    00743 *   int naxis
    00744 *     (Given or returned) Number of pixel and world coordinate elements.
    00745 *
    00746 *     If wcsini() is used to initialize the linprm struct (as would normally
    00747 *     be the case) then it will set naxis from the value passed to it as a
    00748 *     function argument.  The user should not subsequently modify it.
    00749 *
    00750 *   double *crpix
    00751 *     (Given) Address of the first element of an array of double containing
    00752 *     the coordinate reference pixel, CRPIXja.
    00753 *
    00754 *   double *pc
    00755 *     (Given) Address of the first element of the PCi_ja (pixel coordinate)
    00756 *     transformation matrix.  The expected order is
    00757 *
    00758 =       struct wcsprm wcs;
    00759 =       wcs.pc = {PC1_1, PC1_2, PC2_1, PC2_2};
    00760 *
    00761 *     This may be constructed conveniently from a 2-D array via
    00762 *
    00763 =       double m[2][2] = {{PC1_1, PC1_2},
    00764 =                         {PC2_1, PC2_2}};
    00765 *
    00766 *     which is equivalent to
    00767 *
    00768 =       double m[2][2];
    00769 =       m[0][0] = PC1_1;
    00770 =       m[0][1] = PC1_2;
    00771 =       m[1][0] = PC2_1;
    00772 =       m[1][1] = PC2_2;
    00773 *
    00774 *     The storage order for this 2-D array is the same as for the 1-D array,
    00775 *     whence
    00776 *
    00777 =       wcs.pc = *m;
    00778 *
    00779 *     would be legitimate.
    00780 *
    00781 *   double *cdelt
    00782 *     (Given) Address of the first element of an array of double containing
    00783 *     the coordinate increments, CDELTia.
    00784 *
    00785 *   double *crval
    00786 *     (Given) Address of the first element of an array of double containing
    00787 *     the coordinate reference values, CRVALia.
    00788 *
    00789 *   char (*cunit)[72]
    00790 *     (Given) Address of the first element of an array of char[72] containing
    00791 *     the CUNITia keyvalues which define the units of measurement of the
    00792 *     CRVALia, CDELTia, and CDi_ja keywords.
    00793 *
    00794 *     As CUNITia is an optional header keyword, cunit[][72] may be left blank
    00795 *     but otherwise is expected to contain a standard units specification as
    00796 *     defined by WCS Paper I.  Utility function wcsutrn(), described in
    00797 *     wcsunits.h, is available to translate commonly used non-standard units
    00798 *     specifications but this must be done as a separate step before invoking
    00799 *     wcsset().
    00800 *
    00801 *     For celestial axes, if cunit[][72] is not blank, wcsset() uses
    00802 *     wcsunits() to parse it and scale cdelt[], crval[], and cd[][*] to
    00803 *     degrees.  It then resets cunit[][72] to "deg".
    00804 *
    00805 *     For spectral axes, if cunit[][72] is not blank, wcsset() uses wcsunits()
    00806 *     to parse it and scale cdelt[], crval[], and cd[][*] to SI units.  It
    00807 *     then resets cunit[][72] accordingly.
    00808 *
    00809 *     wcsset() ignores cunit[][72] for other coordinate types; cunit[][72] may
    00810 *     be used to label coordinate values.
    00811 *
    00812 *     These variables accomodate the longest allowed string-valued FITS
    00813 *     keyword, being limited to 68 characters, plus the null-terminating
    00814 *     character.
    00815 *
    00816 *   char (*ctype)[72]
    00817 *     (Given) Address of the first element of an array of char[72] containing
    00818 *     the coordinate axis types, CTYPEia.
    00819 *
    00820 *     The ctype[][72] keyword values must be in upper case and there must be
    00821 *     zero or one pair of matched celestial axis types, and zero or one
    00822 *     spectral axis.  The ctype[][72] strings should be padded with blanks on
    00823 *     the right and null-terminated so that they are at least eight characters
    00824 *     in length.
    00825 *
    00826 *     These variables accomodate the longest allowed string-valued FITS
    00827 *     keyword, being limited to 68 characters, plus the null-terminating
    00828 *     character.
    00829 *
    00830 *   double lonpole
    00831 *     (Given and returned) The native longitude of the celestial pole, phi_p,
    00832 *     given by LONPOLEa [deg] or by PVi_2a [deg] attached to the longitude
    00833 *     axis which takes precedence if defined, and ...
    00834 *   double latpole
    00835 *     (Given and returned) ... the native latitude of the celestial pole,
    00836 *     theta_p, given by LATPOLEa [deg] or by PVi_3a [deg] attached to the
    00837 *     longitude axis which takes precedence if defined.
    00838 *
    00839 *     lonpole and latpole may be left to default to values set by wcsini()
    00840 *     (see celprm::ref), but in any case they will be reset by wcsset() to
    00841 *     the values actually used.  Note therefore that if the wcsprm struct is
    00842 *     reused without resetting them, whether directly or via wcsini(), they
    00843 *     will no longer have their default values.
    00844 *
    00845 *   double restfrq
    00846 *     (Given) The rest frequency [Hz], and/or ...
    00847 *   double restwav
    00848 *     (Given) ... the rest wavelength in vacuuo [m], only one of which need be
    00849 *     given, the other should be set to zero.
    00850 *
    00851 *   int npv
    00852 *     (Given) The number of entries in the wcsprm::pv[] array.
    00853 *
    00854 *   int npvmax
    00855 *     (Given or returned) The length of the wcsprm::pv[] array.
    00856 *
    00857 *     npvmax will be set by wcsini() if it allocates memory for wcsprm::pv[],
    00858 *     otherwise it must be set by the user.  See also wcsnpv().
    00859 *
    00860 *   struct pvcard *pv
    00861 *     (Given or returned) Address of the first element of an array of length
    00862 *     npvmax of pvcard structs.  Set by wcsini() if it allocates memory for
    00863 *     pv[], otherwise it must be set by the user.  See also wcsnpv().
    00864 *
    00865 *     As a FITS header parser encounters each PVi_ma keyword it should load it
    00866 *     into a pvcard struct in the array and increment npv.  wcsset()
    00867 *     interprets these as required.
    00868 *
    00869 *     Note that, if they were not given, wcsset() resets the entries for
    00870 *     PVi_1a, PVi_2a, PVi_3a, and PVi_4a for longitude axis i to match
    00871 *     phi_0 and theta_0 (the native longitude and latitude of the reference
    00872 *     point), LONPOLEa and LATPOLEa respectively.
    00873 *
    00874 *   int nps
    00875 *     (Given) The number of entries in the wcsprm::ps[] array.
    00876 *
    00877 *   int npsmax
    00878 *     (Given or returned) The length of the wcsprm::ps[] array.
    00879 *
    00880 *     npsmax will be set by wcsini() if it allocates memory for wcsprm::ps[],
    00881 *     otherwise it must be set by the user.  See also wcsnps().
    00882 *
    00883 *   struct pscard *ps
    00884 *     (Given or returned) Address of the first element of an array of length
    00885 *     npsmax of pscard structs.  Set by wcsini() if it allocates memory for
    00886 *     ps[], otherwise it must be set by the user.  See also wcsnps().
    00887 *
    00888 *     As a FITS header parser encounters each PSi_ma keyword it should load it
    00889 *     into a pscard struct in the array and increment nps.  wcsset()
    00890 *     interprets these as required (currently no PSi_ma keyvalues are
    00891 *     recognized).
    00892 *
    00893 *   double *cd
    00894 *     (Given) For historical compatibility, the wcsprm struct supports two
    00895 *     alternate specifications of the linear transformation matrix, those
    00896 *     associated with the CDi_ja keywords, and ...
    00897 *   double *crota
    00898 *     (Given) ... those associated with the CROTAia keywords.  Although these
    00899 *     may not formally co-exist with PCi_ja, the approach taken here is simply
    00900 *     to ignore them if given in conjunction with PCi_ja.
    00901 *
    00902 *   int altlin
    00903 *     (Given) altlin is a bit flag that denotes which of the PCi_ja, CDi_ja
    00904 *     and CROTAia keywords are present in the header:
    00905 *
    00906 *     - Bit 0: PCi_ja is present.
    00907 *
    00908 *     - Bit 1: CDi_ja is present.
    00909 *
    00910 *       Matrix elements in the IRAF convention are
    00911 *       equivalent to the product CDi_ja = CDELTia * PCi_ja, but the
    00912 *       defaults differ from that of the PCi_ja matrix.  If one or more
    00913 *       CDi_ja keywords are present then all unspecified CDi_ja default to
    00914 *       zero.  If no CDi_ja (or CROTAia) keywords are present, then the
    00915 *       header is assumed to be in PCi_ja form whether or not any PCi_ja
    00916 *       keywords are present since this results in an interpretation of
    00917 *       CDELTia consistent with the original FITS specification.
    00918 *
    00919 *       While CDi_ja may not formally co-exist with PCi_ja, it may co-exist
    00920 *       with CDELTia and CROTAia which are to be ignored.
    00921 *
    00922 *     - Bit 2: CROTAia is present.
    00923 *
    00924 *       In the AIPS convention, CROTAia may only be
    00925 *       associated with the latitude axis of a celestial axis pair.  It
    00926 *       specifies a rotation in the image plane that is applied AFTER the
    00927 *       CDELTia; any other CROTAia keywords are ignored.
    00928 *
    00929 *       CROTAia may not formally co-exist with PCi_ja.
    00930 *
    00931 *       CROTAia and CDELTia may formally co-exist with CDi_ja but if so are to
    00932 *       be ignored.
    00933 *
    00934 *     CDi_ja and CROTAia keywords, if found, are to be stored in the
    00935 *     wcsprm::cd and wcsprm::crota arrays which are dimensioned similarly to
    00936 *     wcsprm::pc and wcsprm::cdelt.  FITS
    00937 *     header parsers should use the following procedure:
    00938 *
    00939 *     - Whenever a PCi_ja  keyword is encountered: altlin |= 1;
    00940 *
    00941 *     - Whenever a CDi_ja  keyword is encountered: altlin |= 2;
    00942 *
    00943 *     - Whenever a CROTAia keyword is encountered: altlin |= 4;
    00944 *
    00945 *     If none of these bits are set the PCi_ja representation results, i.e.
    00946 *     wcsprm::pc and wcsprm::cdelt will be used as given.
    00947 *
    00948 *     These alternate specifications of the linear transformation matrix are
    00949 *     translated immediately to PCi_ja by wcsset() and are invisible to the
    00950 *     lower-level WCSLIB routines.  In particular, wcsset() resets
    00951 *     wcsprm::cdelt to unity if CDi_ja is present (and no PCi_ja).
    00952 *
    00953 *     If CROTAia are present but none is associated with the latitude axis
    00954 *     (and no PCi_ja or CDi_ja), then wcsset() reverts to a unity PCi_ja
    00955 *     matrix.
    00956 *
    00957 *   int velref
    00958 *     (Given) AIPS velocity code VELREF, refer to spcaips().
    00959 *
    00960 *   char alt[4]
    00961 *     (Given, auxiliary) Character code for alternate coordinate descriptions
    00962 *     (i.e. the 'a' in keyword names such as CTYPEia).  This is blank for the
    00963 *     primary coordinate description, or one of the 26 upper-case letters,
    00964 *     A-Z.
    00965 *
    00966 *     An array of four characters is provided for alignment purposes, only the
    00967 *     first is used.
    00968 *
    00969 *   int colnum
    00970 *     (Given, auxiliary) Where the coordinate representation is associated
    00971 *     with an image-array column in a FITS binary table, this variable may be
    00972 *     used to record the relevant column number.
    00973 *
    00974 *     It should be set to zero for an image header or pixel list.
    00975 *
    00976 *   int *colax
    00977 *     (Given, auxiliary) Address of the first element of an array of int
    00978 *     recording the column numbers for each axis in a pixel list.
    00979 *
    00980 *     The array elements should be set to zero for an image header or image
    00981 *     array in a binary table.
    00982 *
    00983 *   char (*cname)[72]
    00984 *     (Given, auxiliary) The address of the first element of an array of
    00985 *     char[72] containing the coordinate axis names, CNAMEia.
    00986 *
    00987 *     These variables accomodate the longest allowed string-valued FITS
    00988 *     keyword, being limited to 68 characters, plus the null-terminating
    00989 *     character.
    00990 *
    00991 *   double *crder
    00992 *     (Given, auxiliary) Address of the first element of an array of double
    00993 *     recording the random error in the coordinate value, CRDERia.
    00994 *   double *csyer
    00995 *     (Given, auxiliary) Address of the first element of an array of double
    00996 *     recording the systematic error in the coordinate value, CSYERia.
    00997 *
    00998 *   char dateavg[72]
    00999 *     (Given, auxiliary) The date of a representative mid-point of the
    01000 *     observation in ISO format, yyyy-mm-ddThh:mm:ss.
    01001 *   char dateobs[72]
    01002 *     (Given, auxiliary) The date of the start of the observation unless
    01003 *     otherwise explained in the comment field of the DATE-OBS keyword, in
    01004 *     ISO format, yyyy-mm-ddThh:mm:ss.
    01005 *
    01006 *   double equinox
    01007 *     (Given, auxiliary) The equinox associated with dynamical equatorial or
    01008 *     ecliptic coordinate systems, EQUINOXa (or EPOCH in older headers).  Not
    01009 *     applicable to ICRS equatorial or ecliptic coordinates.
    01010 *
    01011 *   double mjdavg
    01012 *     (Given, auxiliary) Modified Julian Date (MJD = JD - 2400000.5), MJD-AVG,
    01013 *     corresponding to DATE-AVG.
    01014 *   double mjdobs
    01015 *     (Given, auxiliary) Modified Julian Date (MJD = JD - 2400000.5), MJD-OBS,
    01016 *     corresponding to DATE-OBS.
    01017 *
    01018 *   double obsgeo[3]
    01019 *     (Given, auxiliary) Location of the observer in a standard terrestrial
    01020 *     reference frame, OBSGEO-X, OBSGEO-Y, OBSGEO-Z [m].
    01021 *
    01022 *   char radesys[72]
    01023 *     (Given, auxiliary) The equatorial or ecliptic coordinate system type,
    01024 *     RADESYSa.
    01025 *
    01026 *   char specsys[72]
    01027 *     (Given, auxiliary) Spectral reference frame (standard of rest),
    01028 *     SPECSYSa, and ...
    01029 *   char ssysobs[72]
    01030 *     (Given, auxiliary) ... the actual frame in which there is no
    01031 *     differential variation in the spectral coordinate across the
    01032 *     field-of-view, SSYSOBSa.
    01033 *   double velosys
    01034 *     (Given, auxiliary) The relative radial velocity [m/s] between the
    01035 *     observer and the selected standard of rest in the direction of the
    01036 *     celestial reference coordinate, VELOSYSa.
    01037 *
    01038 *   double zsource
    01039 *     (Given, auxiliary) The redshift, ZSOURCEa, of the source, and ...
    01040 *   char ssyssrc[72]
    01041 *     (Given, auxiliary) ... the spectral reference frame (standard of rest)
    01042 *     in which this was measured, SSYSSRCa.
    01043 *
    01044 *   double velangl
    01045 *     (Given, auxiliary) The angle [deg] that should be used to decompose an
    01046 *     observed velocity into radial and transverse components.
    01047 *
    01048 *   char wcsname[72]
    01049 *     (Given, auxiliary) The name given to the coordinate representation,
    01050 *     WCSNAMEa.  This variable accomodates the longest allowed string-valued
    01051 *     FITS keyword, being limited to 68 characters, plus the null-terminating
    01052 *     character.
    01053 *
    01054 *   int ntab
    01055 *     (Given) See wcsprm::tab.
    01056 *
    01057 *   int nwtb
    01058 *     (Given) See wcsprm::wtb.
    01059 *
    01060 *   struct tabprm *tab
    01061 *     (Given) Address of the first element of an array of ntab tabprm structs
    01062 *     for which memory has been allocated.  These are used to store tabular
    01063 *     transformation parameters.
    01064 *
    01065 *     Although technically wcsprm::ntab and tab are "given", they will
    01066 *     normally be set by invoking wcstab(), whether directly or indirectly.
    01067 *
    01068 *     The tabprm structs contain some members that must be supplied and others
    01069 *     that are derived.  The information to be supplied comes primarily from
    01070 *     arrays stored in one or more FITS binary table extensions.  These
    01071 *     arrays, referred to here as "wcstab arrays", are themselves located by
    01072 *     parameters stored in the FITS image header.
    01073 *
    01074 *   struct wtbarr *wtb
    01075 *     (Given) Address of the first element of an array of nwtb wtbarr structs
    01076 *     for which memory has been allocated.  These are used in extracting
    01077 *     wcstab arrays from a FITS binary table.
    01078 *
    01079 *     Although technically wcsprm::nwtb and wtb are "given", they will
    01080 *     normally be set by invoking wcstab(), whether directly or indirectly.
    01081 *
    01082 *   char lngtyp[8]
    01083 *     (Returned) Four-character WCS celestial longitude and ...
    01084 *   char lattyp[8]
    01085 *     (Returned) ... latitude axis types. e.g. "RA", "DEC", "GLON", "GLAT",
    01086 *     etc. extracted from 'RA--', 'DEC-', 'GLON', 'GLAT', etc. in the first
    01087 *     four characters of CTYPEia but with trailing dashes removed.  (Declared
    01088 *     as char[8] for alignment reasons.)
    01089 *
    01090 *   int lng
    01091 *     (Returned) Index for the longitude coordinate, and ...
    01092 *   int lat
    01093 *     (Returned) ... index for the latitude coordinate, and ...
    01094 *   int spec
    01095 *     (Returned) ... index for the spectral coordinate in the imgcrd[][] and
    01096 *     world[][] arrays in the API of wcsp2s(), wcss2p() and wcsmix().
    01097 *
    01098 *     These may also serve as indices into the pixcrd[][] array provided that
    01099 *     the PCi_ja matrix does not transpose axes.
    01100 *
    01101 *   int cubeface
    01102 *     (Returned) Index into the pixcrd[][] array for the CUBEFACE axis.  This
    01103 *     is used for quadcube projections where the cube faces are stored on a
    01104 *     separate axis (see wcs.h).
    01105 *
    01106 *   int *types
    01107 *     (Returned) Address of the first element of an array of int containing a
    01108 *     four-digit type code for each axis.
    01109 *
    01110 *     - First digit (i.e. 1000s):
    01111 *       - 0: Non-specific coordinate type.
    01112 *       - 1: Stokes coordinate.
    01113 *       - 2: Celestial coordinate (including CUBEFACE).
    01114 *       - 3: Spectral coordinate.
    01115 *
    01116 *     - Second digit (i.e. 100s):
    01117 *       - 0: Linear axis.
    01118 *       - 1: Quantized axis (STOKES, CUBEFACE).
    01119 *       - 2: Non-linear celestial axis.
    01120 *       - 3: Non-linear spectral axis.
    01121 *       - 4: Logarithmic axis.
    01122 *       - 5: Tabular axis.
    01123 *
    01124 *     - Third digit (i.e. 10s):
    01125 *       - 0: Group number, e.g. lookup table number, being an index into the
    01126 *            tabprm array (see above).
    01127 *
    01128 *     - The fourth digit is used as a qualifier depending on the axis type.
    01129 *
    01130 *       - For celestial axes:
    01131 *         - 0: Longitude coordinate.
    01132 *         - 1: Latitude coordinate.
    01133 *         - 2: CUBEFACE number.
    01134 *
    01135 *       - For lookup tables: the axis number in a multidimensional table.
    01136 *
    01137 *     CTYPEia in "4-3" form with unrecognized algorithm code will have its
    01138 *     type set to -1 and generate an error.
    01139 *
    01140 *   void *padding
    01141 *     (An unused variable inserted for alignment purposes only.)
    01142 *
    01143 *   struct linprm lin
    01144 *     (Returned) Linear transformation parameters (usage is described in the
    01145 *     prologue to lin.h).
    01146 *
    01147 *   struct celprm cel
    01148 *     (Returned) Celestial transformation parameters (usage is described in
    01149 *     the prologue to cel.h).
    01150 *
    01151 *   struct spcprm spc
    01152 *     (Returned) Spectral transformation parameters (usage is described in the
    01153 *     prologue to spc.h).
    01154 *
    01155 *   struct wcserr *err
    01156 *     (Returned) If enabled, when an error status is returned this struct
    01157 *     contains detailed information about the error, see wcserr_enable().
    01158 *
    01159 *   void *m_padding
    01160 *     (For internal use only.)
    01161 *   int m_flag
    01162 *     (For internal use only.)
    01163 *   int m_naxis
    01164 *     (For internal use only.)
    01165 *   double *m_crpix
    01166 *     (For internal use only.)
    01167 *   double *m_pc
    01168 *     (For internal use only.)
    01169 *   double *m_cdelt
    01170 *     (For internal use only.)
    01171 *   double *m_crval
    01172 *     (For internal use only.)
    01173 *   char (*m_cunit)[72]
    01174 *     (For internal use only.)
    01175 *   char (*m_ctype)[72]
    01176 *     (For internal use only.)
    01177 *   struct pvcard *m_pv
    01178 *     (For internal use only.)
    01179 *   struct pscard *m_ps
    01180 *     (For internal use only.)
    01181 *   double *m_cd
    01182 *     (For internal use only.)
    01183 *   double *m_crota
    01184 *     (For internal use only.)
    01185 *   int *m_colax
    01186 *     (For internal use only.)
    01187 *   char (*m_cname)[72]
    01188 *     (For internal use only.)
    01189 *   double *m_crder
    01190 *     (For internal use only.)
    01191 *   double *m_csyer
    01192 *     (For internal use only.)
    01193 *   struct tabprm *m_tab
    01194 *     (For internal use only.)
    01195 *   struct wtbarr *m_wtb
    01196 *     (For internal use only.)
    01197 *
    01198 *
    01199 * pscard struct - Store for PSi_ma keyrecords
    01200 * -------------------------------------------
    01201 * The pscard struct is used to pass the parsed contents of PSi_ma keyrecords
    01202 * to wcsset() via the wcsprm struct.
    01203 *
    01204 * All members of this struct are to be set by the user.
    01205 *
    01206 *   int i
    01207 *     (Given) Axis number (1-relative), as in the FITS PSi_ma keyword.
    01208 *
    01209 *   int m
    01210 *     (Given) Parameter number (non-negative), as in the FITS PSi_ma keyword.
    01211 *
    01212 *   char value[72]
    01213 *     (Given) Parameter value.
    01214 *
    01215 *
    01216 * pvcard struct - Store for PVi_ma keyrecords
    01217 * -------------------------------------------
    01218 * The pvcard struct is used to pass the parsed contents of PVi_ma keyrecords
    01219 * to wcsset() via the wcsprm struct.
    01220 *
    01221 * All members of this struct are to be set by the user.
    01222 *
    01223 *   int i
    01224 *     (Given) Axis number (1-relative), as in the FITS PVi_ma keyword.  If
    01225 *     i == 0, wcsset() will replace it with the latitude axis number.
    01226 *
    01227 *   int m
    01228 *     (Given) Parameter number (non-negative), as in the FITS PVi_ma keyword.
    01229 *
    01230 *   double value
    01231 *     (Given) Parameter value.
    01232 *
    01233 *
    01234 * wtbarr struct - Extraction of coordinate lookup tables from BINTABLE
    01235 * --------------------------------------------------------------------
    01236 * Function wcstab(), which is invoked automatically by wcspih(), sets up an
    01237 * array of wtbarr structs to assist in extracting coordinate lookup tables
    01238 * from a binary table extension (BINTABLE) and copying them into the tabprm
    01239 * structs stored in wcsprm.  Refer to the usage notes for wcspih() and
    01240 * wcstab() in wcshdr.h, and also the prologue to tab.h.
    01241 *
    01242 * For C++ usage, because of a name space conflict with the wtbarr typedef
    01243 * defined in CFITSIO header fitsio.h, the wtbarr struct is renamed to wtbarr_s
    01244 * by preprocessor macro substitution with scope limited to wcs.h itself.
    01245 *
    01246 *   int i
    01247 *     (Given) Image axis number.
    01248 *
    01249 *   int m
    01250 *     (Given) wcstab array axis number for index vectors.
    01251 *
    01252 *   int kind
    01253 *     (Given) Character identifying the wcstab array type:
    01254 *       - c: coordinate array,
    01255 *       - i: index vector.
    01256 *
    01257 *   char extnam[72]
    01258 *     (Given) EXTNAME identifying the binary table extension.
    01259 *
    01260 *   int extver
    01261 *     (Given) EXTVER identifying the binary table extension.
    01262 *
    01263 *   int extlev
    01264 *     (Given) EXTLEV identifying the binary table extension.
    01265 *
    01266 *   char ttype[72]
    01267 *     (Given) TTYPEn identifying the column of the binary table that contains
    01268 *     the wcstab array.
    01269 *
    01270 *   long row
    01271 *     (Given) Table row number.
    01272 *
    01273 *   int ndim
    01274 *     (Given) Expected dimensionality of the wcstab array.
    01275 *
    01276 *   int *dimlen
    01277 *     (Given) Address of the first element of an array of int of length ndim
    01278 *     into which the wcstab array axis lengths are to be written.
    01279 *
    01280 *   double **arrayp
    01281 *     (Given) Pointer to an array of double which is to be allocated by the
    01282 *     user and into which the wcstab array is to be written.
    01283 *
    01284 *
    01285 * Global variable: const char *wcs_errmsg[] - Status return messages
    01286 * ------------------------------------------------------------------
    01287 * Error messages to match the status value returned from each function.
    01288 *
    01289 *===========================================================================*/
    01290
    01291 #ifndef WCSLIB_WCS
    01292 #define WCSLIB_WCS
    01293
    01294 #include "lin.h"
    01295 #include "cel.h"
    01296 #include "spc.h"
    01297 #include "tab.h"
    01298 #include "wcserr.h"
    01299
    01300 #ifdef __cplusplus
    01301 extern "C" {
    01302 #endif
    01303
    01304 #define WCSSUB_LONGITUDE 0x1001
    01305 #define WCSSUB_LATITUDE  0x1002
    01306 #define WCSSUB_CUBEFACE  0x1004
    01307 #define WCSSUB_CELESTIAL 0x1007
    01308 #define WCSSUB_SPECTRAL  0x1008
    01309 #define WCSSUB_STOKES    0x1010
    01310
    01311
    01312 extern const char *wcs_errmsg[];
    01313
    01314 enum wcs_errmsg_enum {
    01315   WCSERR_SUCCESS         =  0,  /* Success. */
    01316   WCSERR_NULL_POINTER    =  1,  /* Null wcsprm pointer passed. */
    01317   WCSERR_MEMORY          =  2,  /* Memory allocation failed. */
    01318   WCSERR_SINGULAR_MTX    =  3,  /* Linear transformation matrix is
    01319                                    singular. */
    01320   WCSERR_BAD_CTYPE       =  4,  /* Inconsistent or unrecognized coordinate
    01321                                    axis types. */
    01322   WCSERR_BAD_PARAM       =  5,  /* Invalid parameter value. */
    01323   WCSERR_BAD_COORD_TRANS =  6,  /* Invalid coordinate transformation
    01324                                    parameters. */
    01325   WCSERR_ILL_COORD_TRANS =  7,  /* Ill-conditioned coordinate transformation
    01326                                    parameters. */
    01327   WCSERR_BAD_PIX         =  8,  /* One or more of the pixel coordinates were
    01328                                    invalid. */
    01329   WCSERR_BAD_WORLD       =  9,  /* One or more of the world coordinates were
    01330                                    invalid. */
    01331   WCSERR_BAD_WORLD_COORD = 10,  /* Invalid world coordinate. */
    01332   WCSERR_NO_SOLUTION     = 11,  /* No solution found in the specified
    01333                                    interval. */
    01334   WCSERR_BAD_SUBIMAGE    = 12,  /* Invalid subimage specification. */
    01335   WCSERR_NON_SEPARABLE   = 13   /* Non-separable subimage coordinate
    01336                                    system. */
    01337 };
    01338
    01339
    01340 /* Struct used for storing PVi_ma keywords. */
    01341 struct pvcard {
    01342   int i;                        /* Axis number, as in PVi_ma (1-relative).  */
    01343   int m;                        /* Parameter number, ditto  (0-relative).   */
    01344   double value;                 /* Parameter value.                         */
    01345 };
    01346
    01347 /* Struct used for storing PSi_ma keywords. */
    01348 struct pscard {
    01349   int i;                        /* Axis number, as in PSi_ma (1-relative).  */
    01350   int m;                        /* Parameter number, ditto  (0-relative).   */
    01351   char value[72];               /* Parameter value.                         */
    01352 };
    01353
    01354                                 /* For extracting wcstab arrays.  Matches   */
    01355                                 /* the wtbarr typedef defined in CFITSIO    */
    01356                                 /* header fitsio.h.                         */
    01357 #ifdef __cplusplus
    01358 #define wtbarr wtbarr_s         /* See prologue above.                      */
    01359 #endif
    01360 struct wtbarr {
    01361   int  i;                       /* Image axis number.                       */
    01362   int  m;                       /* Array axis number for index vectors.     */
    01363   int  kind;                    /* wcstab array type.                       */
    01364   char extnam[72];              /* EXTNAME of binary table extension.       */
    01365   int  extver;                  /* EXTVER  of binary table extension.       */
    01366   int  extlev;                  /* EXTLEV  of binary table extension.       */
    01367   char ttype[72];               /* TTYPEn of column containing the array.   */
    01368   long row;                     /* Table row number.                        */
    01369   int  ndim;                    /* Expected wcstab array dimensionality.    */
    01370   int  *dimlen;                 /* Where to write the array axis lengths.   */
    01371   double **arrayp;              /* Where to write the address of the array  */
    01372                                 /* allocated to store the wcstab array.     */
    01373 };
    01374
    01375
    01376 struct wcsprm {
    01377   /* Initialization flag (see the prologue above).                          */
    01378   /*------------------------------------------------------------------------*/
    01379   int    flag;                  /* Set to zero to force initialization.     */
    01380
    01381   /* FITS header keyvalues to be provided (see the prologue above).         */
    01382   /*------------------------------------------------------------------------*/
    01383   int    naxis;                 /* Number of axes (pixel and coordinate).   */
    01384   double *crpix;                /* CRPIXja keyvalues for each pixel axis.   */
    01385   double *pc;                   /* PCi_ja  linear transformation matrix.    */
    01386   double *cdelt;                /* CDELTia keyvalues for each coord axis.   */
    01387   double *crval;                /* CRVALia keyvalues for each coord axis.   */
    01388
    01389   char   (*cunit)[72];          /* CUNITia keyvalues for each coord axis.   */
    01390   char   (*ctype)[72];          /* CTYPEia keyvalues for each coord axis.   */
    01391
    01392   double lonpole;               /* LONPOLEa keyvalue.                       */
    01393   double latpole;               /* LATPOLEa keyvalue.                       */
    01394
    01395   double restfrq;               /* RESTFRQa keyvalue.                       */
    01396   double restwav;               /* RESTWAVa keyvalue.                       */
    01397
    01398   int    npv;                   /* Number of PVi_ma keywords, and the       */
    01399   int    npvmax;                /* number for which space was allocated.    */
    01400   struct pvcard *pv;            /* PVi_ma keywords for each i and m.        */
    01401
    01402   int    nps;                   /* Number of PSi_ma keywords, and the       */
    01403   int    npsmax;                /* number for which space was allocated.    */
    01404   struct pscard *ps;            /* PSi_ma keywords for each i and m.        */
    01405
    01406   /* Alternative header keyvalues (see the prologue above).                 */
    01407   /*------------------------------------------------------------------------*/
    01408   double *cd;                   /* CDi_ja linear transformation matrix.     */
    01409   double *crota;                /* CROTAia keyvalues for each coord axis.   */
    01410   int    altlin;                /* Alternative representations              */
    01411                                 /*   Bit 0: PCi_ja  is present,             */
    01412                                 /*   Bit 1: CDi_ja  is present,             */
    01413                                 /*   Bit 2: CROTAia is present.             */
    01414   int    velref;                /* AIPS velocity code, VELREF.              */
    01415
    01416   /* Auxiliary coordinate system information, not used by WCSLIB.           */
    01417   char   alt[4];
    01418   int    colnum;
    01419   int    *colax;
    01420
    01421   char   (*cname)[72];
    01422   double *crder;
    01423   double *csyer;
    01424   char   dateavg[72];
    01425   char   dateobs[72];
    01426   double equinox;
    01427   double mjdavg;
    01428   double mjdobs;
    01429   double obsgeo[3];
    01430   char   radesys[72];
    01431   char   specsys[72];
    01432   char   ssysobs[72];
    01433   double velosys;
    01434   double zsource;
    01435   char   ssyssrc[72];
    01436   double velangl;
    01437   char   wcsname[72];
    01438
    01439   /* Coordinate lookup tables (see the prologue above).                     */
    01440   /*------------------------------------------------------------------------*/
    01441   int    ntab;                  /* Number of separate tables.               */
    01442   int    nwtb;                  /* Number of wtbarr structs.                */
    01443   struct tabprm *tab;           /* Tabular transformation parameters.       */
    01444   struct wtbarr *wtb;           /* Array of wtbarr structs.                 */
    01445
    01446   /* Information derived from the FITS header keyvalues by wcsset().        */
    01447   /*------------------------------------------------------------------------*/
    01448   char   lngtyp[8], lattyp[8];  /* Celestial axis types, e.g. RA, DEC.      */
    01449   int    lng, lat, spec;        /* Longitude, latitude and spectral axis    */
    01450                                 /* indices (0-relative).                    */
    01451   int    cubeface;              /* True if there is a CUBEFACE axis.        */
    01452   int    *types;                /* Coordinate type codes for each axis.     */
    01453   void   *padding;              /* (Dummy inserted for alignment purposes.) */
    01454
    01455   struct linprm lin;            /* Linear    transformation parameters.     */
    01456   struct celprm cel;            /* Celestial transformation parameters.     */
    01457   struct spcprm spc;            /* Spectral  transformation parameters.     */
    01458
    01459   /* Error handling                                                         */
    01460   /*------------------------------------------------------------------------*/
    01461   struct wcserr *err;
    01462
    01463   /* Private - the remainder are for memory management.                     */
    01464   /*------------------------------------------------------------------------*/
    01465   void   *m_padding;
    01466   int    m_flag, m_naxis;
    01467   double *m_crpix, *m_pc, *m_cdelt, *m_crval;
    01468   char  (*m_cunit)[72], (*m_ctype)[72];
    01469   struct pvcard *m_pv;
    01470   struct pscard *m_ps;
    01471   double *m_cd, *m_crota;
    01472   int    *m_colax;
    01473   char  (*m_cname)[72];
    01474   double *m_crder, *m_csyer;
    01475   struct tabprm *m_tab;
    01476   struct wtbarr *m_wtb;
    01477 };
    01478
    01479 /* Size of the wcsprm struct in int units, used by the Fortran wrappers. */
    01480 #define WCSLEN (sizeof(struct wcsprm)/sizeof(int))
    01481
    01482
    01483 int wcsnpv(int n);
    01484
    01485 int wcsnps(int n);
    01486
    01487 int wcsini(int alloc, int naxis, struct wcsprm *wcs);
    01488
    01489 int wcssub(int alloc, const struct wcsprm *wcssrc, int *nsub, int axes[],
    01490            struct wcsprm *wcsdst);
    01491
    01492 int wcsfree(struct wcsprm *wcs);
    01493
    01494 int wcsprt(const struct wcsprm *wcs);
    01495
    01496 int wcsperr(const struct wcsprm *wcs, const char *prefix);
    01497
    01498 int wcsset(struct wcsprm *wcs);
    01499
    01500 int wcsp2s(struct wcsprm *wcs, int ncoord, int nelem, const double pixcrd[],
    01501            double imgcrd[], double phi[], double theta[], double world[],
    01502            int stat[]);
    01503
    01504 int wcss2p(struct wcsprm *wcs, int ncoord, int nelem, const double world[],
    01505            double phi[], double theta[], double imgcrd[], double pixcrd[],
    01506            int stat[]);
    01507
    01508 int wcsmix(struct wcsprm *wcs, int mixpix, int mixcel, const double vspan[],
    01509            double vstep, int viter, double world[], double phi[],
    01510            double theta[], double imgcrd[], double pixcrd[]);
    01511
    01512 int wcssptr(struct wcsprm *wcs, int *i, char ctype[9]);
    01513
    01514 /* Defined mainly for backwards compatibility, use wcssub() instead. */
    01515 #define wcscopy(alloc, wcssrc, wcsdst) wcssub(alloc, wcssrc, 0x0, 0x0, wcsdst)
    01516
    01517
    01518 /* Deprecated. */
    01519 #define wcsini_errmsg wcs_errmsg
    01520 #define wcssub_errmsg wcs_errmsg
    01521 #define wcscopy_errmsg wcs_errmsg
    01522 #define wcsfree_errmsg wcs_errmsg
    01523 #define wcsprt_errmsg wcs_errmsg
    01524 #define wcsset_errmsg wcs_errmsg
    01525 #define wcsp2s_errmsg wcs_errmsg
    01526 #define wcss2p_errmsg wcs_errmsg
    01527 #define wcsmix_errmsg wcs_errmsg
    01528
    01529 #ifdef __cplusplus
    01530 #undef wtbarr
    01531 }
    01532 #endif
    01533
    01534 #endif /* WCSLIB_WCS */