00001 /*============================================================================ 00002 00003 WCSLIB 4.15 - 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 Direct correspondence concerning WCSLIB to mark@calabretta.id.au 00022 00023 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO. 00024 http://www.atnf.csiro.au/people/Mark.Calabretta 00025 $Id: tab.h,v 4.15 2012/09/26 14:26:05 cal103 Exp $ 00026 *============================================================================= 00027 * 00028 * WCSLIB 4.15 - C routines that implement tabular coordinate systems as 00029 * defined by the FITS World Coordinate System (WCS) standard. Refer to 00030 * 00031 * "Representations of world coordinates in FITS", 00032 * Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (paper I) 00033 * 00034 * "Representations of spectral coordinates in FITS", 00035 * Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L. 00036 * 2006, A&A, 446, 747 (Paper III) 00037 * 00038 * Refer to the README file provided with WCSLIB for an overview of the 00039 * library. 00040 * 00041 * 00042 * Summary of the tab routines 00043 * --------------------------- 00044 * These routines implement the part of the FITS WCS standard that deals with 00045 * tabular coordinates, i.e. coordinates that are defined via a lookup table. 00046 * They define methods to be used for computing tabular world coordinates from 00047 * intermediate world coordinates (a linear transformation of image pixel 00048 * coordinates), and vice versa. They are based on the tabprm struct which 00049 * contains all information needed for the computations. The struct contains 00050 * some members that must be set by the user, and others that are maintained 00051 * by these routines, somewhat like a C++ class but with no encapsulation. 00052 * 00053 * tabini(), tabmem(), tabcpy(), and tabfree() are provided to manage the 00054 * tabprm struct, and another, tabprt(), to print its contents. 00055 * 00056 * A setup routine, tabset(), computes intermediate values in the tabprm struct 00057 * from parameters in it that were supplied by the user. The struct always 00058 * needs to be set up by tabset() but it need not be called explicitly - refer 00059 * to the explanation of tabprm::flag. 00060 * 00061 * tabx2s() and tabs2x() implement the WCS tabular coordinate transformations. 00062 * 00063 * Accuracy: 00064 * --------- 00065 * No warranty is given for the accuracy of these routines (refer to the 00066 * copyright notice); intending users must satisfy for themselves their 00067 * adequacy for the intended purpose. However, closure effectively to within 00068 * double precision rounding error was demonstrated by test routine ttab.c 00069 * which accompanies this software. 00070 * 00071 * 00072 * tabini() - Default constructor for the tabprm struct 00073 * ---------------------------------------------------- 00074 * tabini() allocates memory for arrays in a tabprm struct and sets all members 00075 * of the struct to default values. 00076 * 00077 * PLEASE NOTE: every tabprm struct should be initialized by tabini(), possibly 00078 * repeatedly. On the first invokation, and only the first invokation, the 00079 * flag member of the tabprm struct must be set to -1 to initialize memory 00080 * management, regardless of whether tabini() will actually be used to allocate 00081 * memory. 00082 * 00083 * Given: 00084 * alloc int If true, allocate memory unconditionally for arrays in 00085 * the tabprm struct. 00086 * 00087 * If false, it is assumed that pointers to these arrays 00088 * have been set by the user except if they are null 00089 * pointers in which case memory will be allocated for 00090 * them regardless. (In other words, setting alloc true 00091 * saves having to initalize these pointers to zero.) 00092 * 00093 * M int The number of tabular coordinate axes. 00094 * 00095 * K const int[] 00096 * Vector of length M whose elements (K_1, K_2,... K_M) 00097 * record the lengths of the axes of the coordinate array 00098 * and of each indexing vector. M and K[] are used to 00099 * determine the length of the various tabprm arrays and 00100 * therefore the amount of memory to allocate for them. 00101 * Their values are copied into the tabprm struct. 00102 * 00103 * It is permissible to set K (i.e. the address of the 00104 * array) to zero which has the same effect as setting 00105 * each element of K[] to zero. In this case no memory 00106 * will be allocated for the index vectors or coordinate 00107 * array in the tabprm struct. These together with the 00108 * K vector must be set separately before calling 00109 * tabset(). 00110 * 00111 * Given and returned: 00112 * tab struct tabprm* 00113 * Tabular transformation parameters. Note that, in 00114 * order to initialize memory management tabprm::flag 00115 * should be set to -1 when tab is initialized for the 00116 * first time (memory leaks may result if it had already 00117 * been initialized). 00118 * 00119 * Function return value: 00120 * int Status return value: 00121 * 0: Success. 00122 * 1: Null tabprm pointer passed. 00123 * 2: Memory allocation failed. 00124 * 3: Invalid tabular parameters. 00125 * 00126 * For returns > 1, a detailed error message is set in 00127 * tabprm::err if enabled, see wcserr_enable(). 00128 * 00129 * 00130 * tabmem() - Acquire tabular memory 00131 * --------------------------------- 00132 * tabmem() takes control of memory allocated by the user for arrays in the 00133 * tabprm struct. 00134 * 00135 * Given and returned: 00136 * tab struct tabprm* 00137 * Tabular transformation parameters. 00138 * 00139 * Function return value: 00140 * int Status return value: 00141 * 0: Success. 00142 * 1: Null tabprm pointer passed. 00143 * 2: Memory allocation failed. 00144 * 00145 * For returns > 1, a detailed error message is set in 00146 * tabprm::err if enabled, see wcserr_enable(). 00147 * 00148 * 00149 * tabcpy() - Copy routine for the tabprm struct 00150 * --------------------------------------------- 00151 * tabcpy() does a deep copy of one tabprm struct to another, using tabini() to 00152 * allocate memory for its arrays if required. Only the "information to be 00153 * provided" part of the struct is copied; a call to tabset() is required to 00154 * set up the remainder. 00155 * 00156 * Given: 00157 * alloc int If true, allocate memory unconditionally for arrays in 00158 * the tabprm struct. 00159 * 00160 * If false, it is assumed that pointers to these arrays 00161 * have been set by the user except if they are null 00162 * pointers in which case memory will be allocated for 00163 * them regardless. (In other words, setting alloc true 00164 * saves having to initalize these pointers to zero.) 00165 * 00166 * tabsrc const struct tabprm* 00167 * Struct to copy from. 00168 * 00169 * Given and returned: 00170 * tabdst struct tabprm* 00171 * Struct to copy to. tabprm::flag should be set to -1 00172 * if tabdst was not previously initialized (memory leaks 00173 * may result if it was previously initialized). 00174 * 00175 * Function return value: 00176 * int Status return value: 00177 * 0: Success. 00178 * 1: Null tabprm pointer passed. 00179 * 2: Memory allocation failed. 00180 * 00181 * For returns > 1, a detailed error message is set in 00182 * tabprm::err (associated with tabdst) if enabled, see 00183 * wcserr_enable(). 00184 * 00185 * 00186 * tabfree() - Destructor for the tabprm struct 00187 * -------------------------------------------- 00188 * tabfree() frees memory allocated for the tabprm arrays by tabini(). 00189 * tabini() records the memory it allocates and tabfree() will only attempt to 00190 * free this. 00191 * 00192 * PLEASE NOTE: tabfree() must not be invoked on a tabprm struct that was not 00193 * initialized by tabini(). 00194 * 00195 * Returned: 00196 * tab struct tabprm* 00197 * Coordinate transformation parameters. 00198 * 00199 * Function return value: 00200 * int Status return value: 00201 * 0: Success. 00202 * 1: Null tabprm pointer passed. 00203 * 00204 * 00205 * tabprt() - Print routine for the tabprm struct 00206 * ---------------------------------------------- 00207 * tabprt() prints the contents of a tabprm struct using wcsprintf(). Mainly 00208 * intended for diagnostic purposes. 00209 * 00210 * Given: 00211 * tab const struct tabprm* 00212 * Tabular transformation parameters. 00213 * 00214 * Function return value: 00215 * int Status return value: 00216 * 0: Success. 00217 * 1: Null tabprm pointer passed. 00218 * 00219 * 00220 * tabset() - Setup routine for the tabprm struct 00221 * ----------------------------------------------- 00222 * tabset() allocates memory for work arrays in the tabprm struct and sets up 00223 * the struct according to information supplied within it. 00224 * 00225 * Note that this routine need not be called directly; it will be invoked by 00226 * tabx2s() and tabs2x() if tabprm::flag is anything other than a predefined 00227 * magic value. 00228 * 00229 * Given and returned: 00230 * tab struct tabprm* 00231 * Tabular transformation parameters. 00232 * 00233 * Function return value: 00234 * int Status return value: 00235 * 0: Success. 00236 * 1: Null tabprm pointer passed. 00237 * 3: Invalid tabular parameters. 00238 * 00239 * For returns > 1, a detailed error message is set in 00240 * tabprm::err if enabled, see wcserr_enable(). 00241 * 00242 * 00243 * tabx2s() - Pixel-to-world transformation 00244 * ---------------------------------------- 00245 * tabx2s() transforms intermediate world coordinates to world coordinates 00246 * using coordinate lookup. 00247 * 00248 * Given and returned: 00249 * tab struct tabprm* 00250 * Tabular transformation parameters. 00251 * 00252 * Given: 00253 * ncoord, 00254 * nelem int The number of coordinates, each of vector length 00255 * nelem. 00256 * 00257 * x const double[ncoord][nelem] 00258 * Array of intermediate world coordinates, SI units. 00259 * 00260 * Returned: 00261 * world double[ncoord][nelem] 00262 * Array of world coordinates, in SI units. 00263 * 00264 * stat int[ncoord] 00265 * Status return value status for each coordinate: 00266 * 0: Success. 00267 * 1: Invalid intermediate world coordinate. 00268 * 00269 * Function return value: 00270 * int Status return value: 00271 * 0: Success. 00272 * 1: Null tabprm pointer passed. 00273 * 3: Invalid tabular parameters. 00274 * 4: One or more of the x coordinates were invalid, 00275 * as indicated by the stat vector. 00276 * 00277 * For returns > 1, a detailed error message is set in 00278 * tabprm::err if enabled, see wcserr_enable(). 00279 * 00280 * 00281 * tabs2x() - World-to-pixel transformation 00282 * ---------------------------------------- 00283 * tabs2x() transforms world coordinates to intermediate world coordinates. 00284 * 00285 * Given and returned: 00286 * tab struct tabprm* 00287 * Tabular transformation parameters. 00288 * 00289 * Given: 00290 * ncoord, 00291 * nelem int The number of coordinates, each of vector length 00292 * nelem. 00293 * world const double[ncoord][nelem] 00294 * Array of world coordinates, in SI units. 00295 * 00296 * Returned: 00297 * x double[ncoord][nelem] 00298 * Array of intermediate world coordinates, SI units. 00299 * stat int[ncoord] 00300 * Status return value status for each vector element: 00301 * 0: Success. 00302 * 1: Invalid world coordinate. 00303 * 00304 * Function return value: 00305 * int Status return value: 00306 * 0: Success. 00307 * 1: Null tabprm pointer passed. 00308 * 3: Invalid tabular parameters. 00309 * 5: One or more of the world coordinates were 00310 * invalid, as indicated by the stat vector. 00311 * 00312 * For returns > 1, a detailed error message is set in 00313 * tabprm::err if enabled, see wcserr_enable(). 00314 * 00315 * 00316 * tabprm struct - Tabular transformation parameters 00317 * ------------------------------------------------- 00318 * The tabprm struct contains information required to transform tabular 00319 * coordinates. It consists of certain members that must be set by the user 00320 * ("given") and others that are set by the WCSLIB routines ("returned"). Some 00321 * of the latter are supplied for informational purposes while others are for 00322 * internal use only. 00323 * 00324 * int flag 00325 * (Given and returned) This flag must be set to zero whenever any of the 00326 * following tabprm structure members are set or changed: 00327 * 00328 * - tabprm::M (q.v., not normally set by the user), 00329 * - tabprm::K (q.v., not normally set by the user), 00330 * - tabprm::map, 00331 * - tabprm::crval, 00332 * - tabprm::index, 00333 * - tabprm::coord. 00334 * 00335 * This signals the initialization routine, tabset(), to recompute the 00336 * returned members of the tabprm struct. tabset() will reset flag to 00337 * indicate that this has been done. 00338 * 00339 * PLEASE NOTE: flag should be set to -1 when tabini() is called for the 00340 * first time for a particular tabprm struct in order to initialize memory 00341 * management. It must ONLY be used on the first initialization otherwise 00342 * memory leaks may result. 00343 * 00344 * int M 00345 * (Given or returned) Number of tabular coordinate axes. 00346 * 00347 * If tabini() is used to initialize the linprm struct (as would normally 00348 * be the case) then it will set M from the value passed to it as a 00349 * function argument. The user should not subsequently modify it. 00350 * 00351 * int *K 00352 * (Given or returned) Pointer to the first element of a vector of length 00353 * tabprm::M whose elements (K_1, K_2,... K_M) record the lengths of the 00354 * axes of the coordinate array and of each indexing vector. 00355 * 00356 * If tabini() is used to initialize the linprm struct (as would normally 00357 * be the case) then it will set K from the array passed to it as a 00358 * function argument. The user should not subsequently modify it. 00359 * 00360 * int *map 00361 * (Given) Pointer to the first element of a vector of length tabprm::M 00362 * that defines the association between axis m in the M-dimensional 00363 * coordinate array (1 <= m <= M) and the indices of the intermediate world 00364 * coordinate and world coordinate arrays, x[] and world[], in the argument 00365 * lists for tabx2s() and tabs2x(). 00366 * 00367 * When x[] and world[] contain the full complement of coordinate elements 00368 * in image-order, as will usually be the case, then map[m-1] == i-1 for 00369 * axis i in the N-dimensional image (1 <= i <= N). In terms of the FITS 00370 * keywords 00371 * 00372 * map[PVi_3a - 1] == i - 1. 00373 * 00374 * However, a different association may result if x[], for example, only 00375 * contains a (relevant) subset of intermediate world coordinate elements. 00376 * For example, if M == 1 for an image with N > 1, it is possible to fill 00377 * x[] with the relevant coordinate element with nelem set to 1. In this 00378 * case map[0] = 0 regardless of the value of i. 00379 * 00380 * double *crval 00381 * (Given) Pointer to the first element of a vector of length tabprm::M 00382 * whose elements contain the index value for the reference pixel for each 00383 * of the tabular coordinate axes. 00384 * 00385 * double **index 00386 * (Given) Pointer to the first element of a vector of length tabprm::M of 00387 * pointers to vectors of lengths (K_1, K_2,... K_M) of 0-relative indexes 00388 * (see tabprm::K). 00389 * 00390 * The address of any or all of these index vectors may be set to zero, 00391 * i.e. 00392 * 00393 = index[m] == 0; 00394 * 00395 * this is interpreted as default indexing, i.e. 00396 * 00397 = index[m][k] = k; 00398 * 00399 * double *coord 00400 * (Given) Pointer to the first element of the tabular coordinate array, 00401 * treated as though it were defined as 00402 * 00403 = double coord[K_M]...[K_2][K_1][M]; 00404 * 00405 * (see tabprm::K) i.e. with the M dimension varying fastest so that the 00406 * M elements of a coordinate vector are stored contiguously in memory. 00407 * 00408 * int nc 00409 * (Returned) Total number of coordinate vectors in the coordinate array 00410 * being the product K_1 * K_2 * ... * K_M (see tabprm::K). 00411 * 00412 * int padding 00413 * (An unused variable inserted for alignment purposes only.) 00414 * 00415 * int *sense 00416 * (Returned) Pointer to the first element of a vector of length tabprm::M 00417 * whose elements indicate whether the corresponding indexing vector is 00418 * monotonic increasing (+1), or decreasing (-1). 00419 * 00420 * int *p0 00421 * (Returned) Pointer to the first element of a vector of length tabprm::M 00422 * of interpolated indices into the coordinate array such that Upsilon_m, 00423 * as defined in Paper III, is equal to (p0[m] + 1) + tabprm::delta[m]. 00424 * 00425 * double *delta 00426 * (Returned) Pointer to the first element of a vector of length tabprm::M 00427 * of interpolated indices into the coordinate array such that Upsilon_m, 00428 * as defined in Paper III, is equal to (tabprm::p0[m] + 1) + delta[m]. 00429 * 00430 * double *extrema 00431 * (Returned) Pointer to the first element of an array that records the 00432 * minimum and maximum value of each element of the coordinate vector in 00433 * each row of the coordinate array, treated as though it were defined as 00434 * 00435 = double extrema[K_M]...[K_2][2][M] 00436 * 00437 * (see tabprm::K). The minimum is recorded in the first element of the 00438 * compressed K_1 dimension, then the maximum. This array is used by the 00439 * inverse table lookup function, tabs2x(), to speed up table searches. 00440 * 00441 * struct wcserr *err 00442 * (Returned) If enabled, when an error status is returned this struct 00443 * contains detailed information about the error, see wcserr_enable(). 00444 * 00445 * int m_flag 00446 * (For internal use only.) 00447 * int m_M 00448 * (For internal use only.) 00449 * int m_N 00450 * (For internal use only.) 00451 * int set_M 00452 * (For internal use only.) 00453 * int m_K 00454 * (For internal use only.) 00455 * int m_map 00456 * (For internal use only.) 00457 * int m_crval 00458 * (For internal use only.) 00459 * int m_index 00460 * (For internal use only.) 00461 * int m_indxs 00462 * (For internal use only.) 00463 * int m_coord 00464 * (For internal use only.) 00465 * 00466 * 00467 * Global variable: const char *tab_errmsg[] - Status return messages 00468 * ------------------------------------------------------------------ 00469 * Error messages to match the status value returned from each function. 00470 * 00471 *===========================================================================*/ 00472 00473 #ifndef WCSLIB_TAB 00474 #define WCSLIB_TAB 00475 00476 #include "wcserr.h" 00477 00478 #ifdef __cplusplus 00479 extern "C" { 00480 #endif 00481 00482 00483 extern const char *tab_errmsg[]; 00484 00485 enum tab_errmsg_enum { 00486 TABERR_SUCCESS = 0, /* Success. */ 00487 TABERR_NULL_POINTER = 1, /* Null tabprm pointer passed. */ 00488 TABERR_MEMORY = 2, /* Memory allocation failed. */ 00489 TABERR_BAD_PARAMS = 3, /* Invalid tabular parameters. */ 00490 TABERR_BAD_X = 4, /* One or more of the x coordinates were 00491 invalid. */ 00492 TABERR_BAD_WORLD = 5 /* One or more of the world coordinates were 00493 invalid. */ 00494 }; 00495 00496 struct tabprm { 00497 /* Initialization flag (see the prologue above). */ 00498 /*------------------------------------------------------------------------*/ 00499 int flag; /* Set to zero to force initialization. */ 00500 00501 /* Parameters to be provided (see the prologue above). */ 00502 /*------------------------------------------------------------------------*/ 00503 int M; /* Number of tabular coordinate axes. */ 00504 int *K; /* Vector of length M whose elements */ 00505 /* (K_1, K_2,... K_M) record the lengths of */ 00506 /* the axes of the coordinate array and of */ 00507 /* each indexing vector. */ 00508 int *map; /* Vector of length M usually such that */ 00509 /* map[m-1] == i-1 for coordinate array */ 00510 /* axis m and image axis i (see above). */ 00511 double *crval; /* Vector of length M containing the index */ 00512 /* value for the reference pixel for each */ 00513 /* of the tabular coordinate axes. */ 00514 double **index; /* Vector of pointers to M indexing vectors */ 00515 /* of lengths (K_1, K_2,... K_M). */ 00516 double *coord; /* (1+M)-dimensional tabular coordinate */ 00517 /* array (see above). */ 00518 00519 /* Information derived from the parameters supplied. */ 00520 /*------------------------------------------------------------------------*/ 00521 int nc; /* Number of coordinate vectors (of length */ 00522 /* M) in the coordinate array. */ 00523 int padding; /* (Dummy inserted for alignment purposes.) */ 00524 int *sense; /* Vector of M flags that indicate whether */ 00525 /* the Mth indexing vector is monotonic */ 00526 /* increasing, or else decreasing. */ 00527 int *p0; /* Vector of M indices. */ 00528 double *delta; /* Vector of M increments. */ 00529 double *extrema; /* (1+M)-dimensional array of coordinate */ 00530 /* extrema. */ 00531 00532 /* Error handling */ 00533 /*------------------------------------------------------------------------*/ 00534 struct wcserr *err; 00535 00536 /* Private - the remainder are for memory management. */ 00537 /*------------------------------------------------------------------------*/ 00538 int m_flag, m_M, m_N; 00539 int set_M; 00540 int *m_K, *m_map; 00541 double *m_crval, **m_index, **m_indxs, *m_coord; 00542 }; 00543 00544 /* Size of the tabprm struct in int units, used by the Fortran wrappers. */ 00545 #define TABLEN (sizeof(struct tabprm)/sizeof(int)) 00546 00547 00548 int tabini(int alloc, int M, const int K[], struct tabprm *tab); 00549 00550 int tabmem(struct tabprm *tab); 00551 00552 int tabcpy(int alloc, const struct tabprm *tabsrc, struct tabprm *tabdst); 00553 00554 int tabfree(struct tabprm *tab); 00555 00556 int tabprt(const struct tabprm *tab); 00557 00558 int tabset(struct tabprm *tab); 00559 00560 int tabx2s(struct tabprm *tab, int ncoord, int nelem, const double x[], 00561 double world[], int stat[]); 00562 00563 int tabs2x(struct tabprm *tab, int ncoord, int nelem, const double world[], 00564 double x[], int stat[]); 00565 00566 00567 /* Deprecated. */ 00568 #define tabini_errmsg tab_errmsg 00569 #define tabcpy_errmsg tab_errmsg 00570 #define tabfree_errmsg tab_errmsg 00571 #define tabprt_errmsg tab_errmsg 00572 #define tabset_errmsg tab_errmsg 00573 #define tabx2s_errmsg tab_errmsg 00574 #define tabs2x_errmsg tab_errmsg 00575 00576 #ifdef __cplusplus 00577 } 00578 #endif 00579 00580 #endif /* WCSLIB_TAB */