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