WCSLIB: spc.h Source File

WCSLIB 8.4

Loading...
Searching...
No Matches
spc.h
Go to the documentation of this file.
1/*============================================================================
2 WCSLIB 8.4 - an implementation of the FITS WCS standard.
3 Copyright (C) 1995-2024, 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 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
21 http://www.atnf.csiro.au/people/Mark.Calabretta
22 $Id: spc.h,v 8.4 2024/10/28 13:56:16 mcalabre Exp $
23*=============================================================================
24*
25* WCSLIB 8.4 - C routines that implement the FITS World Coordinate System
26* (WCS) standard. Refer to the README file provided with WCSLIB for an
27* overview of the library.
28*
29*
30* Summary of the spc routines
31* ---------------------------
32* Routines in this suite implement the part of the FITS World Coordinate
33* System (WCS) standard that deals with spectral coordinates, as described in
34*
35= "Representations of world coordinates in FITS",
36= Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
37=
38= "Representations of spectral coordinates in FITS",
39= Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
40= 2006, A&A, 446, 747 (WCS Paper III)
41*
42* These routines define methods to be used for computing spectral world
43* coordinates from intermediate world coordinates (a linear transformation
44* of image pixel coordinates), and vice versa. They are based on the spcprm
45* struct which contains all information needed for the computations. The
46* struct contains some members that must be set by the user, and others that
47* are maintained by these routines, somewhat like a C++ class but with no
48* encapsulation.
49*
50* Routine spcini() is provided to initialize the spcprm struct with default
51* values, spcfree() reclaims any memory that may have been allocated to store
52* an error message, spcsize() computes its total size including allocated
53* memory, spcenq() returns information about the state of the struct, and
54* 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* spcsize() - Compute the size of a spcprm struct
216* -----------------------------------------------
217* spcsize() computes the full size of a spcprm struct, including allocated
218* memory.
219*
220* Given:
221* spc const struct spcprm*
222* Spectral transformation parameters.
223*
224* If NULL, the base size of the struct and the allocated
225* size are both set to zero.
226*
227* Returned:
228* sizes int[2] The first element is the base size of the struct as
229* returned by sizeof(struct spcprm). The second element
230* is the total allocated size, in bytes. This figure
231* includes memory allocated for the constituent struct,
232* spcprm::err.
233*
234* It is not an error for the struct not to have been set
235* up via spcset().
236*
237* Function return value:
238* int Status return value:
239* 0: Success.
240*
241*
242* spcenq() - enquire about the state of a spcprm struct
243* -----------------------------------------------------
244* spcenq() may be used to obtain information about the state of a spcprm
245* struct. The function returns a true/false answer for the enquiry asked.
246*
247* Given:
248* spc const struct spcprm*
249* Spectral transformation parameters.
250*
251* enquiry int Enquiry according to the following parameters:
252* SPCENQ_MEM: memory in the struct is being managed by
253* WCSLIB (see spcini()).
254* SPCENQ_SET: the struct has been set up by spcset().
255* SPCENQ_BYP: the struct is in bypass mode (see
256* spcset()).
257* These may be combined by logical OR, e.g.
258* SPCENQ_MEM | SPCENQ_SET. The enquiry result will be
259* the logical AND of the individual results.
260*
261* Function return value:
262* int Enquiry result:
263* 0: No.
264* 1: Yes.
265*
266*
267* spcprt() - Print routine for the spcprm struct
268* ----------------------------------------------
269* spcprt() prints the contents of a spcprm struct using wcsprintf(). Mainly
270* intended for diagnostic purposes.
271*
272* Given:
273* spc const struct spcprm*
274* Spectral transformation parameters.
275*
276* Function return value:
277* int Status return value:
278* 0: Success.
279* 1: Null spcprm pointer passed.
280*
281*
282* spcperr() - Print error messages from a spcprm struct
283* -----------------------------------------------------
284* spcperr() prints the error message(s) (if any) stored in a spcprm struct.
285* If there are no errors then nothing is printed. It uses wcserr_prt(), q.v.
286*
287* Given:
288* spc const struct spcprm*
289* Spectral transformation parameters.
290*
291* prefix const char *
292* If non-NULL, each output line will be prefixed with
293* this string.
294*
295* Function return value:
296* int Status return value:
297* 0: Success.
298* 1: Null spcprm pointer passed.
299*
300*
301* spcset() - Setup routine for the spcprm struct
302* ----------------------------------------------
303* spcset() sets up a spcprm struct according to information supplied within
304* it.
305*
306* Note that this routine need not be called directly; it will be invoked by
307* spcx2s() and spcs2x() if spcprm::flag is anything other than a predefined
308* magic value.
309*
310* spcset() normally operates regardless of the value of spcprm::flag; i.e.
311* even if a struct was previously set up it will be reset unconditionally.
312* However, a spcprm struct may be put into "bypass" mode by invoking spcset()
313* initially with spcprm::flag == 1 (rather than 0). spcset() will return
314* immediately if invoked on a struct in that state. To take a struct out of
315* bypass mode, simply reset spcprm::flag to zero. See also spcenq().
316*
317* Given and returned:
318* spc struct spcprm*
319* Spectral transformation parameters.
320*
321* Function return value:
322* int Status return value:
323* 0: Success.
324* 1: Null spcprm pointer passed.
325* 2: Invalid spectral parameters.
326*
327* For returns > 1, a detailed error message is set in
328* spcprm::err if enabled, see wcserr_enable().
329*
330*
331* spcx2s() - Transform to spectral coordinates
332* --------------------------------------------
333* spcx2s() transforms intermediate world coordinates to spectral coordinates.
334*
335* Given and returned:
336* spc struct spcprm*
337* Spectral transformation parameters.
338*
339* Given:
340* nx int Vector length.
341*
342* sx int Vector stride.
343*
344* sspec int Vector stride.
345*
346* x const double[]
347* Intermediate world coordinates, in SI units.
348*
349* Returned:
350* spec double[] Spectral coordinates, in SI units.
351*
352* stat int[] Status return value status for each vector element:
353* 0: Success.
354* 1: Invalid value of x.
355*
356* Function return value:
357* int Status return value:
358* 0: Success.
359* 1: Null spcprm pointer passed.
360* 2: Invalid spectral parameters.
361* 3: One or more of the x coordinates were invalid,
362* as indicated by the stat vector.
363*
364* For returns > 1, a detailed error message is set in
365* spcprm::err if enabled, see wcserr_enable().
366*
367*
368* spcs2x() - Transform spectral coordinates
369* -----------------------------------------
370* spcs2x() transforms spectral world coordinates to intermediate world
371* coordinates.
372*
373* Given and returned:
374* spc struct spcprm*
375* Spectral transformation parameters.
376*
377* Given:
378* nspec int Vector length.
379*
380* sspec int Vector stride.
381*
382* sx int Vector stride.
383*
384* spec const double[]
385* Spectral coordinates, in SI units.
386*
387* Returned:
388* x double[] Intermediate world coordinates, in SI units.
389*
390* stat int[] Status return value status for each vector element:
391* 0: Success.
392* 1: Invalid value of spec.
393*
394* Function return value:
395* int Status return value:
396* 0: Success.
397* 1: Null spcprm pointer passed.
398* 2: Invalid spectral parameters.
399* 4: One or more of the spec coordinates were
400* invalid, as indicated by the stat vector.
401*
402* For returns > 1, a detailed error message is set in
403* spcprm::err if enabled, see wcserr_enable().
404*
405*
406* spctype() - Spectral CTYPEia keyword analysis
407* ---------------------------------------------
408* spctype() checks whether a CTYPEia keyvalue is a valid spectral axis type
409* and if so returns information derived from it relating to the associated S-,
410* P-, and X-type spectral variables (see explanation above).
411*
412* The return arguments are guaranteed not be modified if CTYPEia is not a
413* valid spectral type; zero-pointers may be specified for any that are not of
414* interest.
415*
416* A deprecated form of this function, spctyp(), lacks the wcserr** parameter.
417*
418* Given:
419* ctype const char[9]
420* The CTYPEia keyvalue, (eight characters with null
421* termination).
422*
423* Returned:
424* stype char[] The four-letter name of the S-type spectral variable
425* copied or translated from ctype. If a non-zero
426* pointer is given, the array must accomodate a null-
427* terminated string of length 5.
428*
429* scode char[] The three-letter spectral algorithm code copied or
430* translated from ctype. Logarithmic ('LOG') and
431* tabular ('TAB') codes are also recognized. If a
432* non-zero pointer is given, the array must accomodate a
433* null-terminated string of length 4.
434*
435* sname char[] Descriptive name of the S-type spectral variable.
436* If a non-zero pointer is given, the array must
437* accomodate a null-terminated string of length 22.
438*
439* units char[] SI units of the S-type spectral variable. If a
440* non-zero pointer is given, the array must accomodate a
441* null-terminated string of length 8.
442*
443* ptype char* Character code for the P-type spectral variable
444* derived from ctype, one of 'F', 'W', 'A', or 'V'.
445*
446* xtype char* Character code for the X-type spectral variable
447* derived from ctype, one of 'F', 'W', 'A', or 'V'.
448* Also, 'w' and 'a' are synonymous to 'W' and 'A' for
449* grisms in vacuo and air respectively. Set to 'L' or
450* 'T' for logarithmic ('LOG') and tabular ('TAB') axes.
451*
452* restreq int* Multivalued flag that indicates whether rest
453* frequency or wavelength is required to compute
454* spectral variables for this CTYPEia:
455* 0: Not required.
456* 1: Required for the conversion between S- and
457* P-types (e.g. 'ZOPT-F2W').
458* 2: Required for the conversion between P- and
459* X-types (e.g. 'BETA-W2V').
460* 3: Required for the conversion between S- and
461* P-types, and between P- and X-types, but not
462* between S- and X-types (this applies only for
463* 'VRAD-V2F', 'VOPT-V2W', and 'ZOPT-V2W').
464* Thus the rest frequency or wavelength is required for
465* spectral coordinate computations (i.e. between S- and
466* X-types) only if restreq%3 != 0.
467*
468* err struct wcserr **
469* If enabled, for function return values > 1, this
470* struct will contain a detailed error message, see
471* wcserr_enable(). May be NULL if an error message is
472* not desired. Otherwise, the user is responsible for
473* deleting the memory allocated for the wcserr struct.
474*
475* Function return value:
476* int Status return value:
477* 0: Success.
478* 2: Invalid spectral parameters (not a spectral
479* CTYPEia).
480*
481*
482* spcspxe() - Spectral keyword analysis
483* ------------------------------------
484* spcspxe() analyses the CTYPEia and CRVALia FITS spectral axis keyword values
485* and returns information about the associated X-type spectral variable.
486*
487* A deprecated form of this function, spcspx(), lacks the wcserr** parameter.
488*
489* Given:
490* ctypeS const char[9]
491* Spectral axis type, i.e. the CTYPEia keyvalue, (eight
492* characters with null termination). For non-grism
493* axes, the character code for the P-type spectral
494* variable in the algorithm code (i.e. the eighth
495* character of CTYPEia) may be set to '?' (it will not
496* be reset).
497*
498* crvalS double Value of the S-type spectral variable at the reference
499* point, i.e. the CRVALia keyvalue, SI units.
500*
501* restfrq,
502* restwav double Rest frequency [Hz] and rest wavelength in vacuo [m],
503* only one of which need be given, the other should be
504* set to zero.
505*
506* Returned:
507* ptype char* Character code for the P-type spectral variable
508* derived from ctypeS, one of 'F', 'W', 'A', or 'V'.
509*
510* xtype char* Character code for the X-type spectral variable
511* derived from ctypeS, one of 'F', 'W', 'A', or 'V'.
512* Also, 'w' and 'a' are synonymous to 'W' and 'A' for
513* grisms in vacuo and air respectively; crvalX and dXdS
514* (see below) will conform to these.
515*
516* restreq int* Multivalued flag that indicates whether rest frequency
517* or wavelength is required to compute spectral
518* variables for this CTYPEia, as for spctype().
519*
520* crvalX double* Value of the X-type spectral variable at the reference
521* point, SI units.
522*
523* dXdS double* The derivative, dX/dS, evaluated at the reference
524* point, SI units. Multiply the CDELTia keyvalue by
525* this to get the pixel spacing in the X-type spectral
526* coordinate.
527*
528* err struct wcserr **
529* If enabled, for function return values > 1, this
530* struct will contain a detailed error message, see
531* wcserr_enable(). May be NULL if an error message is
532* not desired. Otherwise, the user is responsible for
533* deleting the memory allocated for the wcserr struct.
534*
535* Function return value:
536* int Status return value:
537* 0: Success.
538* 2: Invalid spectral parameters.
539*
540*
541* spcxpse() - Spectral keyword synthesis
542* -------------------------------------
543* spcxpse(), for the spectral axis type specified and the value provided for
544* the X-type spectral variable at the reference point, deduces the value of
545* the FITS spectral axis keyword CRVALia and also the derivative dS/dX which
546* may be used to compute CDELTia. See above for an explanation of the S-,
547* P-, and X-type spectral variables.
548*
549* A deprecated form of this function, spcxps(), lacks the wcserr** parameter.
550*
551* Given:
552* ctypeS const char[9]
553* The required spectral axis type, i.e. the CTYPEia
554* keyvalue, (eight characters with null termination).
555* For non-grism axes, the character code for the P-type
556* spectral variable in the algorithm code (i.e. the
557* eighth character of CTYPEia) may be set to '?' (it
558* will not be reset).
559*
560* crvalX double Value of the X-type spectral variable at the reference
561* point (N.B. NOT the CRVALia keyvalue), SI units.
562*
563* restfrq,
564* restwav double Rest frequency [Hz] and rest wavelength in vacuo [m],
565* only one of which need be given, the other should be
566* set to zero.
567*
568* Returned:
569* ptype char* Character code for the P-type spectral variable
570* derived from ctypeS, one of 'F', 'W', 'A', or 'V'.
571*
572* xtype char* Character code for the X-type spectral variable
573* derived from ctypeS, one of 'F', 'W', 'A', or 'V'.
574* Also, 'w' and 'a' are synonymous to 'W' and 'A' for
575* grisms; crvalX and cdeltX must conform to these.
576*
577* restreq int* Multivalued flag that indicates whether rest frequency
578* or wavelength is required to compute spectral
579* variables for this CTYPEia, as for spctype().
580*
581* crvalS double* Value of the S-type spectral variable at the reference
582* point (i.e. the appropriate CRVALia keyvalue), SI
583* units.
584*
585* dSdX double* The derivative, dS/dX, evaluated at the reference
586* point, SI units. Multiply this by the pixel spacing
587* in the X-type spectral coordinate to get the CDELTia
588* keyvalue.
589*
590* err struct wcserr **
591* If enabled, for function return values > 1, this
592* struct will contain a detailed error message, see
593* wcserr_enable(). May be NULL if an error message is
594* not desired. Otherwise, the user is responsible for
595* deleting the memory allocated for the wcserr struct.
596*
597* Function return value:
598* int Status return value:
599* 0: Success.
600* 2: Invalid spectral parameters.
601*
602*
603* spctrne() - Spectral keyword translation
604* ---------------------------------------
605* spctrne() translates a set of FITS spectral axis keywords into the
606* corresponding set for the specified spectral axis type. For example, a
607* 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.
608*
609* A deprecated form of this function, spctrn(), lacks the wcserr** parameter.
610*
611* Given:
612* ctypeS1 const char[9]
613* Spectral axis type, i.e. the CTYPEia keyvalue, (eight
614* characters with null termination). For non-grism
615* axes, the character code for the P-type spectral
616* variable in the algorithm code (i.e. the eighth
617* character of CTYPEia) may be set to '?' (it will not
618* be reset).
619*
620* crvalS1 double Value of the S-type spectral variable at the reference
621* point, i.e. the CRVALia keyvalue, SI units.
622*
623* cdeltS1 double Increment of the S-type spectral variable at the
624* reference point, SI units.
625*
626* restfrq,
627* restwav double Rest frequency [Hz] and rest wavelength in vacuo [m],
628* only one of which need be given, the other should be
629* set to zero. Neither are required if the translation
630* is between wave-characteristic types, or between
631* velocity-characteristic types. E.g., required for
632* 'FREQ' -> 'ZOPT-F2W', but not required for
633* 'VELO-F2V' -> 'ZOPT-F2W'.
634*
635* Given and returned:
636* ctypeS2 char[9] Required spectral axis type (eight characters with
637* null termination). The first four characters are
638* required to be given and are never modified. The
639* remaining four, the algorithm code, are completely
640* determined by, and must be consistent with, ctypeS1
641* and the first four characters of ctypeS2. A non-zero
642* status value will be returned if they are inconsistent
643* (see below). However, if the final three characters
644* are specified as "???", or if just the eighth
645* character is specified as '?', the correct algorithm
646* code will be substituted (applies for grism axes as
647* well as non-grism).
648*
649* Returned:
650* crvalS2 double* Value of the new S-type spectral variable at the
651* reference point, i.e. the new CRVALia keyvalue, SI
652* units.
653*
654* cdeltS2 double* Increment of the new S-type spectral variable at the
655* reference point, i.e. the new CDELTia keyvalue, SI
656* units.
657*
658* err struct wcserr **
659* If enabled, for function return values > 1, this
660* struct will contain a detailed error message, see
661* wcserr_enable(). May be NULL if an error message is
662* not desired. Otherwise, the user is responsible for
663* deleting the memory allocated for the wcserr struct.
664*
665* Function return value:
666* int Status return value:
667* 0: Success.
668* 2: Invalid spectral parameters.
669*
670* A status value of 2 will be returned if restfrq or
671* restwav are not specified when required, or if ctypeS1
672* or ctypeS2 are self-inconsistent, or have different
673* spectral X-type variables.
674*
675*
676* spcaips() - Translate AIPS-convention spectral keywords
677* -------------------------------------------------------
678* spcaips() translates AIPS-convention spectral CTYPEia and VELREF keyvalues.
679*
680* Given:
681* ctypeA const char[9]
682* CTYPEia keyvalue possibly containing an
683* AIPS-convention spectral code (eight characters, need
684* not be null-terminated).
685*
686* velref int AIPS-convention VELREF code. It has the following
687* integer values:
688* 1: LSR kinematic, originally described simply as
689* "LSR" without distinction between the kinematic
690* and dynamic definitions.
691* 2: Barycentric, originally described as "HEL"
692* meaning heliocentric.
693* 3: Topocentric, originally described as "OBS"
694* meaning geocentric but widely interpreted as
695* topocentric.
696* AIPS++ extensions to VELREF are also recognized:
697* 4: LSR dynamic.
698* 5: Geocentric.
699* 6: Source rest frame.
700* 7: Galactocentric.
701*
702* For an AIPS 'VELO' axis, a radio convention velocity
703* (VRAD) is denoted by adding 256 to VELREF, otherwise
704* an optical velocity (VOPT) is indicated (this is not
705* applicable to 'FREQ' or 'FELO' axes). Setting velref
706* to 0 or 256 chooses between optical and radio velocity
707* without specifying a Doppler frame, provided that a
708* frame is encoded in ctypeA. If not, i.e. for
709* ctypeA = 'VELO', ctype will be returned as 'VELO'.
710*
711* VELREF takes precedence over CTYPEia in defining the
712* Doppler frame, e.g.
713*
714= ctypeA = 'VELO-HEL'
715= velref = 1
716*
717* returns ctype = 'VOPT' with specsys set to 'LSRK'.
718*
719* If omitted from the header, the default value of
720* VELREF is 0.
721*
722* Returned:
723* ctype char[9] Translated CTYPEia keyvalue, or a copy of ctypeA if no
724* translation was performed (in which case any trailing
725* blanks in ctypeA will be replaced with nulls).
726*
727* specsys char[9] Doppler reference frame indicated by VELREF or else
728* by CTYPEia with value corresponding to the SPECSYS
729* keyvalue in the FITS WCS standard. May be returned
730* blank if neither specifies a Doppler frame, e.g.
731* ctypeA = 'FELO' and velref%256 == 0.
732*
733* Function return value:
734* int Status return value:
735* -1: No translation required (not an error).
736* 0: Success.
737* 2: Invalid value of VELREF.
738*
739*
740* spcprm struct - Spectral transformation parameters
741* --------------------------------------------------
742* The spcprm struct contains information required to transform spectral
743* coordinates. It consists of certain members that must be set by the user
744* ("given") and others that are set by the WCSLIB routines ("returned"). Some
745* of the latter are supplied for informational purposes while others are for
746* internal use only.
747*
748* int flag
749* (Given and returned) This flag must be set to zero (or 1, see spcset())
750* whenever any of the following spcprm members are set or changed:
751*
752* - spcprm::type,
753* - spcprm::code,
754* - spcprm::crval,
755* - spcprm::restfrq,
756* - spcprm::restwav,
757* - spcprm::pv[].
758*
759* This signals the initialization routine, spcset(), to recompute the
760* returned members of the spcprm struct. spcset() will reset flag to
761* indicate that this has been done.
762*
763* char type[8]
764* (Given) Four-letter spectral variable type, e.g "ZOPT" for
765* CTYPEia = 'ZOPT-F2W'. (Declared as char[8] for alignment reasons.)
766*
767* char code[4]
768* (Given) Three-letter spectral algorithm code, e.g "F2W" for
769* CTYPEia = 'ZOPT-F2W'.
770*
771* double crval
772* (Given) Reference value (CRVALia), SI units.
773*
774* double restfrq
775* (Given) The rest frequency [Hz], and ...
776*
777* double restwav
778* (Given) ... the rest wavelength in vacuo [m], only one of which need be
779* given, the other should be set to zero. Neither are required if the
780* X and S spectral variables are both wave-characteristic, or both
781* velocity-characteristic, types.
782*
783* double pv[7]
784* (Given) Grism parameters for 'GRI' and 'GRA' algorithm codes:
785* - 0: G, grating ruling density.
786* - 1: m, interference order.
787* - 2: alpha, angle of incidence [deg].
788* - 3: n_r, refractive index at the reference wavelength, lambda_r.
789* - 4: n'_r, dn/dlambda at the reference wavelength, lambda_r (/m).
790* - 5: epsilon, grating tilt angle [deg].
791* - 6: theta, detector tilt angle [deg].
792*
793* The remaining members of the spcprm struct are maintained by spcset() and
794* must not be modified elsewhere:
795*
796* double w[6]
797* (Returned) Intermediate values:
798* - 0: Rest frequency or wavelength (SI).
799* - 1: The value of the X-type spectral variable at the reference point
800* (SI units).
801* - 2: dX/dS at the reference point (SI units).
802* The remainder are grism intermediates.
803*
804* int isGrism
805* (Returned) Grism coordinates?
806* - 0: no,
807* - 1: in vacuum,
808* - 2: in air.
809*
810* int padding1
811* (An unused variable inserted for alignment purposes only.)
812*
813* struct wcserr *err
814* (Returned) If enabled, when an error status is returned, this struct
815* contains detailed information about the error, see wcserr_enable().
816*
817* void *padding2
818* (An unused variable inserted for alignment purposes only.)
819* int (*spxX2P)(SPX_ARGS)
820* (For internal use only) The first and ...
821* int (*spxP2S)(SPX_ARGS)
822* (For internal use only) ... the second of the pointers to the
823* transformation functions in the two-step algorithm chain X -> P -> S in
824* the pixel-to-spectral direction where the non-linear transformation is
825* from X to P. The argument list, SPX_ARGS, is defined in spx.h.
826*
827* int (*spxS2P)(SPX_ARGS)
828* (For internal use only) The first and ...
829* int (*spxP2X)(SPX_ARGS)
830* (For internal use only) ... the second of the pointers to the
831* transformation functions in the two-step algorithm chain S -> P -> X in
832* the spectral-to-pixel direction where the non-linear transformation is
833* from P to X. The argument list, SPX_ARGS, is defined in spx.h.
834*
835*
836* Global variable: const char *spc_errmsg[] - Status return messages
837* ------------------------------------------------------------------
838* Error messages to match the status value returned from each function.
839*
840*===========================================================================*/
841
842#ifndef WCSLIB_SPC
843#define WCSLIB_SPC
844
845#include "spx.h"
846
847#ifdef __cplusplus
848 extern "C" {
849#endif
850
851 enum spcenq_enum {
852 SPCENQ_SET = 2, // spcprm struct has been set up.
853 SPCENQ_BYP = 4, // spcprm struct is in bypass mode.
854};
855
856 extern const char *spc_errmsg[];
857
858 enum spc_errmsg_enum {
859 SPCERR_NO_CHANGE = -1, // No change.
860 SPCERR_SUCCESS = 0, // Success.
861 SPCERR_NULL_POINTER = 1, // Null spcprm pointer passed.
862 SPCERR_BAD_SPEC_PARAMS = 2, // Invalid spectral parameters.
863 SPCERR_BAD_X = 3, // One or more of x coordinates were
864 // invalid.
865 SPCERR_BAD_SPEC = 4 // One or more of the spec coordinates were
866 // invalid.
867};
868
869 struct spcprm {
870 // Initialization flag (see the prologue above).
871 //--------------------------------------------------------------------------
872 int flag; // Set to zero to force initialization.
873
874 // Parameters to be provided (see the prologue above).
875 //--------------------------------------------------------------------------
876 char type[8]; // Four-letter spectral variable type.
877 char code[4]; // Three-letter spectral algorithm code.
878
879 double crval; // Reference value (CRVALia), SI units.
880 double restfrq; // Rest frequency, Hz.
881 double restwav; // Rest wavelength, m.
882
883 double pv[7]; // Grism parameters:
884 // 0: G, grating ruling density.
885 // 1: m, interference order.
886 // 2: alpha, angle of incidence.
887 // 3: n_r, refractive index at lambda_r.
888 // 4: n'_r, dn/dlambda at lambda_r.
889 // 5: epsilon, grating tilt angle.
890 // 6: theta, detector tilt angle.
891
892 // Information derived from the parameters supplied.
893 //--------------------------------------------------------------------------
894 double w[6]; // Intermediate values.
895 // 0: Rest frequency or wavelength (SI).
896 // 1: CRVALX (SI units).
897 // 2: CDELTX/CDELTia = dX/dS (SI units).
898 // The remainder are grism intermediates.
899
900 int isGrism; // Grism coordinates? 1: vacuum, 2: air.
901 int padding1; // (Dummy inserted for alignment purposes.)
902
903 // Error messaging, if enabled.
904 //--------------------------------------------------------------------------
905 struct wcserr *err;
906
907 //--------------------------------------------------------------------------
908 // Private - the remainder are for internal use.
909 //--------------------------------------------------------------------------
910 void *padding2; // (Dummy inserted for alignment purposes.)
911
912 int (*spxX2P)(SPX_ARGS); // Pointers to the transformation functions
913 int (*spxP2S)(SPX_ARGS); // in the two-step algorithm chain in the
914 // pixel-to-spectral direction.
915
916 int (*spxS2P)(SPX_ARGS); // Pointers to the transformation functions
917 int (*spxP2X)(SPX_ARGS); // in the two-step algorithm chain in the
918 // spectral-to-pixel direction.
919};
920
921// Size of the spcprm struct in int units, used by the Fortran wrappers.
922#define SPCLEN (sizeof(struct spcprm)/sizeof(int))
923
924
925 int spcini(struct spcprm *spc);
926
927 int spcfree(struct spcprm *spc);
928
929 int spcsize(const struct spcprm *spc, int sizes[2]);
930
931 int spcenq(const struct spcprm *spc, int enquiry);
932
933 int spcprt(const struct spcprm *spc);
934
935 int spcperr(const struct spcprm *spc, const char *prefix);
936
937 int spcset(struct spcprm *spc);
938
939 int spcx2s(struct spcprm *spc, int nx, int sx, int sspec,
940 const double x[], double spec[], int stat[]);
941
942 int spcs2x(struct spcprm *spc, int nspec, int sspec, int sx,
943 const double spec[], double x[], int stat[]);
944
945 int spctype(const char ctype[9], char stype[], char scode[], char sname[],
946 char units[], char *ptype, char *xtype, int *restreq,
947 struct wcserr **err);
948
949 int spcspxe(const char ctypeS[9], double crvalS, double restfrq,
950 double restwav, char *ptype, char *xtype, int *restreq,
951 double *crvalX, double *dXdS, struct wcserr **err);
952
953 int spcxpse(const char ctypeS[9], double crvalX, double restfrq,
954 double restwav, char *ptype, char *xtype, int *restreq,
955 double *crvalS, double *dSdX, struct wcserr **err);
956
957 int spctrne(const char ctypeS1[9], double crvalS1, double cdeltS1,
958 double restfrq, double restwav, char ctypeS2[9], double *crvalS2,
959 double *cdeltS2, struct wcserr **err);
960
961 int spcaips(const char ctypeA[9], int velref, char ctype[9], char specsys[9]);
962
963
964// Deprecated.
965#define spcini_errmsg spc_errmsg
966#define spcprt_errmsg spc_errmsg
967#define spcset_errmsg spc_errmsg
968#define spcx2s_errmsg spc_errmsg
969#define spcs2x_errmsg spc_errmsg
970
971 int spctyp(const char ctype[9], char stype[], char scode[], char sname[],
972 char units[], char *ptype, char *xtype, int *restreq);
973 int spcspx(const char ctypeS[9], double crvalS, double restfrq,
974 double restwav, char *ptype, char *xtype, int *restreq,
975 double *crvalX, double *dXdS);
976 int spcxps(const char ctypeS[9], double crvalX, double restfrq,
977 double restwav, char *ptype, char *xtype, int *restreq,
978 double *crvalS, double *dSdX);
979 int spctrn(const char ctypeS1[9], double crvalS1, double cdeltS1,
980 double restfrq, double restwav, char ctypeS2[9], double *crvalS2,
981 double *cdeltS2);
982
983#ifdef __cplusplus
984}
985#endif
986
987#endif // WCSLIB_SPC
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.
spcsize
int spcsize(const struct spcprm *spc, int sizes[2])
Compute the size of a spcprm struct.
spcfree
int spcfree(struct spcprm *spc)
Destructor for the spcprm struct.
spcini
int spcini(struct spcprm *spc)
Default constructor for the spcprm struct.
spcenq_enum
spcenq_enum
Definition spc.h:851
SPCENQ_BYP
@ SPCENQ_BYP
Definition spc.h:853
SPCENQ_SET
@ SPCENQ_SET
Definition spc.h:852
spcperr
int spcperr(const struct spcprm *spc, const char *prefix)
Print error messages from a spcprm struct.
spctrn
int spctrn(const char ctypeS1[9], double crvalS1, double cdeltS1, double restfrq, double restwav, char ctypeS2[9], double *crvalS2, double *cdeltS2)
spc_errmsg_enum
spc_errmsg_enum
Definition spc.h:858
SPCERR_BAD_SPEC_PARAMS
@ SPCERR_BAD_SPEC_PARAMS
Definition spc.h:862
SPCERR_SUCCESS
@ SPCERR_SUCCESS
Definition spc.h:860
SPCERR_BAD_X
@ SPCERR_BAD_X
Definition spc.h:863
SPCERR_NULL_POINTER
@ SPCERR_NULL_POINTER
Definition spc.h:861
SPCERR_BAD_SPEC
@ SPCERR_BAD_SPEC
Definition spc.h:865
SPCERR_NO_CHANGE
@ SPCERR_NO_CHANGE
Definition spc.h:859
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.
spcspx
int spcspx(const char ctypeS[9], double crvalS, double restfrq, double restwav, char *ptype, char *xtype, int *restreq, double *crvalX, double *dXdS)
spcprt
int spcprt(const struct spcprm *spc)
Print routine for the spcprm struct.
spcxps
int spcxps(const char ctypeS[9], double crvalX, double restfrq, double restwav, char *ptype, char *xtype, int *restreq, double *crvalS, double *dSdX)
spctyp
int spctyp(const char ctype[9], char stype[], char scode[], char sname[], char units[], char *ptype, char *xtype, int *restreq)
spcaips
int spcaips(const char ctypeA[9], int velref, char ctype[9], char specsys[9])
Translate AIPS-convention spectral keywords.
spcenq
int spcenq(const struct spcprm *spc, int enquiry)
enquire about the state of a spcprm struct.
spcs2x
int spcs2x(struct spcprm *spc, int nspec, int sspec, int sx, const double spec[], double x[], int stat[])
Transform spectral coordinates.
spcx2s
int spcx2s(struct spcprm *spc, int nx, int sx, int sspec, const double x[], double spec[], int stat[])
Transform to spectral coordinates.
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.
spcset
int spcset(struct spcprm *spc)
Setup routine for the spcprm struct.
spc_errmsg
const char * spc_errmsg[]
Status return messages.
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.
spx.h
SPX_ARGS
#define SPX_ARGS
For use in declaring spectral conversion function prototypes.
Definition spx.h:541
spcprm
Spectral transformation parameters.
Definition spc.h:869
spcprm::spxP2S
int(* spxP2S)(SPX_ARGS)
Definition spc.h:913
spcprm::crval
double crval
Definition spc.h:879
spcprm::code
char code[4]
Definition spc.h:877
spcprm::restwav
double restwav
Definition spc.h:881
spcprm::padding2
void * padding2
Definition spc.h:910
spcprm::spxP2X
int(* spxP2X)(SPX_ARGS)
Definition spc.h:917
spcprm::spxX2P
int(* spxX2P)(SPX_ARGS)
Definition spc.h:912
spcprm::restfrq
double restfrq
Definition spc.h:880
spcprm::padding1
int padding1
Definition spc.h:901
spcprm::spxS2P
int(* spxS2P)(SPX_ARGS)
Definition spc.h:916
spcprm::type
char type[8]
Definition spc.h:876
spcprm::err
struct wcserr * err
Definition spc.h:905
spcprm::w
double w[6]
Definition spc.h:894
spcprm::pv
double pv[7]
Definition spc.h:883
spcprm::isGrism
int isGrism
Definition spc.h:900
spcprm::flag
int flag
Definition spc.h:872
wcserr
Error message handling.
Definition wcserr.h:243