WCSLIB: spc.h Source File

WCSLIB 7.3.1

spc.h
Go to the documentation of this file.
1 /*============================================================================
2 WCSLIB 7.3 - an implementation of the FITS WCS standard.
3 Copyright (C) 1995-2020, Mark Calabretta
4
5 This file is part of WCSLIB.
6
7 WCSLIB is free software: you can redistribute it and/or modify it under the
8 terms of the GNU Lesser General Public License as published by the Free
9 Software Foundation, either version 3 of the License, or (at your option)
10 any later version.
11
12 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
13 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
14 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
15 more details.
16
17 You should have received a copy of the GNU Lesser General Public License
18 along with WCSLIB. If not, see http://www.gnu.org/licenses.
19
20 Direct correspondence concerning WCSLIB to mark@calabretta.id.au
21
22 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
23 http://www.atnf.csiro.au/people/Mark.Calabretta
24 $Id: spc.h,v 7.3.1.2 2020/08/17 11:19:09 mcalabre Exp mcalabre $
25 *=============================================================================
26 *
27 * WCSLIB 7.3 - C routines that implement the FITS World Coordinate System
28 * (WCS) standard. Refer to the README file provided with WCSLIB for an
29 * overview of the library.
30 *
31 *
32 * Summary of the spc routines
33 * ---------------------------
34 * Routines in this suite implement the part of the FITS World Coordinate
35 * System (WCS) standard that deals with spectral coordinates, as described in
36 *
37 = "Representations of world coordinates in FITS",
38 = Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
39 =
40 = "Representations of spectral coordinates in FITS",
41 = Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
42 = 2006, A&A, 446, 747 (WCS Paper III)
43 *
44 * These routines define methods to be used for computing spectral world
45 * coordinates from intermediate world coordinates (a linear transformation
46 * of image pixel coordinates), and vice versa. They are based on the spcprm
47 * struct which contains all information needed for the computations. The
48 * struct contains some members that must be set by the user, and others that
49 * are maintained by these routines, somewhat like a C++ class but with no
50 * encapsulation.
51 *
52 * Routine spcini() is provided to initialize the spcprm struct with default
53 * values, spcfree() reclaims any memory that may have been allocated to store
54 * an error message, and spcprt() prints its contents.
55 *
56 * spcperr() prints the error message(s) (if any) stored in a spcprm struct.
57 *
58 * A setup routine, spcset(), computes intermediate values in the spcprm struct
59 * from parameters in it that were supplied by the user. The struct always
60 * needs to be set up by spcset() but it need not be called explicitly - refer
61 * to the explanation of spcprm::flag.
62 *
63 * spcx2s() and spcs2x() implement the WCS spectral coordinate transformations.
64 * In fact, they are high level driver routines for the lower level spectral
65 * coordinate transformation routines described in spx.h.
66 *
67 * A number of routines are provided to aid in analysing or synthesising sets
68 * of FITS spectral axis keywords:
69 *
70 * - spctype() checks a spectral CTYPEia keyword for validity and returns
71 * information derived from it.
72 *
73 * - Spectral keyword analysis routine spcspxe() computes the values of the
74 * X-type spectral variables for the S-type variables supplied.
75 *
76 * - Spectral keyword synthesis routine, spcxpse(), computes the S-type
77 * variables for the X-types supplied.
78 *
79 * - Given a set of spectral keywords, a translation routine, spctrne(),
80 * produces the corresponding set for the specified spectral CTYPEia.
81 *
82 * - spcaips() translates AIPS-convention spectral CTYPEia and VELREF
83 * keyvalues.
84 *
85 * Spectral variable types - S, P, and X:
86 * --------------------------------------
87 * A few words of explanation are necessary regarding spectral variable types
88 * in FITS.
89 *
90 * Every FITS spectral axis has three associated spectral variables:
91 *
92 * S-type: the spectral variable in which coordinates are to be
93 * expressed. Each S-type is encoded as four characters and is
94 * linearly related to one of four basic types as follows:
95 *
96 * F (Frequency):
97 * - 'FREQ': frequency
98 * - 'AFRQ': angular frequency
99 * - 'ENER': photon energy
100 * - 'WAVN': wave number
101 * - 'VRAD': radio velocity
102 *
103 * W (Wavelength in vacuo):
104 * - 'WAVE': wavelength
105 * - 'VOPT': optical velocity
106 * - 'ZOPT': redshift
107 *
108 * A (wavelength in Air):
109 * - 'AWAV': wavelength in air
110 *
111 * V (Velocity):
112 * - 'VELO': relativistic velocity
113 * - 'BETA': relativistic beta factor
114 *
115 * The S-type forms the first four characters of the CTYPEia keyvalue,
116 * and CRVALia and CDELTia are expressed as S-type quantities so that
117 * they provide a first-order approximation to the S-type variable at
118 * the reference point.
119 *
120 * Note that 'AFRQ', angular frequency, is additional to the variables
121 * defined in WCS Paper III.
122 *
123 * P-type: the basic spectral variable (F, W, A, or V) with which the
124 * S-type variable is associated (see list above).
125 *
126 * For non-grism axes, the P-type is encoded as the eighth character of
127 * CTYPEia.
128 *
129 * X-type: the basic spectral variable (F, W, A, or V) for which the
130 * spectral axis is linear, grisms excluded (see below).
131 *
132 * For non-grism axes, the X-type is encoded as the sixth character of
133 * CTYPEia.
134 *
135 * Grisms: Grism axes have normal S-, and P-types but the axis is linear,
136 * not in any spectral variable, but in a special "grism parameter".
137 * The X-type spectral variable is either W or A for grisms in vacuo or
138 * air respectively, but is encoded as 'w' or 'a' to indicate that an
139 * additional transformation is required to convert to or from the
140 * grism parameter. The spectral algorithm code for grisms also has a
141 * special encoding in CTYPEia, either 'GRI' (in vacuo) or 'GRA' (in air).
142 *
143 * In the algorithm chain, the non-linear transformation occurs between the
144 * X-type and the P-type variables; the transformation between P-type and
145 * S-type variables is always linear.
146 *
147 * When the P-type and X-type variables are the same, the spectral axis is
148 * linear in the S-type variable and the second four characters of CTYPEia
149 * are blank. This can never happen for grism axes.
150 *
151 * As an example, correlating radio spectrometers always produce spectra that
152 * are regularly gridded in frequency; a redshift scale on such a spectrum is
153 * non-linear. The required value of CTYPEia would be 'ZOPT-F2W', where the
154 * desired S-type is 'ZOPT' (redshift), the P-type is necessarily 'W'
155 * (wavelength), and the X-type is 'F' (frequency) by the nature of the
156 * instrument.
157 *
158 * Air-to-vacuum wavelength conversion:
159 * ------------------------------------
160 * Please refer to the prologue of spx.h for important comments relating to the
161 * air-to-vacuum wavelength conversion.
162 *
163 * Argument checking:
164 * ------------------
165 * The input spectral values are only checked for values that would result in
166 * floating point exceptions. In particular, negative frequencies and
167 * wavelengths are allowed, as are velocities greater than the speed of
168 * light. The same is true for the spectral parameters - rest frequency and
169 * wavelength.
170 *
171 * Accuracy:
172 * ---------
173 * No warranty is given for the accuracy of these routines (refer to the
174 * copyright notice); intending users must satisfy for themselves their
175 * adequacy for the intended purpose. However, closure effectively to within
176 * double precision rounding error was demonstrated by test routine tspc.c
177 * which accompanies this software.
178 *
179 *
180 * spcini() - Default constructor for the spcprm struct
181 * ----------------------------------------------------
182 * spcini() sets all members of a spcprm struct to default values. It should
183 * be used to initialize every spcprm struct.
184 *
185 * PLEASE NOTE: If the spcprm struct has already been initialized, then before
186 * reinitializing, it spcfree() should be used to free any memory that may have
187 * been allocated to store an error message. A memory leak may otherwise
188 * result.
189 *
190 * Given and returned:
191 * spc struct spcprm*
192 * Spectral transformation parameters.
193 *
194 * Function return value:
195 * int Status return value:
196 * 0: Success.
197 * 1: Null spcprm pointer passed.
198 *
199 *
200 * spcfree() - Destructor for the spcprm struct
201 * --------------------------------------------
202 * spcfree() frees any memory that may have been allocated to store an error
203 * message in the spcprm struct.
204 *
205 * Given:
206 * spc struct spcprm*
207 * Spectral transformation parameters.
208 *
209 * Function return value:
210 * int Status return value:
211 * 0: Success.
212 * 1: Null spcprm pointer passed.
213 *
214 *
215 * spcprt() - Print routine for the spcprm struct
216 * ----------------------------------------------
217 * spcprt() prints the contents of a spcprm struct using wcsprintf(). Mainly
218 * intended for diagnostic purposes.
219 *
220 * Given:
221 * spc const struct spcprm*
222 * Spectral transformation parameters.
223 *
224 * Function return value:
225 * int Status return value:
226 * 0: Success.
227 * 1: Null spcprm pointer passed.
228 *
229 *
230 * spcperr() - Print error messages from a spcprm struct
231 * -----------------------------------------------------
232 * spcperr() prints the error message(s) (if any) stored in a spcprm struct.
233 * If there are no errors then nothing is printed. It uses wcserr_prt(), q.v.
234 *
235 * Given:
236 * spc const struct spcprm*
237 * Spectral transformation parameters.
238 *
239 * prefix const char *
240 * If non-NULL, each output line will be prefixed with
241 * this string.
242 *
243 * Function return value:
244 * int Status return value:
245 * 0: Success.
246 * 1: Null spcprm pointer passed.
247 *
248 *
249 * spcset() - Setup routine for the spcprm struct
250 * ----------------------------------------------
251 * spcset() sets up a spcprm struct according to information supplied within
252 * it.
253 *
254 * Note that this routine need not be called directly; it will be invoked by
255 * spcx2s() and spcs2x() if spcprm::flag is anything other than a predefined
256 * magic value.
257 *
258 * Given and returned:
259 * spc struct spcprm*
260 * Spectral transformation parameters.
261 *
262 * Function return value:
263 * int Status return value:
264 * 0: Success.
265 * 1: Null spcprm pointer passed.
266 * 2: Invalid spectral parameters.
267 *
268 * For returns > 1, a detailed error message is set in
269 * spcprm::err if enabled, see wcserr_enable().
270 *
271 *
272 * spcx2s() - Transform to spectral coordinates
273 * --------------------------------------------
274 * spcx2s() transforms intermediate world coordinates to spectral coordinates.
275 *
276 * Given and returned:
277 * spc struct spcprm*
278 * Spectral transformation parameters.
279 *
280 * Given:
281 * nx int Vector length.
282 *
283 * sx int Vector stride.
284 *
285 * sspec int Vector stride.
286 *
287 * x const double[]
288 * Intermediate world coordinates, in SI units.
289 *
290 * Returned:
291 * spec double[] Spectral coordinates, in SI units.
292 *
293 * stat int[] Status return value status for each vector element:
294 * 0: Success.
295 * 1: Invalid value of x.
296 *
297 * Function return value:
298 * int Status return value:
299 * 0: Success.
300 * 1: Null spcprm pointer passed.
301 * 2: Invalid spectral parameters.
302 * 3: One or more of the x coordinates were invalid,
303 * as indicated by the stat vector.
304 *
305 * For returns > 1, a detailed error message is set in
306 * spcprm::err if enabled, see wcserr_enable().
307 *
308 *
309 * spcs2x() - Transform spectral coordinates
310 * -----------------------------------------
311 * spcs2x() transforms spectral world coordinates to intermediate world
312 * coordinates.
313 *
314 * Given and returned:
315 * spc struct spcprm*
316 * Spectral transformation parameters.
317 *
318 * Given:
319 * nspec int Vector length.
320 *
321 * sspec int Vector stride.
322 *
323 * sx int Vector stride.
324 *
325 * spec const double[]
326 * Spectral coordinates, in SI units.
327 *
328 * Returned:
329 * x double[] Intermediate world coordinates, in SI units.
330 *
331 * stat int[] Status return value status for each vector element:
332 * 0: Success.
333 * 1: Invalid value of spec.
334 *
335 * Function return value:
336 * int Status return value:
337 * 0: Success.
338 * 1: Null spcprm pointer passed.
339 * 2: Invalid spectral parameters.
340 * 4: One or more of the spec coordinates were
341 * invalid, as indicated by the stat vector.
342 *
343 * For returns > 1, a detailed error message is set in
344 * spcprm::err if enabled, see wcserr_enable().
345 *
346 *
347 * spctype() - Spectral CTYPEia keyword analysis
348 * ---------------------------------------------
349 * spctype() checks whether a CTYPEia keyvalue is a valid spectral axis type
350 * and if so returns information derived from it relating to the associated S-,
351 * P-, and X-type spectral variables (see explanation above).
352 *
353 * The return arguments are guaranteed not be modified if CTYPEia is not a
354 * valid spectral type; zero-pointers may be specified for any that are not of
355 * interest.
356 *
357 * A deprecated form of this function, spctyp(), lacks the wcserr** parameter.
358 *
359 * Given:
360 * ctype const char[9]
361 * The CTYPEia keyvalue, (eight characters with null
362 * termination).
363 *
364 * Returned:
365 * stype char[] The four-letter name of the S-type spectral variable
366 * copied or translated from ctype. If a non-zero
367 * pointer is given, the array must accomodate a null-
368 * terminated string of length 5.
369 *
370 * scode char[] The three-letter spectral algorithm code copied or
371 * translated from ctype. Logarithmic ('LOG') and
372 * tabular ('TAB') codes are also recognized. If a
373 * non-zero pointer is given, the array must accomodate a
374 * null-terminated string of length 4.
375 *
376 * sname char[] Descriptive name of the S-type spectral variable.
377 * If a non-zero pointer is given, the array must
378 * accomodate a null-terminated string of length 22.
379 *
380 * units char[] SI units of the S-type spectral variable. If a
381 * non-zero pointer is given, the array must accomodate a
382 * null-terminated string of length 8.
383 *
384 * ptype char* Character code for the P-type spectral variable
385 * derived from ctype, one of 'F', 'W', 'A', or 'V'.
386 *
387 * xtype char* Character code for the X-type spectral variable
388 * derived from ctype, one of 'F', 'W', 'A', or 'V'.
389 * Also, 'w' and 'a' are synonymous to 'W' and 'A' for
390 * grisms in vacuo and air respectively. Set to 'L' or
391 * 'T' for logarithmic ('LOG') and tabular ('TAB') axes.
392 *
393 * restreq int* Multivalued flag that indicates whether rest
394 * frequency or wavelength is required to compute
395 * spectral variables for this CTYPEia:
396 * 0: Not required.
397 * 1: Required for the conversion between S- and
398 * P-types (e.g. 'ZOPT-F2W').
399 * 2: Required for the conversion between P- and
400 * X-types (e.g. 'BETA-W2V').
401 * 3: Required for the conversion between S- and
402 * P-types, and between P- and X-types, but not
403 * between S- and X-types (this applies only for
404 * 'VRAD-V2F', 'VOPT-V2W', and 'ZOPT-V2W').
405 * Thus the rest frequency or wavelength is required for
406 * spectral coordinate computations (i.e. between S- and
407 * X-types) only if restreq%3 != 0.
408 *
409 * err struct wcserr **
410 * If enabled, for function return values > 1, this
411 * struct will contain a detailed error message, see
412 * wcserr_enable(). May be NULL if an error message is
413 * not desired. Otherwise, the user is responsible for
414 * deleting the memory allocated for the wcserr struct.
415 *
416 * Function return value:
417 * int Status return value:
418 * 0: Success.
419 * 2: Invalid spectral parameters (not a spectral
420 * CTYPEia).
421 *
422 *
423 * spcspxe() - Spectral keyword analysis
424 * ------------------------------------
425 * spcspxe() analyses the CTYPEia and CRVALia FITS spectral axis keyword values
426 * and returns information about the associated X-type spectral variable.
427 *
428 * A deprecated form of this function, spcspx(), lacks the wcserr** parameter.
429 *
430 * Given:
431 * ctypeS const char[9]
432 * Spectral axis type, i.e. the CTYPEia keyvalue, (eight
433 * characters with null termination). For non-grism
434 * axes, the character code for the P-type spectral
435 * variable in the algorithm code (i.e. the eighth
436 * character of CTYPEia) may be set to '?' (it will not
437 * be reset).
438 *
439 * crvalS double Value of the S-type spectral variable at the reference
440 * point, i.e. the CRVALia keyvalue, SI units.
441 *
442 * restfrq,
443 * restwav double Rest frequency [Hz] and rest wavelength in vacuo [m],
444 * only one of which need be given, the other should be
445 * set to zero.
446 *
447 * Returned:
448 * ptype char* Character code for the P-type spectral variable
449 * derived from ctypeS, one of 'F', 'W', 'A', or 'V'.
450 *
451 * xtype char* Character code for the X-type spectral variable
452 * derived from ctypeS, one of 'F', 'W', 'A', or 'V'.
453 * Also, 'w' and 'a' are synonymous to 'W' and 'A' for
454 * grisms in vacuo and air respectively; crvalX and dXdS
455 * (see below) will conform to these.
456 *
457 * restreq int* Multivalued flag that indicates whether rest frequency
458 * or wavelength is required to compute spectral
459 * variables for this CTYPEia, as for spctype().
460 *
461 * crvalX double* Value of the X-type spectral variable at the reference
462 * point, SI units.
463 *
464 * dXdS double* The derivative, dX/dS, evaluated at the reference
465 * point, SI units. Multiply the CDELTia keyvalue by
466 * this to get the pixel spacing in the X-type spectral
467 * coordinate.
468 *
469 * err struct wcserr **
470 * If enabled, for function return values > 1, this
471 * struct will contain a detailed error message, see
472 * wcserr_enable(). May be NULL if an error message is
473 * not desired. Otherwise, the user is responsible for
474 * deleting the memory allocated for the wcserr struct.
475 *
476 * Function return value:
477 * int Status return value:
478 * 0: Success.
479 * 2: Invalid spectral parameters.
480 *
481 *
482 * spcxpse() - Spectral keyword synthesis
483 * -------------------------------------
484 * spcxpse(), for the spectral axis type specified and the value provided for
485 * the X-type spectral variable at the reference point, deduces the value of
486 * the FITS spectral axis keyword CRVALia and also the derivative dS/dX which
487 * may be used to compute CDELTia. See above for an explanation of the S-,
488 * P-, and X-type spectral variables.
489 *
490 * A deprecated form of this function, spcxps(), lacks the wcserr** parameter.
491 *
492 * Given:
493 * ctypeS const char[9]
494 * The required spectral axis type, i.e. the CTYPEia
495 * keyvalue, (eight characters with null termination).
496 * For non-grism axes, the character code for the P-type
497 * spectral variable in the algorithm code (i.e. the
498 * eighth character of CTYPEia) may be set to '?' (it
499 * will not be reset).
500 *
501 * crvalX double Value of the X-type spectral variable at the reference
502 * point (N.B. NOT the CRVALia keyvalue), SI units.
503 *
504 * restfrq,
505 * restwav double Rest frequency [Hz] and rest wavelength in vacuo [m],
506 * only one of which need be given, the other should be
507 * set to zero.
508 *
509 * Returned:
510 * ptype char* Character code for the P-type spectral variable
511 * derived from ctypeS, one of 'F', 'W', 'A', or 'V'.
512 *
513 * xtype char* Character code for the X-type spectral variable
514 * derived from ctypeS, one of 'F', 'W', 'A', or 'V'.
515 * Also, 'w' and 'a' are synonymous to 'W' and 'A' for
516 * grisms; crvalX and cdeltX must conform to these.
517 *
518 * restreq int* Multivalued flag that indicates whether rest frequency
519 * or wavelength is required to compute spectral
520 * variables for this CTYPEia, as for spctype().
521 *
522 * crvalS double* Value of the S-type spectral variable at the reference
523 * point (i.e. the appropriate CRVALia keyvalue), SI
524 * units.
525 *
526 * dSdX double* The derivative, dS/dX, evaluated at the reference
527 * point, SI units. Multiply this by the pixel spacing
528 * in the X-type spectral coordinate to get the CDELTia
529 * keyvalue.
530 *
531 * err struct wcserr **
532 * If enabled, for function return values > 1, this
533 * struct will contain a detailed error message, see
534 * wcserr_enable(). May be NULL if an error message is
535 * not desired. Otherwise, the user is responsible for
536 * deleting the memory allocated for the wcserr struct.
537 *
538 * Function return value:
539 * int Status return value:
540 * 0: Success.
541 * 2: Invalid spectral parameters.
542 *
543 *
544 * spctrne() - Spectral keyword translation
545 * ---------------------------------------
546 * spctrne() translates a set of FITS spectral axis keywords into the
547 * corresponding set for the specified spectral axis type. For example, a
548 * 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.
549 *
550 * A deprecated form of this function, spctrn(), lacks the wcserr** parameter.
551 *
552 * Given:
553 * ctypeS1 const char[9]
554 * Spectral axis type, i.e. the CTYPEia keyvalue, (eight
555 * characters with null termination). For non-grism
556 * axes, the character code for the P-type spectral
557 * variable in the algorithm code (i.e. the eighth
558 * character of CTYPEia) may be set to '?' (it will not
559 * be reset).
560 *
561 * crvalS1 double Value of the S-type spectral variable at the reference
562 * point, i.e. the CRVALia keyvalue, SI units.
563 *
564 * cdeltS1 double Increment of the S-type spectral variable at the
565 * reference point, SI units.
566 *
567 * restfrq,
568 * restwav double Rest frequency [Hz] and rest wavelength in vacuo [m],
569 * only one of which need be given, the other should be
570 * set to zero. Neither are required if the translation
571 * is between wave-characteristic types, or between
572 * velocity-characteristic types. E.g., required for
573 * 'FREQ' -> 'ZOPT-F2W', but not required for
574 * 'VELO-F2V' -> 'ZOPT-F2W'.
575 *
576 * Given and returned:
577 * ctypeS2 char[9] Required spectral axis type (eight characters with
578 * null termination). The first four characters are
579 * required to be given and are never modified. The
580 * remaining four, the algorithm code, are completely
581 * determined by, and must be consistent with, ctypeS1
582 * and the first four characters of ctypeS2. A non-zero
583 * status value will be returned if they are inconsistent
584 * (see below). However, if the final three characters
585 * are specified as "???", or if just the eighth
586 * character is specified as '?', the correct algorithm
587 * code will be substituted (applies for grism axes as
588 * well as non-grism).
589 *
590 * Returned:
591 * crvalS2 double* Value of the new S-type spectral variable at the
592 * reference point, i.e. the new CRVALia keyvalue, SI
593 * units.
594 *
595 * cdeltS2 double* Increment of the new S-type spectral variable at the
596 * reference point, i.e. the new CDELTia keyvalue, SI
597 * units.
598 *
599 * err struct wcserr **
600 * If enabled, for function return values > 1, this
601 * struct will contain a detailed error message, see
602 * wcserr_enable(). May be NULL if an error message is
603 * not desired. Otherwise, the user is responsible for
604 * deleting the memory allocated for the wcserr struct.
605 *
606 * Function return value:
607 * int Status return value:
608 * 0: Success.
609 * 2: Invalid spectral parameters.
610 *
611 * A status value of 2 will be returned if restfrq or
612 * restwav are not specified when required, or if ctypeS1
613 * or ctypeS2 are self-inconsistent, or have different
614 * spectral X-type variables.
615 *
616 *
617 * spcaips() - Translate AIPS-convention spectral keywords
618 * -------------------------------------------------------
619 * spcaips() translates AIPS-convention spectral CTYPEia and VELREF keyvalues.
620 *
621 * Given:
622 * ctypeA const char[9]
623 * CTYPEia keyvalue possibly containing an
624 * AIPS-convention spectral code (eight characters, need
625 * not be null-terminated).
626 *
627 * velref int AIPS-convention VELREF code. It has the following
628 * integer values:
629 * 1: LSR kinematic, originally described simply as
630 * "LSR" without distinction between the kinematic
631 * and dynamic definitions.
632 * 2: Barycentric, originally described as "HEL"
633 * meaning heliocentric.
634 * 3: Topocentric, originally described as "OBS"
635 * meaning geocentric but widely interpreted as
636 * topocentric.
637 * AIPS++ extensions to VELREF are also recognized:
638 * 4: LSR dynamic.
639 * 5: Geocentric.
640 * 6: Source rest frame.
641 * 7: Galactocentric.
642 *
643 * For an AIPS 'VELO' axis, a radio convention velocity
644 * (VRAD) is denoted by adding 256 to VELREF, otherwise
645 * an optical velocity (VOPT) is indicated (this is not
646 * applicable to 'FREQ' or 'FELO' axes). Setting velref
647 * to 0 or 256 chooses between optical and radio velocity
648 * without specifying a Doppler frame, provided that a
649 * frame is encoded in ctypeA. If not, i.e. for
650 * ctypeA = 'VELO', ctype will be returned as 'VELO'.
651 *
652 * VELREF takes precedence over CTYPEia in defining the
653 * Doppler frame, e.g.
654 *
655 = ctypeA = 'VELO-HEL'
656 = velref = 1
657 *
658 * returns ctype = 'VOPT' with specsys set to 'LSRK'.
659 *
660 * If omitted from the header, the default value of
661 * VELREF is 0.
662 *
663 * Returned:
664 * ctype char[9] Translated CTYPEia keyvalue, or a copy of ctypeA if no
665 * translation was performed (in which case any trailing
666 * blanks in ctypeA will be replaced with nulls).
667 *
668 * specsys char[9] Doppler reference frame indicated by VELREF or else
669 * by CTYPEia with value corresponding to the SPECSYS
670 * keyvalue in the FITS WCS standard. May be returned
671 * blank if neither specifies a Doppler frame, e.g.
672 * ctypeA = 'FELO' and velref%256 == 0.
673 *
674 * Function return value:
675 * int Status return value:
676 * -1: No translation required (not an error).
677 * 0: Success.
678 * 2: Invalid value of VELREF.
679 *
680 *
681 * spcprm struct - Spectral transformation parameters
682 * --------------------------------------------------
683 * The spcprm struct contains information required to transform spectral
684 * coordinates. It consists of certain members that must be set by the user
685 * ("given") and others that are set by the WCSLIB routines ("returned"). Some
686 * of the latter are supplied for informational purposes while others are for
687 * internal use only.
688 *
689 * int flag
690 * (Given and returned) This flag must be set to zero whenever any of the
691 * following spcprm structure members are set or changed:
692 *
693 * - spcprm::type,
694 * - spcprm::code,
695 * - spcprm::crval,
696 * - spcprm::restfrq,
697 * - spcprm::restwav,
698 * - spcprm::pv[].
699 *
700 * This signals the initialization routine, spcset(), to recompute the
701 * returned members of the spcprm struct. spcset() will reset flag to
702 * indicate that this has been done.
703 *
704 * char type[8]
705 * (Given) Four-letter spectral variable type, e.g "ZOPT" for
706 * CTYPEia = 'ZOPT-F2W'. (Declared as char[8] for alignment reasons.)
707 *
708 * char code[4]
709 * (Given) Three-letter spectral algorithm code, e.g "F2W" for
710 * CTYPEia = 'ZOPT-F2W'.
711 *
712 * double crval
713 * (Given) Reference value (CRVALia), SI units.
714 *
715 * double restfrq
716 * (Given) The rest frequency [Hz], and ...
717 *
718 * double restwav
719 * (Given) ... the rest wavelength in vacuo [m], only one of which need be
720 * given, the other should be set to zero. Neither are required if the
721 * X and S spectral variables are both wave-characteristic, or both
722 * velocity-characteristic, types.
723 *
724 * double pv[7]
725 * (Given) Grism parameters for 'GRI' and 'GRA' algorithm codes:
726 * - 0: G, grating ruling density.
727 * - 1: m, interference order.
728 * - 2: alpha, angle of incidence [deg].
729 * - 3: n_r, refractive index at the reference wavelength, lambda_r.
730 * - 4: n'_r, dn/dlambda at the reference wavelength, lambda_r (/m).
731 * - 5: epsilon, grating tilt angle [deg].
732 * - 6: theta, detector tilt angle [deg].
733 *
734 * The remaining members of the spcprm struct are maintained by spcset() and
735 * must not be modified elsewhere:
736 *
737 * double w[6]
738 * (Returned) Intermediate values:
739 * - 0: Rest frequency or wavelength (SI).
740 * - 1: The value of the X-type spectral variable at the reference point
741 * (SI units).
742 * - 2: dX/dS at the reference point (SI units).
743 * The remainder are grism intermediates.
744 *
745 * int isGrism
746 * (Returned) Grism coordinates?
747 * - 0: no,
748 * - 1: in vacuum,
749 * - 2: in air.
750 *
751 * int padding1
752 * (An unused variable inserted for alignment purposes only.)
753 *
754 * struct wcserr *err
755 * (Returned) If enabled, when an error status is returned, this struct
756 * contains detailed information about the error, see wcserr_enable().
757 *
758 * void *padding2
759 * (An unused variable inserted for alignment purposes only.)
760 * int (*spxX2P)(SPX_ARGS)
761 * (Returned) The first and ...
762 * int (*spxP2S)(SPX_ARGS)
763 * (Returned) ... the second of the pointers to the transformation
764 * functions in the two-step algorithm chain X -> P -> S in the
765 * pixel-to-spectral direction where the non-linear transformation is from
766 * X to P. The argument list, SPX_ARGS, is defined in spx.h.
767 *
768 * int (*spxS2P)(SPX_ARGS)
769 * (Returned) The first and ...
770 * int (*spxP2X)(SPX_ARGS)
771 * (Returned) ... the second of the pointers to the transformation
772 * functions in the two-step algorithm chain S -> P -> X in the
773 * spectral-to-pixel direction where the non-linear transformation is from
774 * P to X. The argument list, SPX_ARGS, is defined in spx.h.
775 *
776 *
777 * Global variable: const char *spc_errmsg[] - Status return messages
778 * ------------------------------------------------------------------
779 * Error messages to match the status value returned from each function.
780 *
781 *===========================================================================*/
782
783 #ifndef WCSLIB_SPC
784 #define WCSLIB_SPC
785
786 #include "spx.h"
787
788 #ifdef __cplusplus
789 extern "C" {
790 #endif
791
792
793 extern const char *spc_errmsg[];
794
795 enum spc_errmsg_enum {
796 SPCERR_NO_CHANGE = -1, // No change.
797 SPCERR_SUCCESS = 0, // Success.
798 SPCERR_NULL_POINTER = 1, // Null spcprm pointer passed.
799 SPCERR_BAD_SPEC_PARAMS = 2, // Invalid spectral parameters.
800 SPCERR_BAD_X = 3, // One or more of x coordinates were
801 // invalid.
802 SPCERR_BAD_SPEC = 4 // One or more of the spec coordinates were
803 // invalid.
804 };
805
806 struct spcprm {
807 // Initialization flag (see the prologue above).
808 //--------------------------------------------------------------------------
809 int flag; // Set to zero to force initialization.
810
811 // Parameters to be provided (see the prologue above).
812 //--------------------------------------------------------------------------
813 char type[8]; // Four-letter spectral variable type.
814 char code[4]; // Three-letter spectral algorithm code.
815
816 double crval; // Reference value (CRVALia), SI units.
817 double restfrq; // Rest frequency, Hz.
818 double restwav; // Rest wavelength, m.
819
820 double pv[7]; // Grism parameters:
821 // 0: G, grating ruling density.
822 // 1: m, interference order.
823 // 2: alpha, angle of incidence.
824 // 3: n_r, refractive index at lambda_r.
825 // 4: n'_r, dn/dlambda at lambda_r.
826 // 5: epsilon, grating tilt angle.
827 // 6: theta, detector tilt angle.
828
829 // Information derived from the parameters supplied.
830 //--------------------------------------------------------------------------
831 double w[6]; // Intermediate values.
832 // 0: Rest frequency or wavelength (SI).
833 // 1: CRVALX (SI units).
834 // 2: CDELTX/CDELTia = dX/dS (SI units).
835 // The remainder are grism intermediates.
836
837 int isGrism; // Grism coordinates? 1: vacuum, 2: air.
838 int padding1; // (Dummy inserted for alignment purposes.)
839
840 // Error handling
841 //--------------------------------------------------------------------------
842 struct wcserr *err;
843
844 // Private
845 //--------------------------------------------------------------------------
846 void *padding2; // (Dummy inserted for alignment purposes.)
847 int (*spxX2P)(SPX_ARGS); // Pointers to the transformation functions
848 int (*spxP2S)(SPX_ARGS); // in the two-step algorithm chain in the
849 // pixel-to-spectral direction.
850
851 int (*spxS2P)(SPX_ARGS); // Pointers to the transformation functions
852 int (*spxP2X)(SPX_ARGS); // in the two-step algorithm chain in the
853 // spectral-to-pixel direction.
854 };
855
856 // Size of the spcprm struct in int units, used by the Fortran wrappers.
857 #define SPCLEN (sizeof(struct spcprm)/sizeof(int))
858
859
860 int spcini(struct spcprm *spc);
861
862 int spcfree(struct spcprm *spc);
863
864 int spcprt(const struct spcprm *spc);
865
866 int spcperr(const struct spcprm *spc, const char *prefix);
867
868 int spcset(struct spcprm *spc);
869
870 int spcx2s(struct spcprm *spc, int nx, int sx, int sspec,
871 const double x[], double spec[], int stat[]);
872
873 int spcs2x(struct spcprm *spc, int nspec, int sspec, int sx,
874 const double spec[], double x[], int stat[]);
875
876 int spctype(const char ctype[9], char stype[], char scode[], char sname[],
877 char units[], char *ptype, char *xtype, int *restreq,
878 struct wcserr **err);
879
880 int spcspxe(const char ctypeS[9], double crvalS, double restfrq,
881 double restwav, char *ptype, char *xtype, int *restreq,
882 double *crvalX, double *dXdS, struct wcserr **err);
883
884 int spcxpse(const char ctypeS[9], double crvalX, double restfrq,
885 double restwav, char *ptype, char *xtype, int *restreq,
886 double *crvalS, double *dSdX, struct wcserr **err);
887
888 int spctrne(const char ctypeS1[9], double crvalS1, double cdeltS1,
889 double restfrq, double restwav, char ctypeS2[9], double *crvalS2,
890 double *cdeltS2, struct wcserr **err);
891
892 int spcaips(const char ctypeA[9], int velref, char ctype[9], char specsys[9]);
893
894
895 // Deprecated.
896 #define spcini_errmsg spc_errmsg
897 #define spcprt_errmsg spc_errmsg
898 #define spcset_errmsg spc_errmsg
899 #define spcx2s_errmsg spc_errmsg
900 #define spcs2x_errmsg spc_errmsg
901
902 int spctyp(const char ctype[9], char stype[], char scode[], char sname[],
903 char units[], char *ptype, char *xtype, int *restreq);
904 int spcspx(const char ctypeS[9], double crvalS, double restfrq,
905 double restwav, char *ptype, char *xtype, int *restreq,
906 double *crvalX, double *dXdS);
907 int spcxps(const char ctypeS[9], double crvalX, double restfrq,
908 double restwav, char *ptype, char *xtype, int *restreq,
909 double *crvalS, double *dSdX);
910 int spctrn(const char ctypeS1[9], double crvalS1, double cdeltS1,
911 double restfrq, double restwav, char ctypeS2[9], double *crvalS2,
912 double *cdeltS2);
913
914 #ifdef __cplusplus
915 }
916 #endif
917
918 #endif // WCSLIB_SPC
spcprm::padding1
int padding1
Definition: spc.h:838
spcprm::restfrq
double restfrq
Definition: spc.h:817
spcspx
int spcspx(const char ctypeS[9], double crvalS, double restfrq, double restwav, char *ptype, char *xtype, int *restreq, double *crvalX, double *dXdS)
spcxps
int spcxps(const char ctypeS[9], double crvalX, double restfrq, double restwav, char *ptype, char *xtype, int *restreq, double *crvalS, double *dSdX)
spcprm::isGrism
int isGrism
Definition: spc.h:837
spcprm::type
char type[8]
Definition: spc.h:813
spcini
int spcini(struct spcprm *spc)
Default constructor for the spcprm struct.
spcprm
Spectral transformation parameters.
Definition: spc.h:806
spctrn
int spctrn(const char ctypeS1[9], double crvalS1, double cdeltS1, double restfrq, double restwav, char ctypeS2[9], double *crvalS2, double *cdeltS2)
SPCERR_BAD_SPEC
@ SPCERR_BAD_SPEC
Definition: spc.h:802
spctyp
int spctyp(const char ctype[9], char stype[], char scode[], char sname[], char units[], char *ptype, char *xtype, int *restreq)
spcset
int spcset(struct spcprm *spc)
Setup routine for the spcprm struct.
spcaips
int spcaips(const char ctypeA[9], int velref, char ctype[9], char specsys[9])
Translate AIPS-convention spectral keywords.
spcprm::flag
int flag
Definition: spc.h:809
spcprm::pv
double pv[7]
Definition: spc.h:820
spcprm::restwav
double restwav
Definition: spc.h:818
spc_errmsg_enum
spc_errmsg_enum
Definition: spc.h:795
spcs2x
int spcs2x(struct spcprm *spc, int nspec, int sspec, int sx, const double spec[], double x[], int stat[])
Transform spectral coordinates.
spcfree
int spcfree(struct spcprm *spc)
Destructor for the spcprm struct.
SPCERR_BAD_SPEC_PARAMS
@ SPCERR_BAD_SPEC_PARAMS
Definition: spc.h:799
SPX_ARGS
#define SPX_ARGS
For use in declaring spectral conversion function prototypes.
Definition: spx.h:542
spcprm::spxP2X
int(* spxP2X)(SPX_ARGS)
Definition: spc.h:852
spcprm::crval
double crval
Definition: spc.h:816
SPCERR_BAD_X
@ SPCERR_BAD_X
Definition: spc.h:800
spcprt
int spcprt(const struct spcprm *spc)
Print routine for the spcprm struct.
spcprm::padding2
void * padding2
Definition: spc.h:846
spcprm::err
struct wcserr * err
Definition: spc.h:842
spctype
int spctype(const char ctype[9], char stype[], char scode[], char sname[], char units[], char *ptype, char *xtype, int *restreq, struct wcserr **err)
Spectral CTYPEia keyword analysis.
spc_errmsg
const char * spc_errmsg[]
Status return messages.
spcprm::code
char code[4]
Definition: spc.h:814
spx.h
spcperr
int spcperr(const struct spcprm *spc, const char *prefix)
Print error messages from a spcprm struct.
spcspxe
int spcspxe(const char ctypeS[9], double crvalS, double restfrq, double restwav, char *ptype, char *xtype, int *restreq, double *crvalX, double *dXdS, struct wcserr **err)
Spectral keyword analysis.
spcprm::spxX2P
int(* spxX2P)(SPX_ARGS)
Definition: spc.h:847
wcserr
Error message handling.
Definition: wcserr.h:222
spctrne
int spctrne(const char ctypeS1[9], double crvalS1, double cdeltS1, double restfrq, double restwav, char ctypeS2[9], double *crvalS2, double *cdeltS2, struct wcserr **err)
Spectral keyword translation.
SPCERR_NULL_POINTER
@ SPCERR_NULL_POINTER
Definition: spc.h:798
spcprm::w
double w[6]
Definition: spc.h:831
spcprm::spxP2S
int(* spxP2S)(SPX_ARGS)
Definition: spc.h:848
spcprm::spxS2P
int(* spxS2P)(SPX_ARGS)
Definition: spc.h:851
spcx2s
int spcx2s(struct spcprm *spc, int nx, int sx, int sspec, const double x[], double spec[], int stat[])
Transform to spectral coordinates.
SPCERR_SUCCESS
@ SPCERR_SUCCESS
Definition: spc.h:797
spcxpse
int spcxpse(const char ctypeS[9], double crvalX, double restfrq, double restwav, char *ptype, char *xtype, int *restreq, double *crvalS, double *dSdX, struct wcserr **err)
Spectral keyword synthesis.
SPCERR_NO_CHANGE
@ SPCERR_NO_CHANGE
Definition: spc.h:796