- Main Page
- Related Pages
- Data Structures
- Files

# wcs.h

Go to the documentation of this file.

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