- Main Page
- Related Pages
- Data Structures
- Files

# spc.h

Go to the documentation of this file.

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