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