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 */