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