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