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: spc.h,v 4.8.1.1 2011/08/15 08:07:06 cal103 Exp cal103 $ 00032 *============================================================================= 00033 * 00034 * WCSLIB 4.8 - C routines that implement the spectral coordinate systems 00035 * recognized by the FITS World Coordinate System (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 spectral coordinates in FITS", 00041 * Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L. 00042 * 2006, A&A, 446, 747 (Paper III) 00043 * 00044 * Refer to the README file provided with WCSLIB for an overview of the 00045 * library. 00046 * 00047 * 00048 * Summary of the spc routines 00049 * --------------------------- 00050 * These routines implement the part of the FITS WCS standard that deals with 00051 * spectral coordinates. They define methods to be used for computing spectral 00052 * world coordinates from intermediate world coordinates (a linear 00053 * transformation of image pixel coordinates), and vice versa. They are based 00054 * on the spcprm struct which contains all information needed for the 00055 * computations. The struct contains some members that must be set by the 00056 * user, and others that are maintained by these routines, somewhat like a 00057 * C++ class but with no encapsulation. 00058 * 00059 * Routine spcini() is provided to initialize the spcprm struct with default 00060 * values, spcfree() reclaims any memory that may have been allocated to store 00061 * an error message, and spcprt() prints its contents. 00062 * 00063 * A setup routine, spcset(), computes intermediate values in the spcprm struct 00064 * from parameters in it that were supplied by the user. The struct always 00065 * needs to be set up by spcset() but it need not be called explicitly - refer 00066 * to the explanation of spcprm::flag. 00067 * 00068 * spcx2s() and spcs2x() implement the WCS spectral coordinate transformations. 00069 * In fact, they are high level driver routines for the lower level spectral 00070 * coordinate transformation routines described in spx.h. 00071 * 00072 * A number of routines are provided to aid in analysing or synthesising sets 00073 * of FITS spectral axis keywords: 00074 * 00075 * - spctype() checks a spectral CTYPEia keyword for validity and returns 00076 * information derived from it. 00077 * 00078 * - Spectral keyword analysis routine spcspxe() computes the values of the 00079 * X-type spectral variables for the S-type variables supplied. 00080 * 00081 * - Spectral keyword synthesis routine, spcxpse(), computes the S-type 00082 * variables for the X-types supplied. 00083 * 00084 * - Given a set of spectral keywords, a translation routine, spctrne(), 00085 * produces the corresponding set for the specified spectral CTYPEia. 00086 * 00087 * - spcaips() translates AIPS-convention spectral keywords, CTYPEn and 00088 * VELREF, into CTYPEia and SPECSYSa. 00089 * 00090 * Spectral variable types - S, P, and X: 00091 * -------------------------------------- 00092 * A few words of explanation are necessary regarding spectral variable types 00093 * in FITS. 00094 * 00095 * Every FITS spectral axis has three associated spectral variables: 00096 * 00097 * S-type: the spectral variable in which coordinates are to be 00098 * expressed. Each S-type is encoded as four characters and is 00099 * linearly related to one of four basic types as follows: 00100 * 00101 * F: frequency 00102 * 'FREQ': frequency 00103 * 'AFRQ': angular frequency 00104 * 'ENER': photon energy 00105 * 'WAVN': wave number 00106 * 'VRAD': radio velocity 00107 * 00108 * W: wavelength in vacuo 00109 * 'WAVE': wavelength 00110 * 'VOPT': optical velocity 00111 * 'ZOPT': redshift 00112 * 00113 * A: wavelength in air 00114 * 'AWAV': wavelength in air 00115 * 00116 * V: velocity 00117 * 'VELO': relativistic velocity 00118 * 'BETA': relativistic beta factor 00119 * 00120 * The S-type forms the first four characters of the CTYPEia keyvalue, 00121 * and CRVALia and CDELTia are expressed as S-type quantities so that 00122 * they provide a first-order approximation to the S-type variable at 00123 * the reference point. 00124 * 00125 * Note that 'AFRQ', angular frequency, is additional to the variables 00126 * defined in WCS Paper III. 00127 * 00128 * P-type: the basic spectral variable (F, W, A, or V) with which the 00129 * S-type variable is associated (see list above). 00130 * 00131 * For non-grism axes, the P-type is encoded as the eighth character of 00132 * CTYPEia. 00133 * 00134 * X-type: the basic spectral variable (F, W, A, or V) for which the 00135 * spectral axis is linear, grisms excluded (see below). 00136 * 00137 * For non-grism axes, the X-type is encoded as the sixth character of 00138 * CTYPEia. 00139 * 00140 * Grisms: Grism axes have normal S-, and P-types but the axis is linear, 00141 * not in any spectral variable, but in a special "grism parameter". 00142 * The X-type spectral variable is either W or A for grisms in vacuo or 00143 * air respectively, but is encoded as 'w' or 'a' to indicate that an 00144 * additional transformation is required to convert to or from the 00145 * grism parameter. The spectral algorithm code for grisms also has a 00146 * special encoding in CTYPEia, either 'GRI' (in vacuo) or 'GRA' (in air). 00147 * 00148 * In the algorithm chain, the non-linear transformation occurs between the 00149 * X-type and the P-type variables; the transformation between P-type and 00150 * S-type variables is always linear. 00151 * 00152 * When the P-type and X-type variables are the same, the spectral axis is 00153 * linear in the S-type variable and the second four characters of CTYPEia 00154 * are blank. This can never happen for grism axes. 00155 * 00156 * As an example, correlating radio spectrometers always produce spectra that 00157 * are regularly gridded in frequency; a redshift scale on such a spectrum is 00158 * non-linear. The required value of CTYPEia would be 'ZOPT-F2W', where the 00159 * desired S-type is 'ZOPT' (redshift), the P-type is necessarily 'W' 00160 * (wavelength), and the X-type is 'F' (frequency) by the nature of the 00161 * instrument. 00162 * 00163 * Argument checking: 00164 * ------------------ 00165 * The input spectral values are only checked for values that would result in 00166 * floating point exceptions. In particular, negative frequencies and 00167 * wavelengths are allowed, as are velocities greater than the speed of 00168 * light. The same is true for the spectral parameters - rest frequency and 00169 * wavelength. 00170 * 00171 * Accuracy: 00172 * --------- 00173 * No warranty is given for the accuracy of these routines (refer to the 00174 * copyright notice); intending users must satisfy for themselves their 00175 * adequacy for the intended purpose. However, closure effectively to within 00176 * double precision rounding error was demonstrated by test routine tspc.c 00177 * which accompanies this software. 00178 * 00179 * 00180 * spcini() - Default constructor for the spcprm struct 00181 * ---------------------------------------------------- 00182 * spcini() sets all members of a spcprm struct to default values. It should 00183 * be used to initialize every spcprm struct. 00184 * 00185 * Given and returned: 00186 * spc struct spcprm* 00187 * Spectral transformation parameters. 00188 * 00189 * Function return value: 00190 * int Status return value: 00191 * 0: Success. 00192 * 1: Null spcprm pointer passed. 00193 * 00194 * 00195 * spcfree() - Destructor for the spcprm struct 00196 * -------------------------------------------- 00197 * spcfree() frees any memory that may have been allocated to store an error 00198 * message in the spcprm struct. 00199 * 00200 * Given: 00201 * spc struct spcprm* 00202 * Spectral transformation parameters. 00203 * 00204 * Function return value: 00205 * int Status return value: 00206 * 0: Success. 00207 * 1: Null spcprm pointer passed. 00208 * 00209 * 00210 * spcprt() - Print routine for the spcprm struct 00211 * ---------------------------------------------- 00212 * spcprt() prints the contents of a spcprm struct using wcsprintf(). Mainly 00213 * intended for diagnostic purposes. 00214 * 00215 * Given: 00216 * spc const struct spcprm* 00217 * Spectral transformation parameters. 00218 * 00219 * Function return value: 00220 * int Status return value: 00221 * 0: Success. 00222 * 1: Null spcprm pointer passed. 00223 * 00224 * 00225 * spcset() - Setup routine for the spcprm struct 00226 * ---------------------------------------------- 00227 * spcset() sets up a spcprm struct according to information supplied within 00228 * it. 00229 * 00230 * Note that this routine need not be called directly; it will be invoked by 00231 * spcx2s() and spcs2x() if spcprm::flag is anything other than a predefined 00232 * magic value. 00233 * 00234 * Given and returned: 00235 * spc struct spcprm* 00236 * Spectral transformation parameters. 00237 * 00238 * Function return value: 00239 * int Status return value: 00240 * 0: Success. 00241 * 1: Null spcprm pointer passed. 00242 * 2: Invalid spectral parameters. 00243 * 00244 * For returns > 1, a detailed error message is set in 00245 * spcprm::err if enabled, see wcserr_enable(). 00246 * 00247 * 00248 * spcx2s() - Transform to spectral coordinates 00249 * -------------------------------------------- 00250 * spcx2s() transforms intermediate world coordinates to spectral coordinates. 00251 * 00252 * Given and returned: 00253 * spc struct spcprm* 00254 * Spectral transformation parameters. 00255 * 00256 * Given: 00257 * nx int Vector length. 00258 * 00259 * sx int Vector stride. 00260 * 00261 * sspec int Vector stride. 00262 * 00263 * x const double[] 00264 * Intermediate world coordinates, in SI units. 00265 * 00266 * Returned: 00267 * spec double[] Spectral coordinates, in SI units. 00268 * 00269 * stat int[] Status return value status for each vector element: 00270 * 0: Success. 00271 * 1: Invalid value of x. 00272 * 00273 * Function return value: 00274 * int Status return value: 00275 * 0: Success. 00276 * 1: Null spcprm pointer passed. 00277 * 2: Invalid spectral parameters. 00278 * 3: One or more of the x coordinates were invalid, 00279 * as indicated by the stat vector. 00280 * 00281 * For returns > 1, a detailed error message is set in 00282 * spcprm::err if enabled, see wcserr_enable(). 00283 * 00284 * 00285 * spcs2x() - Transform spectral coordinates 00286 * ----------------------------------------- 00287 * spcs2x() transforms spectral world coordinates to intermediate world 00288 * coordinates. 00289 * 00290 * Given and returned: 00291 * spc struct spcprm* 00292 * Spectral transformation parameters. 00293 * 00294 * Given: 00295 * nspec int Vector length. 00296 * 00297 * sspec int Vector stride. 00298 * 00299 * sx int Vector stride. 00300 * 00301 * spec const double[] 00302 * Spectral coordinates, in SI units. 00303 * 00304 * Returned: 00305 * x double[] Intermediate world coordinates, in SI units. 00306 * 00307 * stat int[] Status return value status for each vector element: 00308 * 0: Success. 00309 * 1: Invalid value of spec. 00310 * 00311 * Function return value: 00312 * int Status return value: 00313 * 0: Success. 00314 * 1: Null spcprm pointer passed. 00315 * 2: Invalid spectral parameters. 00316 * 4: One or more of the spec coordinates were 00317 * invalid, as indicated by the stat vector. 00318 * 00319 * For returns > 1, a detailed error message is set in 00320 * spcprm::err if enabled, see wcserr_enable(). 00321 * 00322 * 00323 * spctype() - Spectral CTYPEia keyword analysis 00324 * --------------------------------------------- 00325 * spctype() checks whether a CTYPEia keyvalue is a valid spectral axis type 00326 * and if so returns information derived from it relating to the associated S-, 00327 * P-, and X-type spectral variables (see explanation above). 00328 * 00329 * The return arguments are guaranteed not be modified if CTYPEia is not a 00330 * valid spectral type; zero-pointers may be specified for any that are not of 00331 * interest. 00332 * 00333 * A deprecated form of this function, spctyp(), lacks the wcserr** parameter. 00334 * 00335 * Given: 00336 * ctype const char[9] 00337 * The CTYPEia keyvalue, (eight characters with null 00338 * termination). 00339 * 00340 * Returned: 00341 * stype char[] The four-letter name of the S-type spectral variable 00342 * copied or translated from ctype. If a non-zero 00343 * pointer is given, the array must accomodate a null- 00344 * terminated string of length 5. 00345 * 00346 * scode char[] The three-letter spectral algorithm code copied or 00347 * translated from ctype. Logarithmic ('LOG') and 00348 * tabular ('TAB') codes are also recognized. If a 00349 * non-zero pointer is given, the array must accomodate a 00350 * null-terminated string of length 4. 00351 * 00352 * sname char[] Descriptive name of the S-type spectral variable. 00353 * If a non-zero pointer is given, the array must 00354 * accomodate a null-terminated string of length 22. 00355 * 00356 * units char[] SI units of the S-type spectral variable. If a 00357 * non-zero pointer is given, the array must accomodate a 00358 * null-terminated string of length 8. 00359 * 00360 * ptype char* Character code for the P-type spectral variable 00361 * derived from ctype, one of 'F', 'W', 'A', or 'V'. 00362 * 00363 * xtype char* Character code for the X-type spectral variable 00364 * derived from ctype, one of 'F', 'W', 'A', or 'V'. 00365 * Also, 'w' and 'a' are synonymous to 'W' and 'A' for 00366 * grisms in vacuo and air respectively. Set to 'L' or 00367 * 'T' for logarithmic ('LOG') and tabular ('TAB') axes. 00368 * 00369 * restreq int* Multivalued flag that indicates whether rest 00370 * frequency or wavelength is required to compute 00371 * spectral variables for this CTYPEia: 00372 * 0: Not required. 00373 * 1: Required for the conversion between S- and 00374 * P-types (e.g. 'ZOPT-F2W'). 00375 * 2: Required for the conversion between P- and 00376 * X-types (e.g. 'BETA-W2V'). 00377 * 3: Required for the conversion between S- and 00378 * P-types, and between P- and X-types, but not 00379 * between S- and X-types (this applies only for 00380 * 'VRAD-V2F', 'VOPT-V2W', and 'ZOPT-V2W'). 00381 * Thus the rest frequency or wavelength is required for 00382 * spectral coordinate computations (i.e. between S- and 00383 * X-types) only if restreq%3 != 0. 00384 * 00385 * err struct wcserr ** 00386 * For function return values > 1, this struct will 00387 * contain a detailed error message. May be NULL if an 00388 * error message is not desired. 00389 * 00390 * Function return value: 00391 * int Status return value: 00392 * 0: Success. 00393 * 2: Invalid spectral parameters (not a spectral 00394 * CTYPEia). 00395 * 00396 * 00397 * spcspxe() - Spectral keyword analysis 00398 * ------------------------------------ 00399 * spcspxe() analyses the CTYPEia and CRVALia FITS spectral axis keyword values 00400 * and returns information about the associated X-type spectral variable. 00401 * 00402 * A deprecated form of this function, spcspx(), lacks the wcserr** parameter. 00403 * 00404 * Given: 00405 * ctypeS const char[9] 00406 * Spectral axis type, i.e. the CTYPEia keyvalue, (eight 00407 * characters with null termination). For non-grism 00408 * axes, the character code for the P-type spectral 00409 * variable in the algorithm code (i.e. the eighth 00410 * character of CTYPEia) may be set to '?' (it will not 00411 * be reset). 00412 * 00413 * crvalS double Value of the S-type spectral variable at the reference 00414 * point, i.e. the CRVALia keyvalue, SI units. 00415 * 00416 * restfrq, 00417 * restwav double Rest frequency [Hz] and rest wavelength in vacuo [m], 00418 * only one of which need be given, the other should be 00419 * set to zero. Neither are required if the translation 00420 * is between wave-characteristic types, or between 00421 * velocity-characteristic types. E.g., required for 00422 * 'FREQ' -> 'ZOPT-F2W', but not required for 00423 * 'VELO-F2V' -> 'ZOPT-F2W'. 00424 * 00425 * Returned: 00426 * ptype char* Character code for the P-type spectral variable 00427 * derived from ctypeS, one of 'F', 'W', 'A', or 'V'. 00428 * 00429 * xtype char* Character code for the X-type spectral variable 00430 * derived from ctypeS, one of 'F', 'W', 'A', or 'V'. 00431 * Also, 'w' and 'a' are synonymous to 'W' and 'A' for 00432 * grisms in vacuo and air respectively; crvalX and dXdS 00433 * (see below) will conform to these. 00434 * 00435 * restreq int* Multivalued flag that indicates whether rest frequency 00436 * or wavelength is required to compute spectral 00437 * variables for this CTYPEia, as for spctype(). 00438 * 00439 * crvalX double* Value of the X-type spectral variable at the reference 00440 * point, SI units. 00441 * 00442 * dXdS double* The derivative, dX/dS, evaluated at the reference 00443 * point, SI units. Multiply the CDELTia keyvalue by 00444 * this to get the pixel spacing in the X-type spectral 00445 * coordinate. 00446 * 00447 * err struct wcserr ** 00448 * For function return values > 1, this struct will 00449 * contain a detailed error message. May be NULL if an 00450 * error message is not desired. 00451 * 00452 * Function return value: 00453 * int Status return value: 00454 * 0: Success. 00455 * 2: Invalid spectral parameters. 00456 * 00457 * 00458 * spcxpse() - Spectral keyword synthesis 00459 * ------------------------------------- 00460 * spcxpse(), for the spectral axis type specified and the value provided for 00461 * the X-type spectral variable at the reference point, deduces the value of 00462 * the FITS spectral axis keyword CRVALia and also the derivative dS/dX which 00463 * may be used to compute CDELTia. See above for an explanation of the S-, 00464 * P-, and X-type spectral variables. 00465 * 00466 * A deprecated form of this function, spcxps(), lacks the wcserr** parameter. 00467 * 00468 * Given: 00469 * ctypeS const char[9] 00470 * The required spectral axis type, i.e. the CTYPEia 00471 * keyvalue, (eight characters with null termination). 00472 * For non-grism axes, the character code for the P-type 00473 * spectral variable in the algorithm code (i.e. the 00474 * eighth character of CTYPEia) may be set to '?' (it 00475 * will not be reset). 00476 * 00477 * crvalX double Value of the X-type spectral variable at the reference 00478 * point (N.B. NOT the CRVALia keyvalue), SI units. 00479 * 00480 * restfrq, 00481 * restwav double Rest frequency [Hz] and rest wavelength in vacuo [m], 00482 * only one of which need be given, the other should be 00483 * set to zero. Neither are required if the translation 00484 * is between wave-characteristic types, or between 00485 * velocity-characteristic types. E.g., required for 00486 * 'FREQ' -> 'ZOPT-F2W', but not required for 00487 * 'VELO-F2V' -> 'ZOPT-F2W'. 00488 * 00489 * Returned: 00490 * ptype char* Character code for the P-type spectral variable 00491 * derived from ctypeS, one of 'F', 'W', 'A', or 'V'. 00492 * 00493 * xtype char* Character code for the X-type spectral variable 00494 * derived from ctypeS, one of 'F', 'W', 'A', or 'V'. 00495 * Also, 'w' and 'a' are synonymous to 'W' and 'A' for 00496 * grisms; crvalX and cdeltX must conform to these. 00497 * 00498 * restreq int* Multivalued flag that indicates whether rest frequency 00499 * or wavelength is required to compute spectral 00500 * variables for this CTYPEia, as for spctype(). 00501 * 00502 * crvalS double* Value of the S-type spectral variable at the reference 00503 * point (i.e. the appropriate CRVALia keyvalue), SI 00504 * units. 00505 * 00506 * dSdX double* The derivative, dS/dX, evaluated at the reference 00507 * point, SI units. Multiply this by the pixel spacing 00508 * in the X-type spectral coordinate to get the CDELTia 00509 * keyvalue. 00510 * 00511 * err struct wcserr ** 00512 * For function return values > 1, this struct will 00513 * contain a detailed error message. May be NULL if an 00514 * error message is not desired. 00515 * 00516 * Function return value: 00517 * int Status return value: 00518 * 0: Success. 00519 * 2: Invalid spectral parameters. 00520 * 00521 * 00522 * spctrne() - Spectral keyword translation 00523 * --------------------------------------- 00524 * spctrne() translates a set of FITS spectral axis keywords into the 00525 * corresponding set for the specified spectral axis type. For example, a 00526 * 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa. 00527 * 00528 * A deprecated form of this function, spctrn(), lacks the wcserr** parameter. 00529 * 00530 * Given: 00531 * ctypeS1 const char[9] 00532 * Spectral axis type, i.e. the CTYPEia keyvalue, (eight 00533 * characters with null termination). For non-grism 00534 * axes, the character code for the P-type spectral 00535 * variable in the algorithm code (i.e. the eighth 00536 * character of CTYPEia) may be set to '?' (it will not 00537 * be reset). 00538 * 00539 * crvalS1 double Value of the S-type spectral variable at the reference 00540 * point, i.e. the CRVALia keyvalue, SI units. 00541 * 00542 * cdeltS1 double Increment of the S-type spectral variable at the 00543 * reference point, SI units. 00544 * 00545 * restfrq, 00546 * restwav double Rest frequency [Hz] and rest wavelength in vacuo [m], 00547 * only one of which need be given, the other should be 00548 * set to zero. Neither are required if the translation 00549 * is between wave-characteristic types, or between 00550 * velocity-characteristic types. E.g., required for 00551 * 'FREQ' -> 'ZOPT-F2W', but not required for 00552 * 'VELO-F2V' -> 'ZOPT-F2W'. 00553 * 00554 * Given and returned: 00555 * ctypeS2 char[9] Required spectral axis type (eight characters with 00556 * null termination). The first four characters are 00557 * required to be given and are never modified. The 00558 * remaining four, the algorithm code, are completely 00559 * determined by, and must be consistent with, ctypeS1 00560 * and the first four characters of ctypeS2. A non-zero 00561 * status value will be returned if they are inconsistent 00562 * (see below). However, if the final three characters 00563 * are specified as "???", or if just the eighth 00564 * character is specified as '?', the correct algorithm 00565 * code will be substituted (applies for grism axes as 00566 * well as non-grism). 00567 * 00568 * Returned: 00569 * crvalS2 double* Value of the new S-type spectral variable at the 00570 * reference point, i.e. the new CRVALia keyvalue, SI 00571 * units. 00572 * 00573 * cdeltS2 double* Increment of the new S-type spectral variable at the 00574 * reference point, i.e. the new CDELTia keyvalue, SI 00575 * units. 00576 * 00577 * err struct wcserr ** 00578 * For function return values > 1, this struct will 00579 * contain a detailed error message. May be NULL if an 00580 * error message is not desired. 00581 * 00582 * Function return value: 00583 * int Status return value: 00584 * 0: Success. 00585 * 2: Invalid spectral parameters. 00586 * 00587 * A status value of 2 will be returned if restfrq or 00588 * restwav are not specified when required, or if ctypeS1 00589 * or ctypeS2 are self-inconsistent, or have different 00590 * spectral X-type variables. 00591 * 00592 * 00593 * spcaips() - Translate AIPS-convention spectral keywords 00594 * ------------------------------------------------------- 00595 * spcaips() translates AIPS-convention spectral keywords, CTYPEn and VELREF, 00596 * into CTYPEia and SPECSYSa. 00597 * 00598 * Given: 00599 * ctypeA const char[9] 00600 * CTYPEia keyvalue (eight characters, need not be null- 00601 * terminated). 00602 * 00603 * velref int AIPS-convention VELREF code. It has the following 00604 * integer values: 00605 * 1: LSR kinematic, originally described simply as 00606 * "LSR" without distinction between the kinematic 00607 * and dynamic definitions. 00608 * 2: Barycentric, originally described as "HEL" 00609 * meaning heliocentric. 00610 * 3: Topocentric, originally described as "OBS" 00611 * meaning geocentric but widely interpreted as 00612 * topocentric. 00613 * AIPS++ extensions to VELREF are also recognized: 00614 * 4: LSR dynamic. 00615 * 5: Geocentric. 00616 * 6: Source rest frame. 00617 * 7: Galactocentric. 00618 * For an AIPS 'VELO' axis, a radio convention velocity 00619 * is denoted by adding 256 to VELREF, otherwise an 00620 * optical velocity is indicated (not applicable to 00621 * 'FELO' axes). Unrecognized values of VELREF are 00622 * simply ignored. 00623 * 00624 * VELREF takes precedence over CTYPEia in defining the 00625 * Doppler frame, e.g. if 00626 * 00627 = CTYPEn = 'VELO-HEL' 00628 = VELREF = 1 00629 * 00630 * the Doppler frame is set to LSRK. 00631 * 00632 * Returned: 00633 * ctype char[9] Translated CTYPEia keyvalue, or a copy of ctypeA if no 00634 * translation was performed (null-filled). 00635 * 00636 * specsys char[9] Doppler reference frame indicated by VELREF or else by 00637 * CTYPEn. 00638 * 00639 * Function return value: 00640 * int Status return value: 00641 * -1: No translation required (not an error). 00642 * 0: Success. 00643 * 00644 * 00645 * spcprm struct - Spectral transformation parameters 00646 * -------------------------------------------------- 00647 * The spcprm struct contains information required to transform spectral 00648 * coordinates. It consists of certain members that must be set by the user 00649 * ("given") and others that are set by the WCSLIB routines ("returned"). Some 00650 * of the latter are supplied for informational purposes while others are for 00651 * internal use only. 00652 * 00653 * int flag 00654 * (Given and returned) This flag must be set to zero whenever any of the 00655 * following spcprm structure members are set or changed: 00656 * 00657 * - spcprm::type, 00658 * - spcprm::code, 00659 * - spcprm::crval, 00660 * - spcprm::restfrq, 00661 * - spcprm::restwav, 00662 * - spcprm::pv[]. 00663 * 00664 * This signals the initialization routine, spcset(), to recompute the 00665 * returned members of the spcprm struct. spcset() will reset flag to 00666 * indicate that this has been done. 00667 * 00668 * char type[8] 00669 * (Given) Four-letter spectral variable type, e.g "ZOPT" for 00670 * CTYPEia = 'ZOPT-F2W'. (Declared as char[8] for alignment reasons.) 00671 * 00672 * char code[4] 00673 * (Given) Three-letter spectral algorithm code, e.g "F2W" for 00674 * CTYPEia = 'ZOPT-F2W'. 00675 * 00676 * double crval 00677 * (Given) Reference value (CRVALia), SI units. 00678 * 00679 * double restfrq 00680 * (Given) The rest frequency [Hz], and ... 00681 * 00682 * double restwav 00683 * (Given) ... the rest wavelength in vacuo [m], only one of which need be 00684 * given, the other should be set to zero. Neither are required if the 00685 * X and S spectral variables are both wave-characteristic, or both 00686 * velocity-characteristic, types. 00687 * 00688 * double pv[7] 00689 * (Given) Grism parameters for 'GRI' and 'GRA' algorithm codes: 00690 * - 0: G, grating ruling density. 00691 * - 1: m, interference order. 00692 * - 2: alpha, angle of incidence [deg]. 00693 * - 3: n_r, refractive index at the reference wavelength, lambda_r. 00694 * - 4: n'_r, dn/dlambda at the reference wavelength, lambda_r (/m). 00695 * - 5: epsilon, grating tilt angle [deg]. 00696 * - 6: theta, detector tilt angle [deg]. 00697 * 00698 * The remaining members of the spcprm struct are maintained by spcset() and 00699 * must not be modified elsewhere: 00700 * 00701 * double w[6] 00702 * (Returned) Intermediate values: 00703 * - 0: Rest frequency or wavelength (SI). 00704 * - 1: The value of the X-type spectral variable at the reference point 00705 * (SI units). 00706 * - 2: dX/dS at the reference point (SI units). 00707 * The remainder are grism intermediates. 00708 * 00709 * int isGrism 00710 * (Returned) Grism coordinates? 00711 * - 0: no, 00712 * - 1: in vacuum, 00713 * - 2: in air. 00714 * 00715 * int padding1 00716 * (An unused variable inserted for alignment purposes only.) 00717 * 00718 * struct wcserr *err 00719 * (Returned) If enabled, when an error status is returned this structure 00720 * contains detailed information about the error, see wcserr_enable(). 00721 * 00722 * void *padding2 00723 * (An unused variable inserted for alignment purposes only.) 00724 * int (*spxX2P)(SPX_ARGS) 00725 * (Returned) The first and ... 00726 * int (*spxP2S)(SPX_ARGS) 00727 * (Returned) ... the second of the pointers to the transformation 00728 * functions in the two-step algorithm chain X -> P -> S in the 00729 * pixel-to-spectral direction where the non-linear transformation is from 00730 * X to P. The argument list, SPX_ARGS, is defined in spx.h. 00731 * 00732 * int (*spxS2P)(SPX_ARGS) 00733 * (Returned) The first and ... 00734 * int (*spxP2X)(SPX_ARGS) 00735 * (Returned) ... the second of the pointers to the transformation 00736 * functions in the two-step algorithm chain S -> P -> X in the 00737 * spectral-to-pixel direction where the non-linear transformation is from 00738 * P to X. The argument list, SPX_ARGS, is defined in spx.h. 00739 * 00740 * 00741 * Global variable: const char *spc_errmsg[] - Status return messages 00742 * ------------------------------------------------------------------ 00743 * Error messages to match the status value returned from each function. 00744 * 00745 *===========================================================================*/ 00746 00747 #ifndef WCSLIB_SPC 00748 #define WCSLIB_SPC 00749 00750 #include "spx.h" 00751 #include "wcserr.h" 00752 00753 #ifdef __cplusplus 00754 extern "C" { 00755 #endif 00756 00757 00758 extern const char *spc_errmsg[]; 00759 00760 enum spc_errmsg_enum { 00761 SPCERR_SUCCESS = 0, /* Success. */ 00762 SPCERR_NULL_POINTER = 1, /* Null spcprm pointer passed. */ 00763 SPCERR_BAD_SPEC_PARAMS = 2, /* Invalid spectral parameters. */ 00764 SPCERR_BAD_X = 3, /* One or more of x coordinates were 00765 invalid. */ 00766 SPCERR_BAD_SPEC = 4 /* One or more of the spec coordinates were 00767 invalid. */ 00768 }; 00769 00770 struct spcprm { 00771 /* Initialization flag (see the prologue above). */ 00772 /*------------------------------------------------------------------------*/ 00773 int flag; /* Set to zero to force initialization. */ 00774 00775 /* Parameters to be provided (see the prologue above). */ 00776 /*------------------------------------------------------------------------*/ 00777 char type[8]; /* Four-letter spectral variable type. */ 00778 char code[4]; /* Three-letter spectral algorithm code. */ 00779 00780 double crval; /* Reference value (CRVALia), SI units. */ 00781 double restfrq; /* Rest frequency, Hz. */ 00782 double restwav; /* Rest wavelength, m. */ 00783 00784 double pv[7]; /* Grism parameters: */ 00785 /* 0: G, grating ruling density. */ 00786 /* 1: m, interference order. */ 00787 /* 2: alpha, angle of incidence. */ 00788 /* 3: n_r, refractive index at lambda_r. */ 00789 /* 4: n'_r, dn/dlambda at lambda_r. */ 00790 /* 5: epsilon, grating tilt angle. */ 00791 /* 6: theta, detector tilt angle. */ 00792 00793 /* Information derived from the parameters supplied. */ 00794 /*------------------------------------------------------------------------*/ 00795 double w[6]; /* Intermediate values. */ 00796 /* 0: Rest frequency or wavelength (SI). */ 00797 /* 1: CRVALX (SI units). */ 00798 /* 2: CDELTX/CDELTia = dX/dS (SI units). */ 00799 /* The remainder are grism intermediates. */ 00800 00801 int isGrism; /* Grism coordinates? 1: vacuum, 2: air. */ 00802 int padding1; /* (Dummy inserted for alignment purposes.) */ 00803 00804 /* Error handling */ 00805 /*------------------------------------------------------------------------*/ 00806 struct wcserr *err; 00807 00808 /* Private */ 00809 /*------------------------------------------------------------------------*/ 00810 void *padding2; /* (Dummy inserted for alignment purposes.) */ 00811 int (*spxX2P)(SPX_ARGS); /* Pointers to the transformation functions */ 00812 int (*spxP2S)(SPX_ARGS); /* in the two-step algorithm chain in the */ 00813 /* pixel-to-spectral direction. */ 00814 00815 int (*spxS2P)(SPX_ARGS); /* Pointers to the transformation functions */ 00816 int (*spxP2X)(SPX_ARGS); /* in the two-step algorithm chain in the */ 00817 /* spectral-to-pixel direction. */ 00818 }; 00819 00820 /* Size of the spcprm struct in int units, used by the Fortran wrappers. */ 00821 #define SPCLEN (sizeof(struct spcprm)/sizeof(int)) 00822 00823 00824 int spcini(struct spcprm *spc); 00825 00826 int spcfree(struct spcprm *spc); 00827 00828 int spcprt(const struct spcprm *spc); 00829 00830 int spcset(struct spcprm *spc); 00831 00832 int spcx2s(struct spcprm *spc, int nx, int sx, int sspec, 00833 const double x[], double spec[], int stat[]); 00834 00835 int spcs2x(struct spcprm *spc, int nspec, int sspec, int sx, 00836 const double spec[], double x[], int stat[]); 00837 00838 int spctype(const char ctype[], char stype[], char scode[], char sname[], 00839 char units[], char *ptype, char *xtype, int *restreq, 00840 struct wcserr **err); 00841 00842 int spcspxe(const char ctypeS[], double crvalS, double restfrq, 00843 double restwav, char *ptype, char *xtype, int *restreq, 00844 double *crvalX, double *dXdS, struct wcserr **err); 00845 00846 int spcxpse(const char ctypeS[], double crvalX, double restfrq, 00847 double restwav, char *ptype, char *xtype, int *restreq, 00848 double *crvalS, double *dSdX, struct wcserr **err); 00849 00850 int spctrne(const char ctypeS1[], double crvalS1, double cdeltS1, 00851 double restfrq, double restwav, char ctypeS2[], double *crvalS2, 00852 double *cdeltS2, struct wcserr **err); 00853 00854 int spcaips(const char ctypeA[], int velref, char ctype[], char specsys[]); 00855 00856 00857 /* Deprecated. */ 00858 #define spcini_errmsg spc_errmsg 00859 #define spcprt_errmsg spc_errmsg 00860 #define spcset_errmsg spc_errmsg 00861 #define spcx2s_errmsg spc_errmsg 00862 #define spcs2x_errmsg spc_errmsg 00863 00864 int spctyp(const char ctype[], char stype[], char scode[], char sname[], 00865 char units[], char *ptype, char *xtype, int *restreq); 00866 int spcspx(const char ctypeS[], double crvalS, double restfrq, double restwav, 00867 char *ptype, char *xtype, int *restreq, double *crvalX, 00868 double *dXdS); 00869 int spcxps(const char ctypeS[], double crvalX, double restfrq, double restwav, 00870 char *ptype, char *xtype, int *restreq, double *crvalS, 00871 double *dSdX); 00872 int spctrn(const char ctypeS1[], double crvalS1, double cdeltS1, 00873 double restfrq, double restwav, char ctypeS2[], double *crvalS2, 00874 double *cdeltS2); 00875 00876 #ifdef __cplusplus 00877 } 00878 #endif 00879 00880 #endif /* WCSLIB_SPC */