00001 /*============================================================================ 00002 00003 WCSLIB 4.13 - an implementation of the FITS WCS standard. 00004 Copyright (C) 1995-2012, Mark Calabretta 00005 00006 This file is part of WCSLIB. 00007 00008 WCSLIB is free software: you can redistribute it and/or modify it under the 00009 terms of the GNU Lesser General Public License as published by the Free 00010 Software Foundation, either version 3 of the License, or (at your option) 00011 any later version. 00012 00013 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY 00014 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00015 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for 00016 more details. 00017 00018 You should have received a copy of the GNU Lesser General Public License 00019 along with WCSLIB. If not, see <http://www.gnu.org/licenses/>. 00020 00021 Correspondence concerning WCSLIB may be directed to: 00022 Internet email: mcalabre@atnf.csiro.au 00023 Postal address: Dr. Mark Calabretta 00024 Australia Telescope National Facility, CSIRO 00025 PO Box 76 00026 Epping NSW 1710 00027 AUSTRALIA 00028 00029 Author: Mark Calabretta, Australia Telescope National Facility 00030 http://www.atnf.csiro.au/~mcalabre/index.html 00031 $Id: spc.h,v 4.13.1.1 2012/03/14 07:40:37 cal103 Exp cal103 $ 00032 *============================================================================= 00033 * 00034 * WCSLIB 4.13 - 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 CTYPEia and VELREF 00088 * keyvalues. 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. 00420 * 00421 * Returned: 00422 * ptype char* Character code for the P-type spectral variable 00423 * derived from ctypeS, one of 'F', 'W', 'A', or 'V'. 00424 * 00425 * xtype char* Character code for the X-type spectral variable 00426 * derived from ctypeS, one of 'F', 'W', 'A', or 'V'. 00427 * Also, 'w' and 'a' are synonymous to 'W' and 'A' for 00428 * grisms in vacuo and air respectively; crvalX and dXdS 00429 * (see below) will conform to these. 00430 * 00431 * restreq int* Multivalued flag that indicates whether rest frequency 00432 * or wavelength is required to compute spectral 00433 * variables for this CTYPEia, as for spctype(). 00434 * 00435 * crvalX double* Value of the X-type spectral variable at the reference 00436 * point, SI units. 00437 * 00438 * dXdS double* The derivative, dX/dS, evaluated at the reference 00439 * point, SI units. Multiply the CDELTia keyvalue by 00440 * this to get the pixel spacing in the X-type spectral 00441 * coordinate. 00442 * 00443 * err struct wcserr ** 00444 * For function return values > 1, this struct will 00445 * contain a detailed error message. May be NULL if an 00446 * error message is not desired. 00447 * 00448 * Function return value: 00449 * int Status return value: 00450 * 0: Success. 00451 * 2: Invalid spectral parameters. 00452 * 00453 * 00454 * spcxpse() - Spectral keyword synthesis 00455 * ------------------------------------- 00456 * spcxpse(), for the spectral axis type specified and the value provided for 00457 * the X-type spectral variable at the reference point, deduces the value of 00458 * the FITS spectral axis keyword CRVALia and also the derivative dS/dX which 00459 * may be used to compute CDELTia. See above for an explanation of the S-, 00460 * P-, and X-type spectral variables. 00461 * 00462 * A deprecated form of this function, spcxps(), lacks the wcserr** parameter. 00463 * 00464 * Given: 00465 * ctypeS const char[9] 00466 * The required spectral axis type, i.e. the CTYPEia 00467 * keyvalue, (eight characters with null termination). 00468 * For non-grism axes, the character code for the P-type 00469 * spectral variable in the algorithm code (i.e. the 00470 * eighth character of CTYPEia) may be set to '?' (it 00471 * will not be reset). 00472 * 00473 * crvalX double Value of the X-type spectral variable at the reference 00474 * point (N.B. NOT the CRVALia keyvalue), SI units. 00475 * 00476 * restfrq, 00477 * restwav double Rest frequency [Hz] and rest wavelength in vacuo [m], 00478 * only one of which need be given, the other should be 00479 * set to zero. 00480 * 00481 * Returned: 00482 * ptype char* Character code for the P-type spectral variable 00483 * derived from ctypeS, one of 'F', 'W', 'A', or 'V'. 00484 * 00485 * xtype char* Character code for the X-type spectral variable 00486 * derived from ctypeS, one of 'F', 'W', 'A', or 'V'. 00487 * Also, 'w' and 'a' are synonymous to 'W' and 'A' for 00488 * grisms; crvalX and cdeltX must conform to these. 00489 * 00490 * restreq int* Multivalued flag that indicates whether rest frequency 00491 * or wavelength is required to compute spectral 00492 * variables for this CTYPEia, as for spctype(). 00493 * 00494 * crvalS double* Value of the S-type spectral variable at the reference 00495 * point (i.e. the appropriate CRVALia keyvalue), SI 00496 * units. 00497 * 00498 * dSdX double* The derivative, dS/dX, evaluated at the reference 00499 * point, SI units. Multiply this by the pixel spacing 00500 * in the X-type spectral coordinate to get the CDELTia 00501 * keyvalue. 00502 * 00503 * err struct wcserr ** 00504 * For function return values > 1, this struct will 00505 * contain a detailed error message. May be NULL if an 00506 * error message is not desired. 00507 * 00508 * Function return value: 00509 * int Status return value: 00510 * 0: Success. 00511 * 2: Invalid spectral parameters. 00512 * 00513 * 00514 * spctrne() - Spectral keyword translation 00515 * --------------------------------------- 00516 * spctrne() translates a set of FITS spectral axis keywords into the 00517 * corresponding set for the specified spectral axis type. For example, a 00518 * 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa. 00519 * 00520 * A deprecated form of this function, spctrn(), lacks the wcserr** parameter. 00521 * 00522 * Given: 00523 * ctypeS1 const char[9] 00524 * Spectral axis type, i.e. the CTYPEia keyvalue, (eight 00525 * characters with null termination). For non-grism 00526 * axes, the character code for the P-type spectral 00527 * variable in the algorithm code (i.e. the eighth 00528 * character of CTYPEia) may be set to '?' (it will not 00529 * be reset). 00530 * 00531 * crvalS1 double Value of the S-type spectral variable at the reference 00532 * point, i.e. the CRVALia keyvalue, SI units. 00533 * 00534 * cdeltS1 double Increment of the S-type spectral variable at the 00535 * reference point, SI units. 00536 * 00537 * restfrq, 00538 * restwav double Rest frequency [Hz] and rest wavelength in vacuo [m], 00539 * only one of which need be given, the other should be 00540 * set to zero. Neither are required if the translation 00541 * is between wave-characteristic types, or between 00542 * velocity-characteristic types. E.g., required for 00543 * 'FREQ' -> 'ZOPT-F2W', but not required for 00544 * 'VELO-F2V' -> 'ZOPT-F2W'. 00545 * 00546 * Given and returned: 00547 * ctypeS2 char[9] Required spectral axis type (eight characters with 00548 * null termination). The first four characters are 00549 * required to be given and are never modified. The 00550 * remaining four, the algorithm code, are completely 00551 * determined by, and must be consistent with, ctypeS1 00552 * and the first four characters of ctypeS2. A non-zero 00553 * status value will be returned if they are inconsistent 00554 * (see below). However, if the final three characters 00555 * are specified as "???", or if just the eighth 00556 * character is specified as '?', the correct algorithm 00557 * code will be substituted (applies for grism axes as 00558 * well as non-grism). 00559 * 00560 * Returned: 00561 * crvalS2 double* Value of the new S-type spectral variable at the 00562 * reference point, i.e. the new CRVALia keyvalue, SI 00563 * units. 00564 * 00565 * cdeltS2 double* Increment of the new S-type spectral variable at the 00566 * reference point, i.e. the new CDELTia keyvalue, SI 00567 * units. 00568 * 00569 * err struct wcserr ** 00570 * For function return values > 1, this struct will 00571 * contain a detailed error message. May be NULL if an 00572 * error message is not desired. 00573 * 00574 * Function return value: 00575 * int Status return value: 00576 * 0: Success. 00577 * 2: Invalid spectral parameters. 00578 * 00579 * A status value of 2 will be returned if restfrq or 00580 * restwav are not specified when required, or if ctypeS1 00581 * or ctypeS2 are self-inconsistent, or have different 00582 * spectral X-type variables. 00583 * 00584 * 00585 * spcaips() - Translate AIPS-convention spectral keywords 00586 * ------------------------------------------------------- 00587 * spcaips() translates AIPS-convention spectral CTYPEia and VELREF keyvalues. 00588 * 00589 * Given: 00590 * ctypeA const char[9] 00591 * CTYPEia keyvalue possibly containing an 00592 * AIPS-convention spectral code (eight characters, need 00593 * not be null-terminated). 00594 * 00595 * velref int AIPS-convention VELREF code. It has the following 00596 * integer values: 00597 * 1: LSR kinematic, originally described simply as 00598 * "LSR" without distinction between the kinematic 00599 * and dynamic definitions. 00600 * 2: Barycentric, originally described as "HEL" 00601 * meaning heliocentric. 00602 * 3: Topocentric, originally described as "OBS" 00603 * meaning geocentric but widely interpreted as 00604 * topocentric. 00605 * AIPS++ extensions to VELREF are also recognized: 00606 * 4: LSR dynamic. 00607 * 5: Geocentric. 00608 * 6: Source rest frame. 00609 * 7: Galactocentric. 00610 * 00611 * For an AIPS 'VELO' axis, a radio convention velocity 00612 * (VRAD) is denoted by adding 256 to VELREF, otherwise 00613 * an optical velocity (VOPT) is indicated (this is not 00614 * applicable to 'FREQ' or 'FELO' axes). Setting velref 00615 * to 0 or 256 chooses between optical and radio velocity 00616 * without specifying a Doppler frame, provided that a 00617 * frame is encoded in ctypeA. If not, i.e. for 00618 * ctypeA = 'VELO', ctype will be returned as 'VELO'. 00619 * 00620 * VELREF takes precedence over CTYPEia in defining the 00621 * Doppler frame, e.g. 00622 * 00623 = ctypeA = 'VELO-HEL' 00624 = velref = 1 00625 * 00626 * returns ctype = 'VOPT' with specsys set to 'LSRK'. 00627 * 00628 * Returned: 00629 * ctype char[9] Translated CTYPEia keyvalue, or a copy of ctypeA if no 00630 * translation was performed (in which case any trailing 00631 * blanks in ctypeA will be replaced with nulls). 00632 * 00633 * specsys char[9] Doppler reference frame indicated by VELREF or else 00634 * by CTYPEia with value corresponding to the SPECSYS 00635 * keyvalue in the FITS WCS standard. May be returned 00636 * blank if neither specifies a Doppler frame, e.g. 00637 * ctypeA = 'FELO' and velref%256 == 0. 00638 * 00639 * Function return value: 00640 * int Status return value: 00641 * -1: No translation required (not an error). 00642 * 0: Success. 00643 * 2: Invalid value of VELREF. 00644 * 00645 * 00646 * spcprm struct - Spectral transformation parameters 00647 * -------------------------------------------------- 00648 * The spcprm struct contains information required to transform spectral 00649 * coordinates. It consists of certain members that must be set by the user 00650 * ("given") and others that are set by the WCSLIB routines ("returned"). Some 00651 * of the latter are supplied for informational purposes while others are for 00652 * internal use only. 00653 * 00654 * int flag 00655 * (Given and returned) This flag must be set to zero whenever any of the 00656 * following spcprm structure members are set or changed: 00657 * 00658 * - spcprm::type, 00659 * - spcprm::code, 00660 * - spcprm::crval, 00661 * - spcprm::restfrq, 00662 * - spcprm::restwav, 00663 * - spcprm::pv[]. 00664 * 00665 * This signals the initialization routine, spcset(), to recompute the 00666 * returned members of the spcprm struct. spcset() will reset flag to 00667 * indicate that this has been done. 00668 * 00669 * char type[8] 00670 * (Given) Four-letter spectral variable type, e.g "ZOPT" for 00671 * CTYPEia = 'ZOPT-F2W'. (Declared as char[8] for alignment reasons.) 00672 * 00673 * char code[4] 00674 * (Given) Three-letter spectral algorithm code, e.g "F2W" for 00675 * CTYPEia = 'ZOPT-F2W'. 00676 * 00677 * double crval 00678 * (Given) Reference value (CRVALia), SI units. 00679 * 00680 * double restfrq 00681 * (Given) The rest frequency [Hz], and ... 00682 * 00683 * double restwav 00684 * (Given) ... the rest wavelength in vacuo [m], only one of which need be 00685 * given, the other should be set to zero. Neither are required if the 00686 * X and S spectral variables are both wave-characteristic, or both 00687 * velocity-characteristic, types. 00688 * 00689 * double pv[7] 00690 * (Given) Grism parameters for 'GRI' and 'GRA' algorithm codes: 00691 * - 0: G, grating ruling density. 00692 * - 1: m, interference order. 00693 * - 2: alpha, angle of incidence [deg]. 00694 * - 3: n_r, refractive index at the reference wavelength, lambda_r. 00695 * - 4: n'_r, dn/dlambda at the reference wavelength, lambda_r (/m). 00696 * - 5: epsilon, grating tilt angle [deg]. 00697 * - 6: theta, detector tilt angle [deg]. 00698 * 00699 * The remaining members of the spcprm struct are maintained by spcset() and 00700 * must not be modified elsewhere: 00701 * 00702 * double w[6] 00703 * (Returned) Intermediate values: 00704 * - 0: Rest frequency or wavelength (SI). 00705 * - 1: The value of the X-type spectral variable at the reference point 00706 * (SI units). 00707 * - 2: dX/dS at the reference point (SI units). 00708 * The remainder are grism intermediates. 00709 * 00710 * int isGrism 00711 * (Returned) Grism coordinates? 00712 * - 0: no, 00713 * - 1: in vacuum, 00714 * - 2: in air. 00715 * 00716 * int padding1 00717 * (An unused variable inserted for alignment purposes only.) 00718 * 00719 * struct wcserr *err 00720 * (Returned) If enabled, when an error status is returned this structure 00721 * contains detailed information about the error, see wcserr_enable(). 00722 * 00723 * void *padding2 00724 * (An unused variable inserted for alignment purposes only.) 00725 * int (*spxX2P)(SPX_ARGS) 00726 * (Returned) The first and ... 00727 * int (*spxP2S)(SPX_ARGS) 00728 * (Returned) ... the second of the pointers to the transformation 00729 * functions in the two-step algorithm chain X -> P -> S in the 00730 * pixel-to-spectral direction where the non-linear transformation is from 00731 * X to P. The argument list, SPX_ARGS, is defined in spx.h. 00732 * 00733 * int (*spxS2P)(SPX_ARGS) 00734 * (Returned) The first and ... 00735 * int (*spxP2X)(SPX_ARGS) 00736 * (Returned) ... the second of the pointers to the transformation 00737 * functions in the two-step algorithm chain S -> P -> X in the 00738 * spectral-to-pixel direction where the non-linear transformation is from 00739 * P to X. The argument list, SPX_ARGS, is defined in spx.h. 00740 * 00741 * 00742 * Global variable: const char *spc_errmsg[] - Status return messages 00743 * ------------------------------------------------------------------ 00744 * Error messages to match the status value returned from each function. 00745 * 00746 *===========================================================================*/ 00747 00748 #ifndef WCSLIB_SPC 00749 #define WCSLIB_SPC 00750 00751 #include "spx.h" 00752 #include "wcserr.h" 00753 00754 #ifdef __cplusplus 00755 extern "C" { 00756 #endif 00757 00758 00759 extern const char *spc_errmsg[]; 00760 00761 enum spc_errmsg_enum { 00762 SPCERR_NO_CHANGE = -1, /* No change. */ 00763 SPCERR_SUCCESS = 0, /* Success. */ 00764 SPCERR_NULL_POINTER = 1, /* Null spcprm pointer passed. */ 00765 SPCERR_BAD_SPEC_PARAMS = 2, /* Invalid spectral parameters. */ 00766 SPCERR_BAD_X = 3, /* One or more of x coordinates were 00767 invalid. */ 00768 SPCERR_BAD_SPEC = 4 /* One or more of the spec coordinates were 00769 invalid. */ 00770 }; 00771 00772 struct spcprm { 00773 /* Initialization flag (see the prologue above). */ 00774 /*------------------------------------------------------------------------*/ 00775 int flag; /* Set to zero to force initialization. */ 00776 00777 /* Parameters to be provided (see the prologue above). */ 00778 /*------------------------------------------------------------------------*/ 00779 char type[8]; /* Four-letter spectral variable type. */ 00780 char code[4]; /* Three-letter spectral algorithm code. */ 00781 00782 double crval; /* Reference value (CRVALia), SI units. */ 00783 double restfrq; /* Rest frequency, Hz. */ 00784 double restwav; /* Rest wavelength, m. */ 00785 00786 double pv[7]; /* Grism parameters: */ 00787 /* 0: G, grating ruling density. */ 00788 /* 1: m, interference order. */ 00789 /* 2: alpha, angle of incidence. */ 00790 /* 3: n_r, refractive index at lambda_r. */ 00791 /* 4: n'_r, dn/dlambda at lambda_r. */ 00792 /* 5: epsilon, grating tilt angle. */ 00793 /* 6: theta, detector tilt angle. */ 00794 00795 /* Information derived from the parameters supplied. */ 00796 /*------------------------------------------------------------------------*/ 00797 double w[6]; /* Intermediate values. */ 00798 /* 0: Rest frequency or wavelength (SI). */ 00799 /* 1: CRVALX (SI units). */ 00800 /* 2: CDELTX/CDELTia = dX/dS (SI units). */ 00801 /* The remainder are grism intermediates. */ 00802 00803 int isGrism; /* Grism coordinates? 1: vacuum, 2: air. */ 00804 int padding1; /* (Dummy inserted for alignment purposes.) */ 00805 00806 /* Error handling */ 00807 /*------------------------------------------------------------------------*/ 00808 struct wcserr *err; 00809 00810 /* Private */ 00811 /*------------------------------------------------------------------------*/ 00812 void *padding2; /* (Dummy inserted for alignment purposes.) */ 00813 int (*spxX2P)(SPX_ARGS); /* Pointers to the transformation functions */ 00814 int (*spxP2S)(SPX_ARGS); /* in the two-step algorithm chain in the */ 00815 /* pixel-to-spectral direction. */ 00816 00817 int (*spxS2P)(SPX_ARGS); /* Pointers to the transformation functions */ 00818 int (*spxP2X)(SPX_ARGS); /* in the two-step algorithm chain in the */ 00819 /* spectral-to-pixel direction. */ 00820 }; 00821 00822 /* Size of the spcprm struct in int units, used by the Fortran wrappers. */ 00823 #define SPCLEN (sizeof(struct spcprm)/sizeof(int)) 00824 00825 00826 int spcini(struct spcprm *spc); 00827 00828 int spcfree(struct spcprm *spc); 00829 00830 int spcprt(const struct spcprm *spc); 00831 00832 int spcset(struct spcprm *spc); 00833 00834 int spcx2s(struct spcprm *spc, int nx, int sx, int sspec, 00835 const double x[], double spec[], int stat[]); 00836 00837 int spcs2x(struct spcprm *spc, int nspec, int sspec, int sx, 00838 const double spec[], double x[], int stat[]); 00839 00840 int spctype(const char ctype[], char stype[], char scode[], char sname[], 00841 char units[], char *ptype, char *xtype, int *restreq, 00842 struct wcserr **err); 00843 00844 int spcspxe(const char ctypeS[], double crvalS, double restfrq, 00845 double restwav, char *ptype, char *xtype, int *restreq, 00846 double *crvalX, double *dXdS, struct wcserr **err); 00847 00848 int spcxpse(const char ctypeS[], double crvalX, double restfrq, 00849 double restwav, char *ptype, char *xtype, int *restreq, 00850 double *crvalS, double *dSdX, struct wcserr **err); 00851 00852 int spctrne(const char ctypeS1[], double crvalS1, double cdeltS1, 00853 double restfrq, double restwav, char ctypeS2[], double *crvalS2, 00854 double *cdeltS2, struct wcserr **err); 00855 00856 int spcaips(const char ctypeA[], int velref, char ctype[], char specsys[]); 00857 00858 00859 /* Deprecated. */ 00860 #define spcini_errmsg spc_errmsg 00861 #define spcprt_errmsg spc_errmsg 00862 #define spcset_errmsg spc_errmsg 00863 #define spcx2s_errmsg spc_errmsg 00864 #define spcs2x_errmsg spc_errmsg 00865 00866 int spctyp(const char ctype[], char stype[], char scode[], char sname[], 00867 char units[], char *ptype, char *xtype, int *restreq); 00868 int spcspx(const char ctypeS[], double crvalS, double restfrq, double restwav, 00869 char *ptype, char *xtype, int *restreq, double *crvalX, 00870 double *dXdS); 00871 int spcxps(const char ctypeS[], double crvalX, double restfrq, double restwav, 00872 char *ptype, char *xtype, int *restreq, double *crvalS, 00873 double *dSdX); 00874 int spctrn(const char ctypeS1[], double crvalS1, double cdeltS1, 00875 double restfrq, double restwav, char ctypeS2[], double *crvalS2, 00876 double *cdeltS2); 00877 00878 #ifdef __cplusplus 00879 } 00880 #endif 00881 00882 #endif /* WCSLIB_SPC */