1/*============================================================================
2
3 WCSLIB 4.23 - an implementation of the FITS WCS standard.
4 Copyright (C) 1995-2014, Mark Calabretta
5
6 This file is part of WCSLIB.
7
8 WCSLIB is free software: you can redistribute it and/or modify it under the
9 terms of the GNU Lesser General Public License as published by the Free
10 Software Foundation, either version 3 of the License, or (at your option)
11 any later version.
12
13 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
14 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
16 more details.
17
18 You should have received a copy of the GNU Lesser General Public License
19 along with WCSLIB. If not, see http://www.gnu.org/licenses.
20
21 Direct correspondence concerning WCSLIB to mark@calabretta.id.au
22
23 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
24 http://www.atnf.csiro.au/people/Mark.Calabretta
25 $Id: wcs.h,v 4.23 2014/05/13 05:50:51 mcalabre Exp $
26*=============================================================================
27*
28* WCSLIB 4.23 - C routines that implement the FITS World Coordinate System
29* (WCS) standard. Refer to
30*
31* "Representations of world coordinates in FITS",
32* Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
33*
34* "Representations of celestial coordinates in FITS",
35* Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (Paper II)
36*
37* "Representations of spectral coordinates in FITS",
38* Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
39* 2006, A&A, 446, 747 (Paper III)
40*
41* Refer to the README file provided with WCSLIB for an overview of the
42* library.
43*
44*
45* Summary of the wcs routines
46* ---------------------------
47* These routines implement the FITS World Coordinate System (WCS) standard
48* which defines methods to be used for computing world coordinates from image
49* pixel coordinates, and vice versa. They are based on the wcsprm struct
50* which contains all information needed for the computations. The struct
51* contains some members that must be set by the user, and others that are
52* maintained by these routines, somewhat like a C++ class but with no
53* encapsulation.
54*
55* Three routines, wcsini(), wcssub(), and wcsfree() are provided to manage the
56* wcsprm struct and another, wcsprt(), to prints its contents. Refer to the
57* description of the wcsprm struct for an explanation of the anticipated usage
58* of these routines. wcscopy(), which does a deep copy of one wcsprm struct
59* to another, is defined as a preprocessor macro function that invokes
60* wcssub().
61*
62* wcsperr() prints the error message(s) (if any) stored in a wcsprm struct,
63* and the linprm, celprm, prjprm, spcprm, and tabprm structs that it contains.
64*
65* A setup routine, wcsset(), computes intermediate values in the wcsprm struct
66* from parameters in it that were supplied by the user. The struct always
67* needs to be set up by wcsset() but this need not be called explicitly -
68* refer to the explanation of wcsprm::flag.
69*
70* wcsp2s() and wcss2p() implement the WCS world coordinate transformations.
71* In fact, they are high level driver routines for the WCS linear,
72* logarithmic, celestial, spectral and tabular transformation routines
73* described in lin.h, log.h, cel.h, spc.h and tab.h.
74*
75* Given either the celestial longitude or latitude plus an element of the
76* pixel coordinate a hybrid routine, wcsmix(), iteratively solves for the
77* unknown elements.
78*
79* wcssptr() translates the spectral axis in a wcsprm struct. For example, a
80* 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.
81*
82* Quadcube projections:
83* ---------------------
84* The quadcube projections (TSC, CSC, QSC) may be represented in FITS in
85* either of two ways:
86*
87* a: The six faces may be laid out in one plane and numbered as follows:
88*
89= 0
90=
91= 4 3 2 1 4 3 2
92=
93= 5
94*
95* Faces 2, 3 and 4 may appear on one side or the other (or both). The
96* world-to-pixel routines map faces 2, 3 and 4 to the left but the
97* pixel-to-world routines accept them on either side.
98*
99* b: The "COBE" convention in which the six faces are stored in a
100* three-dimensional structure using a CUBEFACE axis indexed from
101* 0 to 5 as above.
102*
103* These routines support both methods; wcsset() determines which is being
104* used by the presence or absence of a CUBEFACE axis in ctype[]. wcsp2s()
105* and wcss2p() translate the CUBEFACE axis representation to the single
106* plane representation understood by the lower-level WCSLIB projection
107* routines.
108*
109*
110* wcsini() - Default constructor for the wcsprm struct
111* ----------------------------------------------------
112* wcsini() optionally allocates memory for arrays in a wcsprm struct and sets
113* all members of the struct to default values. Memory is allocated for up to
114* NPVMAX PVi_ma keywords or NPSMAX PSi_ma keywords per WCS representation.
115* These may be changed via wcsnpv() and wcsnps() before wcsini() is called.
116*
117* PLEASE NOTE: every wcsprm struct should be initialized by wcsini(), possibly
118* repeatedly. On the first invokation, and only the first invokation,
119* wcsprm::flag must be set to -1 to initialize memory management, regardless
120* of whether wcsini() will actually be used to allocate memory.
121*
122* Given:
123* alloc int If true, allocate memory unconditionally for the
124* crpix, etc. arrays.
125*
126* If false, it is assumed that pointers to these arrays
127* have been set by the user except if they are null
128* pointers in which case memory will be allocated for
129* them regardless. (In other words, setting alloc true
130* saves having to initalize these pointers to zero.)
131*
132* naxis int The number of world coordinate axes. This is used to
133* determine the length of the various wcsprm vectors and
134* matrices and therefore the amount of memory to
135* allocate for them.
136*
137* Given and returned:
138* wcs struct wcsprm*
139* Coordinate transformation parameters.
140*
141* Note that, in order to initialize memory management,
142* wcsprm::flag should be set to -1 when wcs is
143* initialized for the first time (memory leaks may
144* result if it had already been initialized).
145*
146* Function return value:
147* int Status return value:
148* 0: Success.
149* 1: Null wcsprm pointer passed.
150* 2: Memory allocation failed.
151*
152* For returns > 1, a detailed error message is set in
153* wcsprm::err if enabled, see wcserr_enable().
154*
155*
156* wcsnpv() - Memory allocation for PVi_ma
157* ---------------------------------------
158* wcsnpv() changes the value of NPVMAX (default 64). This global variable
159* controls the number of PVi_ma keywords that wcsini() should allocate space
160* for.
161*
162* PLEASE NOTE: This function is not thread-safe.
163*
164* Given:
165* n int Value of NPVMAX; ignored if < 0.
166*
167* Function return value:
168* int Current value of NPVMAX.
169*
170*
171* wcsnps() - Memory allocation for PSi_ma
172* ---------------------------------------
173* wcsnps() changes the values of NPSMAX (default 8). This global variable
174* controls the number of PSi_ma keywords that wcsini() should allocate space
175* for.
176*
177* PLEASE NOTE: This function is not thread-safe.
178*
179* Given:
180* n int Value of NPSMAX; ignored if < 0.
181*
182* Function return value:
183* int Current value of NPSMAX.
184*
185*
186* wcssub() - Subimage extraction routine for the wcsprm struct
187* ------------------------------------------------------------
188* wcssub() extracts the coordinate description for a subimage from a wcsprm
189* struct. It does a deep copy, using wcsini() to allocate memory for its
190* arrays if required. Only the "information to be provided" part of the
191* struct is extracted; a call to wcsset() is required to set up the remainder.
192*
193* The world coordinate system of the subimage must be separable in the sense
194* that the world coordinates at any point in the subimage must depend only on
195* the pixel coordinates of the axes extracted. In practice, this means that
196* the PCi_ja matrix of the original image must not contain non-zero
197* off-diagonal terms that associate any of the subimage axes with any of the
198* non-subimage axes.
199*
200* Note that while the required elements of the tabprm array are extracted, the
201* wtbarr array is not. (Thus it is not appropriate to call wcssub() after
202* wcstab() but before filling the tabprm structs - refer to wcshdr.h.)
203*
204* wcssub() can also add axes to a wcsprm struct. The new axes will be created
205* using the defaults set by wcsini() which produce a simple, unnamed, linear
206* axis with world coordinate equal to the pixel coordinate. These default
207* values can be changed afterwards, before invoking wcsset().
208*
209* Given:
210* alloc int If true, allocate memory for the crpix, etc. arrays in
211* the destination. Otherwise, it is assumed that
212* pointers to these arrays have been set by the user
213* except if they are null pointers in which case memory
214* will be allocated for them regardless.
215*
216* wcssrc const struct wcsprm*
217* Struct to extract from.
218*
219* Given and returned:
220* nsub int*
221* axes int[] Vector of length *nsub containing the image axis
222* numbers (1-relative) to extract. Order is
223* significant; axes[0] is the axis number of the input
224* image that corresponds to the first axis in the
225* subimage, etc.
226*
227* Use an axis number of 0 to create a new axis using
228* the defaults set by wcsini(). They can be changed
229* later.
230*
231* nsub (the pointer) may be set to zero, and so also may
232* *nsub, which is interpreted to mean all axes in the
233* input image; the number of axes will be returned if
234* nsub != 0x0. axes itself (the pointer) may be set to
235* zero to indicate the first *nsub axes in their
236* original order.
237*
238* Set both nsub (or *nsub) and axes to zero to do a deep
239* copy of one wcsprm struct to another.
240*
241* Subimage extraction by coordinate axis type may be
242* done by setting the elements of axes[] to the
243* following special preprocessor macro values:
244*
245* WCSSUB_LONGITUDE: Celestial longitude.
246* WCSSUB_LATITUDE: Celestial latitude.
247* WCSSUB_CUBEFACE: Quadcube CUBEFACE axis.
248* WCSSUB_SPECTRAL: Spectral axis.
249* WCSSUB_STOKES: Stokes axis.
250*
251* Refer to the notes (below) for further usage examples.
252*
253* On return, *nsub will be set to the number of axes in
254* the subimage; this may be zero if there were no axes
255* of the required type(s) (in which case no memory will
256* be allocated). axes[] will contain the axis numbers
257* that were extracted, or 0 for newly created axes. The
258* vector length must be sufficient to contain all axis
259* numbers. No checks are performed to verify that the
260* coordinate axes are consistent, this is done by
261* wcsset().
262*
263* wcsdst struct wcsprm*
264* Struct describing the subimage. wcsprm::flag should
265* be set to -1 if wcsdst was not previously initialized
266* (memory leaks may result if it was previously
267* initialized).
268*
269* Function return value:
270* int Status return value:
271* 0: Success.
272* 1: Null wcsprm pointer passed.
273* 2: Memory allocation failed.
274* 12: Invalid subimage specification.
275* 13: Non-separable subimage coordinate system.
276*
277* For returns > 1, a detailed error message is set in
278* wcsprm::err if enabled, see wcserr_enable().
279*
280* Notes:
281* Combinations of subimage axes of particular types may be extracted in the
282* same order as they occur in the input image by combining preprocessor
283* codes, for example
284*
285= *nsub = 1;
286= axes[0] = WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_SPECTRAL;
287*
288* would extract the longitude, latitude, and spectral axes in the same order
289* as the input image. If one of each were present, *nsub = 3 would be
290* returned.
291*
292* For convenience, WCSSUB_CELESTIAL is defined as the combination
293* WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_CUBEFACE.
294*
295* The codes may also be negated to extract all but the types specified, for
296* example
297*
298= *nsub = 4;
299= axes[0] = WCSSUB_LONGITUDE;
300= axes[1] = WCSSUB_LATITUDE;
301= axes[2] = WCSSUB_CUBEFACE;
302= axes[3] = -(WCSSUB_SPECTRAL | WCSSUB_STOKES);
303*
304* The last of these specifies all axis types other than spectral or Stokes.
305* Extraction is done in the order specified by axes[] a longitude axis (if
306* present) would be extracted first (via axes[0]) and not subsequently (via
307* axes[3]). Likewise for the latitude and cubeface axes in this example.
308*
309* From the foregoing, it is apparent that the value of *nsub returned may be
310* less than or greater than that given. However, it will never exceed the
311* number of axes in the input image (plus the number of newly-created axes
312* if any were specified on input).
313*
314*
315* wcscompare() - Compare two wcsprm structs for equality
316* ------------------------------------------------------
317* wcscompare() compares two wcsprm structs for equality.
318*
319* Given:
320* cmp int A bit field controlling the strictness of the
321* comparison. When 0, all fields must be identical.
322*
323* The following constants may be or'ed together to
324* relax the comparison:
325* WCSCOMPARE_ANCILLARY: Ignore ancillary keywords
326* that don't change the WCS transformation, such
327* as DATE-OBS or EQUINOX.
328* WCSCOMPARE_TILING: Ignore integral differences in
329* CRPIXja. This is the 'tiling' condition, where
330* two WCSes cover different regions of the same
331* map projection and align on the same map grid.
332* WCSCOMPARE_CRPIX: Ignore any differences at all in
333* CRPIXja. The two WCSes cover different regions
334* of the same map projection but may not align on
335* the same grid map. Overrides WCSCOMPARE_TILING.
336*
337* wcs1 const struct wcsprm*
338* The first wcsprm struct to compare.
339*
340* wcs2 const struct wcsprm*
341* The second wcsprm struct to compare.
342*
343* Returned:
344* equal int* Non-zero when the given structs are equal.
345*
346* Function return value:
347* int Status return value:
348* 0: Success.
349* 1: Null pointer passed.
350*
351*
352* wcscopy() macro - Copy routine for the wcsprm struct
353* ----------------------------------------------------
354* wcscopy() does a deep copy of one wcsprm struct to another. As of
355* WCSLIB 3.6, it is implemented as a preprocessor macro that invokes
356* wcssub() with the nsub and axes pointers both set to zero.
357*
358*
359* wcsfree() - Destructor for the wcsprm struct
360* --------------------------------------------
361* wcsfree() frees memory allocated for the wcsprm arrays by wcsini() and/or
362* wcsset(). wcsini() records the memory it allocates and wcsfree() will only
363* attempt to free this.
364*
365* PLEASE NOTE: wcsfree() must not be invoked on a wcsprm struct that was not
366* initialized by wcsini().
367*
368* Returned:
369* wcs struct wcsprm*
370* Coordinate transformation parameters.
371*
372* Function return value:
373* int Status return value:
374* 0: Success.
375* 1: Null wcsprm pointer passed.
376*
377*
378* wcsprt() - Print routine for the wcsprm struct
379* ----------------------------------------------
380* wcsprt() prints the contents of a wcsprm struct using wcsprintf(). Mainly
381* intended for diagnostic purposes.
382*
383* Given:
384* wcs const struct wcsprm*
385* Coordinate transformation parameters.
386*
387* Function return value:
388* int Status return value:
389* 0: Success.
390* 1: Null wcsprm pointer passed.
391*
392*
393* wcsperr() - Print error messages from a wcsprm struct
394* -----------------------------------------------------
395* wcsperr() prints the error message(s), if any, stored in a wcsprm struct,
396* and the linprm, celprm, prjprm, spcprm, and tabprm structs that it contains.
397* If there are no errors then nothing is printed. It uses wcserr_prt(), q.v.
398*
399* Given:
400* wcs const struct wcsprm*
401* Coordinate transformation parameters.
402*
403* prefix const char *
404* If non-NULL, each output line will be prefixed with
405* this string.
406*
407* Function return value:
408* int Status return value:
409* 0: Success.
410* 1: Null wcsprm pointer passed.
411*
412*
413* wcsbchk() - Enable/disable bounds checking
414* ------------------------------------------
415* wcsbchk() is used to control bounds checking in the projection routines.
416* Note that wcsset() always enables bounds checking. wcsbchk() will invoke
417* wcsset() on the wcsprm struct beforehand if necessary.
418*
419* Given and returned:
420* wcs struct wcsprm*
421* Coordinate transformation parameters.
422*
423* Given:
424* bounds int If bounds&1 then enable strict bounds checking for the
425* spherical-to-Cartesian (s2x) transformation for the
426* AZP, SZP, TAN, SIN, ZPN, and COP projections.
427*
428* If bounds&2 then enable strict bounds checking for the
429* Cartesian-to-spherical (x2s) transformation for the
430* HPX and XPH projections.
431*
432* If bounds&4 then enable bounds checking on the native
433* coordinates returned by the Cartesian-to-spherical
434* (x2s) transformations using prjchk().
435*
436* Zero it to disable all checking.
437*
438* Function return value:
439* int Status return value:
440* 0: Success.
441* 1: Null wcsprm pointer passed.
442*
443*
444* wcsset() - Setup routine for the wcsprm struct
445* ----------------------------------------------
446* wcsset() sets up a wcsprm struct according to information supplied within
447* it (refer to the description of the wcsprm struct).
448*
449* wcsset() recognizes the NCP projection and converts it to the equivalent SIN
450* projection and likewise translates GLS into SFL. It also translates the
451* AIPS spectral types ('FREQ-LSR', 'FELO-HEL', etc.), possibly changing the
452* input header keywords wcsprm::ctype and/or wcsprm::specsys if necessary.
453*
454* Note that this routine need not be called directly; it will be invoked by
455* wcsp2s() and wcss2p() if the wcsprm::flag is anything other than a
456* predefined magic value.
457*
458* Given and returned:
459* wcs struct wcsprm*
460* Coordinate transformation parameters.
461*
462* Function return value:
463* int Status return value:
464* 0: Success.
465* 1: Null wcsprm pointer passed.
466* 2: Memory allocation failed.
467* 3: Linear transformation matrix is singular.
468* 4: Inconsistent or unrecognized coordinate axis
469* types.
470* 5: Invalid parameter value.
471* 6: Invalid coordinate transformation parameters.
472* 7: Ill-conditioned coordinate transformation
473* parameters.
474*
475* For returns > 1, a detailed error message is set in
476* wcsprm::err if enabled, see wcserr_enable().
477*
478* Notes:
479* wcsset() always enables strict bounds checking in the projection routines
480* (via a call to prjini()). Use wcsbchk() to modify bounds-checking after
481* wcsset() is invoked.
482*
483*
484* wcsp2s() - Pixel-to-world transformation
485* ----------------------------------------
486* wcsp2s() transforms pixel coordinates to world coordinates.
487*
488* Given and returned:
489* wcs struct wcsprm*
490* Coordinate transformation parameters.
491*
492* Given:
493* ncoord,
494* nelem int The number of coordinates, each of vector length
495* nelem but containing wcs.naxis coordinate elements.
496* Thus nelem must equal or exceed the value of the
497* NAXIS keyword unless ncoord == 1, in which case nelem
498* is not used.
499*
500* pixcrd const double[ncoord][nelem]
501* Array of pixel coordinates.
502*
503* Returned:
504* imgcrd double[ncoord][nelem]
505* Array of intermediate world coordinates. For
506* celestial axes, imgcrd[][wcs.lng] and
507* imgcrd[][wcs.lat] are the projected x-, and
508* y-coordinates in pseudo "degrees". For spectral
509* axes, imgcrd[][wcs.spec] is the intermediate spectral
510* coordinate, in SI units.
511*
512* phi,theta double[ncoord]
513* Longitude and latitude in the native coordinate system
514* of the projection [deg].
515*
516* world double[ncoord][nelem]
517* Array of world coordinates. For celestial axes,
518* world[][wcs.lng] and world[][wcs.lat] are the
519* celestial longitude and latitude [deg]. For
520* spectral axes, imgcrd[][wcs.spec] is the intermediate
521* spectral coordinate, in SI units.
522*
523* stat int[ncoord]
524* Status return value for each coordinate:
525* 0: Success.
526* 1+: A bit mask indicating invalid pixel coordinate
527* element(s).
528*
529* Function return value:
530* int Status return value:
531* 0: Success.
532* 1: Null wcsprm pointer passed.
533* 2: Memory allocation failed.
534* 3: Linear transformation matrix is singular.
535* 4: Inconsistent or unrecognized coordinate axis
536* types.
537* 5: Invalid parameter value.
538* 6: Invalid coordinate transformation parameters.
539* 7: Ill-conditioned coordinate transformation
540* parameters.
541* 8: One or more of the pixel coordinates were
542* invalid, as indicated by the stat vector.
543*
544* For returns > 1, a detailed error message is set in
545* wcsprm::err if enabled, see wcserr_enable().
546*
547*
548* wcss2p() - World-to-pixel transformation
549* ----------------------------------------
550* wcss2p() transforms world coordinates to pixel coordinates.
551*
552* Given and returned:
553* wcs struct wcsprm*
554* Coordinate transformation parameters.
555*
556* Given:
557* ncoord,
558* nelem int The number of coordinates, each of vector length nelem
559* but containing wcs.naxis coordinate elements. Thus
560* nelem must equal or exceed the value of the NAXIS
561* keyword unless ncoord == 1, in which case nelem is not
562* used.
563*
564* world const double[ncoord][nelem]
565* Array of world coordinates. For celestial axes,
566* world[][wcs.lng] and world[][wcs.lat] are the
567* celestial longitude and latitude [deg]. For spectral
568* axes, world[][wcs.spec] is the spectral coordinate, in
569* SI units.
570*
571* Returned:
572* phi,theta double[ncoord]
573* Longitude and latitude in the native coordinate
574* system of the projection [deg].
575*
576* imgcrd double[ncoord][nelem]
577* Array of intermediate world coordinates. For
578* celestial axes, imgcrd[][wcs.lng] and
579* imgcrd[][wcs.lat] are the projected x-, and
580* y-coordinates in pseudo "degrees". For quadcube
581* projections with a CUBEFACE axis the face number is
582* also returned in imgcrd[][wcs.cubeface]. For
583* spectral axes, imgcrd[][wcs.spec] is the intermediate
584* spectral coordinate, in SI units.
585*
586* pixcrd double[ncoord][nelem]
587* Array of pixel coordinates.
588*
589* stat int[ncoord]
590* Status return value for each coordinate:
591* 0: Success.
592* 1+: A bit mask indicating invalid world coordinate
593* element(s).
594*
595* Function return value:
596* int Status return value:
597* 0: Success.
598* 1: Null wcsprm pointer passed.
599* 2: Memory allocation failed.
600* 3: Linear transformation matrix is singular.
601* 4: Inconsistent or unrecognized coordinate axis
602* types.
603* 5: Invalid parameter value.
604* 6: Invalid coordinate transformation parameters.
605* 7: Ill-conditioned coordinate transformation
606* parameters.
607* 9: One or more of the world coordinates were
608* invalid, as indicated by the stat vector.
609*
610* For returns > 1, a detailed error message is set in
611* wcsprm::err if enabled, see wcserr_enable().
612*
613*
614* wcsmix() - Hybrid coordinate transformation
615* -------------------------------------------
616* wcsmix(), given either the celestial longitude or latitude plus an element
617* of the pixel coordinate, solves for the remaining elements by iterating on
618* the unknown celestial coordinate element using wcss2p(). Refer also to the
619* notes below.
620*
621* Given and returned:
622* wcs struct wcsprm*
623* Indices for the celestial coordinates obtained
624* by parsing the wcsprm::ctype[].
625*
626* Given:
627* mixpix int Which element of the pixel coordinate is given.
628*
629* mixcel int Which element of the celestial coordinate is given:
630* 1: Celestial longitude is given in
631* world[wcs.lng], latitude returned in
632* world[wcs.lat].
633* 2: Celestial latitude is given in
634* world[wcs.lat], longitude returned in
635* world[wcs.lng].
636*
637* vspan const double[2]
638* Solution interval for the celestial coordinate [deg].
639* The ordering of the two limits is irrelevant.
640* Longitude ranges may be specified with any convenient
641* normalization, for example [-120,+120] is the same as
642* [240,480], except that the solution will be returned
643* with the same normalization, i.e. lie within the
644* interval specified.
645*
646* vstep const double
647* Step size for solution search [deg]. If zero, a
648* sensible, although perhaps non-optimal default will be
649* used.
650*
651* viter int If a solution is not found then the step size will be
652* halved and the search recommenced. viter controls how
653* many times the step size is halved. The allowed range
654* is 5 - 10.
655*
656* Given and returned:
657* world double[naxis]
658* World coordinate elements. world[wcs.lng] and
659* world[wcs.lat] are the celestial longitude and
660* latitude [deg]. Which is given and which returned
661* depends on the value of mixcel. All other elements
662* are given.
663*
664* Returned:
665* phi,theta double[naxis]
666* Longitude and latitude in the native coordinate
667* system of the projection [deg].
668*
669* imgcrd double[naxis]
670* Image coordinate elements. imgcrd[wcs.lng] and
671* imgcrd[wcs.lat] are the projected x-, and
672* y-coordinates in pseudo "degrees".
673*
674* Given and returned:
675* pixcrd double[naxis]
676* Pixel coordinate. The element indicated by mixpix is
677* given and the remaining elements are returned.
678*
679* Function return value:
680* int Status return value:
681* 0: Success.
682* 1: Null wcsprm pointer passed.
683* 2: Memory allocation failed.
684* 3: Linear transformation matrix is singular.
685* 4: Inconsistent or unrecognized coordinate axis
686* types.
687* 5: Invalid parameter value.
688* 6: Invalid coordinate transformation parameters.
689* 7: Ill-conditioned coordinate transformation
690* parameters.
691* 10: Invalid world coordinate.
692* 11: No solution found in the specified interval.
693*
694* For returns > 1, a detailed error message is set in
695* wcsprm::err if enabled, see wcserr_enable().
696*
697* Notes:
698* Initially the specified solution interval is checked to see if it's a
699* "crossing" interval. If it isn't, a search is made for a crossing
700* solution by iterating on the unknown celestial coordinate starting at the
701* upper limit of the solution interval and decrementing by the specified
702* step size. A crossing is indicated if the trial value of the pixel
703* coordinate steps through the value specified. If a crossing interval is
704* found then the solution is determined by a modified form of "regula falsi"
705* division of the crossing interval. If no crossing interval was found
706* within the specified solution interval then a search is made for a
707* "non-crossing" solution as may arise from a point of tangency. The
708* process is complicated by having to make allowance for the discontinuities
709* that occur in all map projections.
710*
711* Once one solution has been determined others may be found by subsequent
712* invokations of wcsmix() with suitably restricted solution intervals.
713*
714* Note the circumstance that arises when the solution point lies at a native
715* pole of a projection in which the pole is represented as a finite curve,
716* for example the zenithals and conics. In such cases two or more valid
717* solutions may exist but wcsmix() only ever returns one.
718*
719* Because of its generality wcsmix() is very compute-intensive. For
720* compute-limited applications more efficient special-case solvers could be
721* written for simple projections, for example non-oblique cylindrical
722* projections.
723*
724*
725* wcssptr() - Spectral axis translation
726* -------------------------------------
727* wcssptr() translates the spectral axis in a wcsprm struct. For example, a
728* 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.
729*
730* Given and returned:
731* wcs struct wcsprm*
732* Coordinate transformation parameters.
733*
734* i int* Index of the spectral axis (0-relative). If given < 0
735* it will be set to the first spectral axis identified
736* from the ctype[] keyvalues in the wcsprm struct.
737*
738* ctype char[9] Desired spectral CTYPEia. Wildcarding may be used as
739* for the ctypeS2 argument to spctrn() as described in
740* the prologue of spc.h, i.e. if the final three
741* characters are specified as "???", or if just the
742* eighth character is specified as '?', the correct
743* algorithm code will be substituted and returned.
744*
745* Function return value:
746* int Status return value:
747* 0: Success.
748* 1: Null wcsprm pointer passed.
749* 2: Memory allocation failed.
750* 3: Linear transformation matrix is singular.
751* 4: Inconsistent or unrecognized coordinate axis
752* types.
753* 5: Invalid parameter value.
754* 6: Invalid coordinate transformation parameters.
755* 7: Ill-conditioned coordinate transformation
756* parameters.
757* 12: Invalid subimage specification (no spectral
758* axis).
759*
760* For returns > 1, a detailed error message is set in
761* wcsprm::err if enabled, see wcserr_enable().
762*
763*
764* wcsprm struct - Coordinate transformation parameters
765* ----------------------------------------------------
766* The wcsprm struct contains information required to transform world
767* coordinates. It consists of certain members that must be set by the user
768* ("given") and others that are set by the WCSLIB routines ("returned").
769* Some of the former are not actually required for transforming coordinates.
770* These are described as "auxiliary"; the struct simply provides a place to
771* store them, though they may be used by wcshdo() in constructing a FITS
772* header from a wcsprm struct. Some of the returned values are supplied for
773* informational purposes and others are for internal use only as indicated.
774*
775* In practice, it is expected that a WCS parser would scan the FITS header to
776* determine the number of coordinate axes. It would then use wcsini() to
777* allocate memory for arrays in the wcsprm struct and set default values.
778* Then as it reread the header and identified each WCS keyrecord it would load
779* the value into the relevant wcsprm array element. This is essentially what
780* wcspih() does - refer to the prologue of wcshdr.h. As the final step,
781* wcsset() is invoked, either directly or indirectly, to set the derived
782* members of the wcsprm struct. wcsset() strips off trailing blanks in all
783* string members and null-fills the character array.
784*
785* int flag
786* (Given and returned) This flag must be set to zero whenever any of the
787* following wcsprm struct members are set or changed:
788*
789* - wcsprm::naxis (q.v., not normally set by the user),
790* - wcsprm::crpix,
791* - wcsprm::pc,
792* - wcsprm::cdelt,
793* - wcsprm::crval,
794* - wcsprm::cunit,
795* - wcsprm::ctype,
796* - wcsprm::lonpole,
797* - wcsprm::latpole,
798* - wcsprm::restfrq,
799* - wcsprm::restwav,
800* - wcsprm::npv,
801* - wcsprm::pv,
802* - wcsprm::nps,
803* - wcsprm::ps,
804* - wcsprm::cd,
805* - wcsprm::crota,
806* - wcsprm::altlin.
807*
808* This signals the initialization routine, wcsset(), to recompute the
809* returned members of the celprm struct. celset() will reset flag to
810* indicate that this has been done.
811*
812* PLEASE NOTE: flag should be set to -1 when wcsini() is called for the
813* first time for a particular wcsprm struct in order to initialize memory
814* management. It must ONLY be used on the first initialization otherwise
815* memory leaks may result.
816*
817* int naxis
818* (Given or returned) Number of pixel and world coordinate elements.
819*
820* If wcsini() is used to initialize the linprm struct (as would normally
821* be the case) then it will set naxis from the value passed to it as a
822* function argument. The user should not subsequently modify it.
823*
824* double *crpix
825* (Given) Address of the first element of an array of double containing
826* the coordinate reference pixel, CRPIXja.
827*
828* double *pc
829* (Given) Address of the first element of the PCi_ja (pixel coordinate)
830* transformation matrix. The expected order is
831*
832= struct wcsprm wcs;
833= wcs.pc = {PC1_1, PC1_2, PC2_1, PC2_2};
834*
835* This may be constructed conveniently from a 2-D array via
836*
837= double m[2][2] = {{PC1_1, PC1_2},
838= {PC2_1, PC2_2}};
839*
840* which is equivalent to
841*
842= double m[2][2];
843= m[0][0] = PC1_1;
844= m[0][1] = PC1_2;
845= m[1][0] = PC2_1;
846= m[1][1] = PC2_2;
847*
848* The storage order for this 2-D array is the same as for the 1-D array,
849* whence
850*
851= wcs.pc = *m;
852*
853* would be legitimate.
854*
855* double *cdelt
856* (Given) Address of the first element of an array of double containing
857* the coordinate increments, CDELTia.
858*
859* double *crval
860* (Given) Address of the first element of an array of double containing
861* the coordinate reference values, CRVALia.
862*
863* char (*cunit)[72]
864* (Given) Address of the first element of an array of char[72] containing
865* the CUNITia keyvalues which define the units of measurement of the
866* CRVALia, CDELTia, and CDi_ja keywords.
867*
868* As CUNITia is an optional header keyword, cunit[][72] may be left blank
869* but otherwise is expected to contain a standard units specification as
870* defined by WCS Paper I. Utility function wcsutrn(), described in
871* wcsunits.h, is available to translate commonly used non-standard units
872* specifications but this must be done as a separate step before invoking
873* wcsset().
874*
875* For celestial axes, if cunit[][72] is not blank, wcsset() uses
876* wcsunits() to parse it and scale cdelt[], crval[], and cd[][*] to
877* degrees. It then resets cunit[][72] to "deg".
878*
879* For spectral axes, if cunit[][72] is not blank, wcsset() uses wcsunits()
880* to parse it and scale cdelt[], crval[], and cd[][*] to SI units. It
881* then resets cunit[][72] accordingly.
882*
883* wcsset() ignores cunit[][72] for other coordinate types; cunit[][72] may
884* be used to label coordinate values.
885*
886* These variables accomodate the longest allowed string-valued FITS
887* keyword, being limited to 68 characters, plus the null-terminating
888* character.
889*
890* char (*ctype)[72]
891* (Given) Address of the first element of an array of char[72] containing
892* the coordinate axis types, CTYPEia.
893*
894* The ctype[][72] keyword values must be in upper case and there must be
895* zero or one pair of matched celestial axis types, and zero or one
896* spectral axis. The ctype[][72] strings should be padded with blanks on
897* the right and null-terminated so that they are at least eight characters
898* in length.
899*
900* These variables accomodate the longest allowed string-valued FITS
901* keyword, being limited to 68 characters, plus the null-terminating
902* character.
903*
904* double lonpole
905* (Given and returned) The native longitude of the celestial pole, phi_p,
906* given by LONPOLEa [deg] or by PVi_2a [deg] attached to the longitude
907* axis which takes precedence if defined, and ...
908* double latpole
909* (Given and returned) ... the native latitude of the celestial pole,
910* theta_p, given by LATPOLEa [deg] or by PVi_3a [deg] attached to the
911* longitude axis which takes precedence if defined.
912*
913* lonpole and latpole may be left to default to values set by wcsini()
914* (see celprm::ref), but in any case they will be reset by wcsset() to
915* the values actually used. Note therefore that if the wcsprm struct is
916* reused without resetting them, whether directly or via wcsini(), they
917* will no longer have their default values.
918*
919* double restfrq
920* (Given) The rest frequency [Hz], and/or ...
921* double restwav
922* (Given) ... the rest wavelength in vacuo [m], only one of which need be
923* given, the other should be set to zero.
924*
925* int npv
926* (Given) The number of entries in the wcsprm::pv[] array.
927*
928* int npvmax
929* (Given or returned) The length of the wcsprm::pv[] array.
930*
931* npvmax will be set by wcsini() if it allocates memory for wcsprm::pv[],
932* otherwise it must be set by the user. See also wcsnpv().
933*
934* struct pvcard *pv
935* (Given or returned) Address of the first element of an array of length
936* npvmax of pvcard structs. Set by wcsini() if it allocates memory for
937* pv[], otherwise it must be set by the user. See also wcsnpv().
938*
939* As a FITS header parser encounters each PVi_ma keyword it should load it
940* into a pvcard struct in the array and increment npv. wcsset()
941* interprets these as required.
942*
943* Note that, if they were not given, wcsset() resets the entries for
944* PVi_1a, PVi_2a, PVi_3a, and PVi_4a for longitude axis i to match
945* phi_0 and theta_0 (the native longitude and latitude of the reference
946* point), LONPOLEa and LATPOLEa respectively.
947*
948* int nps
949* (Given) The number of entries in the wcsprm::ps[] array.
950*
951* int npsmax
952* (Given or returned) The length of the wcsprm::ps[] array.
953*
954* npsmax will be set by wcsini() if it allocates memory for wcsprm::ps[],
955* otherwise it must be set by the user. See also wcsnps().
956*
957* struct pscard *ps
958* (Given or returned) Address of the first element of an array of length
959* npsmax of pscard structs. Set by wcsini() if it allocates memory for
960* ps[], otherwise it must be set by the user. See also wcsnps().
961*
962* As a FITS header parser encounters each PSi_ma keyword it should load it
963* into a pscard struct in the array and increment nps. wcsset()
964* interprets these as required (currently no PSi_ma keyvalues are
965* recognized).
966*
967* double *cd
968* (Given) For historical compatibility, the wcsprm struct supports two
969* alternate specifications of the linear transformation matrix, those
970* associated with the CDi_ja keywords, and ...
971* double *crota
972* (Given) ... those associated with the CROTAia keywords. Although these
973* may not formally co-exist with PCi_ja, the approach taken here is simply
974* to ignore them if given in conjunction with PCi_ja.
975*
976* int altlin
977* (Given) altlin is a bit flag that denotes which of the PCi_ja, CDi_ja
978* and CROTAia keywords are present in the header:
979*
980* - Bit 0: PCi_ja is present.
981*
982* - Bit 1: CDi_ja is present.
983*
984* Matrix elements in the IRAF convention are
985* equivalent to the product CDi_ja = CDELTia * PCi_ja, but the
986* defaults differ from that of the PCi_ja matrix. If one or more
987* CDi_ja keywords are present then all unspecified CDi_ja default to
988* zero. If no CDi_ja (or CROTAia) keywords are present, then the
989* header is assumed to be in PCi_ja form whether or not any PCi_ja
990* keywords are present since this results in an interpretation of
991* CDELTia consistent with the original FITS specification.
992*
993* While CDi_ja may not formally co-exist with PCi_ja, it may co-exist
994* with CDELTia and CROTAia which are to be ignored.
995*
996* - Bit 2: CROTAia is present.
997*
998* In the AIPS convention, CROTAia may only be
999* associated with the latitude axis of a celestial axis pair. It
1000* specifies a rotation in the image plane that is applied AFTER the
1001* CDELTia; any other CROTAia keywords are ignored.
1002*
1003* CROTAia may not formally co-exist with PCi_ja.
1004*
1005* CROTAia and CDELTia may formally co-exist with CDi_ja but if so are to
1006* be ignored.
1007*
1008* CDi_ja and CROTAia keywords, if found, are to be stored in the
1009* wcsprm::cd and wcsprm::crota arrays which are dimensioned similarly to
1010* wcsprm::pc and wcsprm::cdelt. FITS
1011* header parsers should use the following procedure:
1012*
1013* - Whenever a PCi_ja keyword is encountered: altlin |= 1;
1014*
1015* - Whenever a CDi_ja keyword is encountered: altlin |= 2;
1016*
1017* - Whenever a CROTAia keyword is encountered: altlin |= 4;
1018*
1019* If none of these bits are set the PCi_ja representation results, i.e.
1020* wcsprm::pc and wcsprm::cdelt will be used as given.
1021*
1022* These alternate specifications of the linear transformation matrix are
1023* translated immediately to PCi_ja by wcsset() and are invisible to the
1024* lower-level WCSLIB routines. In particular, wcsset() resets
1025* wcsprm::cdelt to unity if CDi_ja is present (and no PCi_ja).
1026*
1027* If CROTAia are present but none is associated with the latitude axis
1028* (and no PCi_ja or CDi_ja), then wcsset() reverts to a unity PCi_ja
1029* matrix.
1030*
1031* int velref
1032* (Given) AIPS velocity code VELREF, refer to spcaips().
1033*
1034* char alt[4]
1035* (Given, auxiliary) Character code for alternate coordinate descriptions
1036* (i.e. the 'a' in keyword names such as CTYPEia). This is blank for the
1037* primary coordinate description, or one of the 26 upper-case letters,
1038* A-Z.
1039*
1040* An array of four characters is provided for alignment purposes, only the
1041* first is used.
1042*
1043* int colnum
1044* (Given, auxiliary) Where the coordinate representation is associated
1045* with an image-array column in a FITS binary table, this variable may be
1046* used to record the relevant column number.
1047*
1048* It should be set to zero for an image header or pixel list.
1049*
1050* int *colax
1051* (Given, auxiliary) Address of the first element of an array of int
1052* recording the column numbers for each axis in a pixel list.
1053*
1054* The array elements should be set to zero for an image header or image
1055* array in a binary table.
1056*
1057* char (*cname)[72]
1058* (Given, auxiliary) The address of the first element of an array of
1059* char[72] containing the coordinate axis names, CNAMEia.
1060*
1061* These variables accomodate the longest allowed string-valued FITS
1062* keyword, being limited to 68 characters, plus the null-terminating
1063* character.
1064*
1065* double *crder
1066* (Given, auxiliary) Address of the first element of an array of double
1067* recording the random error in the coordinate value, CRDERia.
1068* double *csyer
1069* (Given, auxiliary) Address of the first element of an array of double
1070* recording the systematic error in the coordinate value, CSYERia.
1071*
1072* char dateavg[72]
1073* (Given, auxiliary) The date of a representative mid-point of the
1074* observation in ISO format, yyyy-mm-ddThh:mm:ss.
1075* char dateobs[72]
1076* (Given, auxiliary) The date of the start of the observation unless
1077* otherwise explained in the comment field of the DATE-OBS keyword, in
1078* ISO format, yyyy-mm-ddThh:mm:ss.
1079*
1080* double equinox
1081* (Given, auxiliary) The equinox associated with dynamical equatorial or
1082* ecliptic coordinate systems, EQUINOXa (or EPOCH in older headers). Not
1083* applicable to ICRS equatorial or ecliptic coordinates.
1084*
1085* double mjdavg
1086* (Given, auxiliary) Modified Julian Date (MJD = JD - 2400000.5), MJD-AVG,
1087* corresponding to DATE-AVG.
1088* double mjdobs
1089* (Given, auxiliary) Modified Julian Date (MJD = JD - 2400000.5), MJD-OBS,
1090* corresponding to DATE-OBS.
1091*
1092* double obsgeo[3]
1093* (Given, auxiliary) Location of the observer in a standard terrestrial
1094* reference frame, OBSGEO-X, OBSGEO-Y, OBSGEO-Z [m].
1095*
1096* char radesys[72]
1097* (Given, auxiliary) The equatorial or ecliptic coordinate system type,
1098* RADESYSa.
1099*
1100* char specsys[72]
1101* (Given, auxiliary) Spectral reference frame (standard of rest),
1102* SPECSYSa, and ...
1103* char ssysobs[72]
1104* (Given, auxiliary) ... the actual frame in which there is no
1105* differential variation in the spectral coordinate across the
1106* field-of-view, SSYSOBSa.
1107* double velosys
1108* (Given, auxiliary) The relative radial velocity [m/s] between the
1109* observer and the selected standard of rest in the direction of the
1110* celestial reference coordinate, VELOSYSa.
1111*
1112* double zsource
1113* (Given, auxiliary) The redshift, ZSOURCEa, of the source, and ...
1114* char ssyssrc[72]
1115* (Given, auxiliary) ... the spectral reference frame (standard of rest)
1116* in which this was measured, SSYSSRCa.
1117*
1118* double velangl
1119* (Given, auxiliary) The angle [deg] that should be used to decompose an
1120* observed velocity into radial and transverse components.
1121*
1122* char wcsname[72]
1123* (Given, auxiliary) The name given to the coordinate representation,
1124* WCSNAMEa. This variable accomodates the longest allowed string-valued
1125* FITS keyword, being limited to 68 characters, plus the null-terminating
1126* character.
1127*
1128* int ntab
1129* (Given) See wcsprm::tab.
1130*
1131* int nwtb
1132* (Given) See wcsprm::wtb.
1133*
1134* struct tabprm *tab
1135* (Given) Address of the first element of an array of ntab tabprm structs
1136* for which memory has been allocated. These are used to store tabular
1137* transformation parameters.
1138*
1139* Although technically wcsprm::ntab and tab are "given", they will
1140* normally be set by invoking wcstab(), whether directly or indirectly.
1141*
1142* The tabprm structs contain some members that must be supplied and others
1143* that are derived. The information to be supplied comes primarily from
1144* arrays stored in one or more FITS binary table extensions. These
1145* arrays, referred to here as "wcstab arrays", are themselves located by
1146* parameters stored in the FITS image header.
1147*
1148* struct wtbarr *wtb
1149* (Given) Address of the first element of an array of nwtb wtbarr structs
1150* for which memory has been allocated. These are used in extracting
1151* wcstab arrays from a FITS binary table.
1152*
1153* Although technically wcsprm::nwtb and wtb are "given", they will
1154* normally be set by invoking wcstab(), whether directly or indirectly.
1155*
1156* char lngtyp[8]
1157* (Returned) Four-character WCS celestial longitude and ...
1158* char lattyp[8]
1159* (Returned) ... latitude axis types. e.g. "RA", "DEC", "GLON", "GLAT",
1160* etc. extracted from 'RA--', 'DEC-', 'GLON', 'GLAT', etc. in the first
1161* four characters of CTYPEia but with trailing dashes removed. (Declared
1162* as char[8] for alignment reasons.)
1163*
1164* int lng
1165* (Returned) Index for the longitude coordinate, and ...
1166* int lat
1167* (Returned) ... index for the latitude coordinate, and ...
1168* int spec
1169* (Returned) ... index for the spectral coordinate in the imgcrd[][] and
1170* world[][] arrays in the API of wcsp2s(), wcss2p() and wcsmix().
1171*
1172* These may also serve as indices into the pixcrd[][] array provided that
1173* the PCi_ja matrix does not transpose axes.
1174*
1175* int cubeface
1176* (Returned) Index into the pixcrd[][] array for the CUBEFACE axis. This
1177* is used for quadcube projections where the cube faces are stored on a
1178* separate axis (see wcs.h).
1179*
1180* int *types
1181* (Returned) Address of the first element of an array of int containing a
1182* four-digit type code for each axis.
1183*
1184* - First digit (i.e. 1000s):
1185* - 0: Non-specific coordinate type.
1186* - 1: Stokes coordinate.
1187* - 2: Celestial coordinate (including CUBEFACE).
1188* - 3: Spectral coordinate.
1189*
1190* - Second digit (i.e. 100s):
1191* - 0: Linear axis.
1192* - 1: Quantized axis (STOKES, CUBEFACE).
1193* - 2: Non-linear celestial axis.
1194* - 3: Non-linear spectral axis.
1195* - 4: Logarithmic axis.
1196* - 5: Tabular axis.
1197*
1198* - Third digit (i.e. 10s):
1199* - 0: Group number, e.g. lookup table number, being an index into the
1200* tabprm array (see above).
1201*
1202* - The fourth digit is used as a qualifier depending on the axis type.
1203*
1204* - For celestial axes:
1205* - 0: Longitude coordinate.
1206* - 1: Latitude coordinate.
1207* - 2: CUBEFACE number.
1208*
1209* - For lookup tables: the axis number in a multidimensional table.
1210*
1211* CTYPEia in "4-3" form with unrecognized algorithm code will have its
1212* type set to -1 and generate an error.
1213*
1214* void *padding
1215* (An unused variable inserted for alignment purposes only.)
1216*
1217* struct linprm lin
1218* (Returned) Linear transformation parameters (usage is described in the
1219* prologue to lin.h).
1220*
1221* struct celprm cel
1222* (Returned) Celestial transformation parameters (usage is described in
1223* the prologue to cel.h).
1224*
1225* struct spcprm spc
1226* (Returned) Spectral transformation parameters (usage is described in the
1227* prologue to spc.h).
1228*
1229* struct wcserr *err
1230* (Returned) If enabled, when an error status is returned this struct
1231* contains detailed information about the error, see wcserr_enable().
1232*
1233* void *m_padding
1234* (For internal use only.)
1235* int m_flag
1236* (For internal use only.)
1237* int m_naxis
1238* (For internal use only.)
1239* double *m_crpix
1240* (For internal use only.)
1241* double *m_pc
1242* (For internal use only.)
1243* double *m_cdelt
1244* (For internal use only.)
1245* double *m_crval
1246* (For internal use only.)
1247* char (*m_cunit)[72]
1248* (For internal use only.)
1249* char (*m_ctype)[72]
1250* (For internal use only.)
1251* struct pvcard *m_pv
1252* (For internal use only.)
1253* struct pscard *m_ps
1254* (For internal use only.)
1255* double *m_cd
1256* (For internal use only.)
1257* double *m_crota
1258* (For internal use only.)
1259* int *m_colax
1260* (For internal use only.)
1261* char (*m_cname)[72]
1262* (For internal use only.)
1263* double *m_crder
1264* (For internal use only.)
1265* double *m_csyer
1266* (For internal use only.)
1267* struct tabprm *m_tab
1268* (For internal use only.)
1269* struct wtbarr *m_wtb
1270* (For internal use only.)
1271*
1272*
1273* pscard struct - Store for PSi_ma keyrecords
1274* -------------------------------------------
1275* The pscard struct is used to pass the parsed contents of PSi_ma keyrecords
1276* to wcsset() via the wcsprm struct.
1277*
1278* All members of this struct are to be set by the user.
1279*
1280* int i
1281* (Given) Axis number (1-relative), as in the FITS PSi_ma keyword.
1282*
1283* int m
1284* (Given) Parameter number (non-negative), as in the FITS PSi_ma keyword.
1285*
1286* char value[72]
1287* (Given) Parameter value.
1288*
1289*
1290* pvcard struct - Store for PVi_ma keyrecords
1291* -------------------------------------------
1292* The pvcard struct is used to pass the parsed contents of PVi_ma keyrecords
1293* to wcsset() via the wcsprm struct.
1294*
1295* All members of this struct are to be set by the user.
1296*
1297* int i
1298* (Given) Axis number (1-relative), as in the FITS PVi_ma keyword. If
1299* i == 0, wcsset() will replace it with the latitude axis number.
1300*
1301* int m
1302* (Given) Parameter number (non-negative), as in the FITS PVi_ma keyword.
1303*
1304* double value
1305* (Given) Parameter value.
1306*
1307*
1308* wtbarr struct - Extraction of coordinate lookup tables from BINTABLE
1309* --------------------------------------------------------------------
1310* Function wcstab(), which is invoked automatically by wcspih(), sets up an
1311* array of wtbarr structs to assist in extracting coordinate lookup tables
1312* from a binary table extension (BINTABLE) and copying them into the tabprm
1313* structs stored in wcsprm. Refer to the usage notes for wcspih() and
1314* wcstab() in wcshdr.h, and also the prologue to tab.h.
1315*
1316* For C++ usage, because of a name space conflict with the wtbarr typedef
1317* defined in CFITSIO header fitsio.h, the wtbarr struct is renamed to wtbarr_s
1318* by preprocessor macro substitution with scope limited to wcs.h itself.
1319*
1320* int i
1321* (Given) Image axis number.
1322*
1323* int m
1324* (Given) wcstab array axis number for index vectors.
1325*
1326* int kind
1327* (Given) Character identifying the wcstab array type:
1328* - c: coordinate array,
1329* - i: index vector.
1330*
1331* char extnam[72]
1332* (Given) EXTNAME identifying the binary table extension.
1333*
1334* int extver
1335* (Given) EXTVER identifying the binary table extension.
1336*
1337* int extlev
1338* (Given) EXTLEV identifying the binary table extension.
1339*
1340* char ttype[72]
1341* (Given) TTYPEn identifying the column of the binary table that contains
1342* the wcstab array.
1343*
1344* long row
1345* (Given) Table row number.
1346*
1347* int ndim
1348* (Given) Expected dimensionality of the wcstab array.
1349*
1350* int *dimlen
1351* (Given) Address of the first element of an array of int of length ndim
1352* into which the wcstab array axis lengths are to be written.
1353*
1354* double **arrayp
1355* (Given) Pointer to an array of double which is to be allocated by the
1356* user and into which the wcstab array is to be written.
1357*
1358*
1359* Global variable: const char *wcs_errmsg[] - Status return messages
1360* ------------------------------------------------------------------
1361* Error messages to match the status value returned from each function.
1362*
1363*===========================================================================*/
1364
1365#ifndef WCSLIB_WCS
1366#define WCSLIB_WCS
1367
1368#include "lin.h"
1369#include "cel.h"
1370#include "spc.h"
1371#include "tab.h"
1372#include "wcserr.h"
1373
1374#ifdef __cplusplus
1375extern "C" {
1376#endif
1377
1378#define WCSSUB_LONGITUDE 0x1001
1379#define WCSSUB_LATITUDE 0x1002
1380#define WCSSUB_CUBEFACE 0x1004
1381#define WCSSUB_CELESTIAL 0x1007
1382#define WCSSUB_SPECTRAL 0x1008
1383#define WCSSUB_STOKES 0x1010
1384
1385
1386#define WCSCOMPARE_ANCILLARY 0x0001
1387#define WCSCOMPARE_TILING 0x0002
1388#define WCSCOMPARE_CRPIX 0x0004
1389
1390
1391extern const char *wcs_errmsg[];
1392
1393enum wcs_errmsg_enum {
1394 WCSERR_SUCCESS = 0, /* Success. */
1395 WCSERR_NULL_POINTER = 1, /* Null wcsprm pointer passed. */
1396 WCSERR_MEMORY = 2, /* Memory allocation failed. */
1397 WCSERR_SINGULAR_MTX = 3, /* Linear transformation matrix is
1398 singular. */
1399 WCSERR_BAD_CTYPE = 4, /* Inconsistent or unrecognized coordinate
1400 axis types. */
1401 WCSERR_BAD_PARAM = 5, /* Invalid parameter value. */
1402 WCSERR_BAD_COORD_TRANS = 6, /* Invalid coordinate transformation
1403 parameters. */
1404 WCSERR_ILL_COORD_TRANS = 7, /* Ill-conditioned coordinate transformation
1405 parameters. */
1406 WCSERR_BAD_PIX = 8, /* One or more of the pixel coordinates were
1407 invalid. */
1408 WCSERR_BAD_WORLD = 9, /* One or more of the world coordinates were
1409 invalid. */
1410 WCSERR_BAD_WORLD_COORD = 10, /* Invalid world coordinate. */
1411 WCSERR_NO_SOLUTION = 11, /* No solution found in the specified
1412 interval. */
1413 WCSERR_BAD_SUBIMAGE = 12, /* Invalid subimage specification. */
1414 WCSERR_NON_SEPARABLE = 13 /* Non-separable subimage coordinate
1415 system. */
1416};
1417
1418
1419/* Struct used for storing PVi_ma keywords. */
1420struct pvcard {
1421 int i; /* Axis number, as in PVi_ma (1-relative). */
1422 int m; /* Parameter number, ditto (0-relative). */
1423 double value; /* Parameter value. */
1424};
1425
1426/* Struct used for storing PSi_ma keywords. */
1427struct pscard {
1428 int i; /* Axis number, as in PSi_ma (1-relative). */
1429 int m; /* Parameter number, ditto (0-relative). */
1430 char value[72]; /* Parameter value. */
1431};
1432
1433 /* For extracting wcstab arrays. Matches */
1434 /* the wtbarr typedef defined in CFITSIO */
1435 /* header fitsio.h. */
1436#ifdef __cplusplus
1437#define wtbarr wtbarr_s /* See prologue above. */
1438#endif
1439struct wtbarr {
1440 int i; /* Image axis number. */
1441 int m; /* Array axis number for index vectors. */
1442 int kind; /* wcstab array type. */
1443 char extnam[72]; /* EXTNAME of binary table extension. */
1444 int extver; /* EXTVER of binary table extension. */
1445 int extlev; /* EXTLEV of binary table extension. */
1446 char ttype[72]; /* TTYPEn of column containing the array. */
1447 long row; /* Table row number. */
1448 int ndim; /* Expected wcstab array dimensionality. */
1449 int *dimlen; /* Where to write the array axis lengths. */
1450 double **arrayp; /* Where to write the address of the array */
1451 /* allocated to store the wcstab array. */
1452};
1453
1454
1455struct wcsprm {
1456 /* Initialization flag (see the prologue above). */
1457 /*------------------------------------------------------------------------*/
1458 int flag; /* Set to zero to force initialization. */
1459
1460 /* FITS header keyvalues to be provided (see the prologue above). */
1461 /*------------------------------------------------------------------------*/
1462 int naxis; /* Number of axes (pixel and coordinate). */
1463 double *crpix; /* CRPIXja keyvalues for each pixel axis. */
1464 double *pc; /* PCi_ja linear transformation matrix. */
1465 double *cdelt; /* CDELTia keyvalues for each coord axis. */
1466 double *crval; /* CRVALia keyvalues for each coord axis. */
1467
1468 char (*cunit)[72]; /* CUNITia keyvalues for each coord axis. */
1469 char (*ctype)[72]; /* CTYPEia keyvalues for each coord axis. */
1470
1471 double lonpole; /* LONPOLEa keyvalue. */
1472 double latpole; /* LATPOLEa keyvalue. */
1473
1474 double restfrq; /* RESTFRQa keyvalue. */
1475 double restwav; /* RESTWAVa keyvalue. */
1476
1477 int npv; /* Number of PVi_ma keywords, and the */
1478 int npvmax; /* number for which space was allocated. */
1479 struct pvcard *pv; /* PVi_ma keywords for each i and m. */
1480
1481 int nps; /* Number of PSi_ma keywords, and the */
1482 int npsmax; /* number for which space was allocated. */
1483 struct pscard *ps; /* PSi_ma keywords for each i and m. */
1484
1485 /* Alternative header keyvalues (see the prologue above). */
1486 /*------------------------------------------------------------------------*/
1487 double *cd; /* CDi_ja linear transformation matrix. */
1488 double *crota; /* CROTAia keyvalues for each coord axis. */
1489 int altlin; /* Alternative representations */
1490 /* Bit 0: PCi_ja is present, */
1491 /* Bit 1: CDi_ja is present, */
1492 /* Bit 2: CROTAia is present. */
1493 int velref; /* AIPS velocity code, VELREF. */
1494
1495 /* Auxiliary coordinate system information, not used by WCSLIB. */
1496 char alt[4];
1497 int colnum;
1498 int *colax;
1499
1500 char (*cname)[72];
1501 double *crder;
1502 double *csyer;
1503 char dateavg[72];
1504 char dateobs[72];
1505 double equinox;
1506 double mjdavg;
1507 double mjdobs;
1508 double obsgeo[3];
1509 char radesys[72];
1510 char specsys[72];
1511 char ssysobs[72];
1512 double velosys;
1513 double zsource;
1514 char ssyssrc[72];
1515 double velangl;
1516 char wcsname[72];
1517
1518 /* Coordinate lookup tables (see the prologue above). */
1519 /*------------------------------------------------------------------------*/
1520 int ntab; /* Number of separate tables. */
1521 int nwtb; /* Number of wtbarr structs. */
1522 struct tabprm *tab; /* Tabular transformation parameters. */
1523 struct wtbarr *wtb; /* Array of wtbarr structs. */
1524
1525 /* Information derived from the FITS header keyvalues by wcsset(). */
1526 /*------------------------------------------------------------------------*/
1527 char lngtyp[8], lattyp[8]; /* Celestial axis types, e.g. RA, DEC. */
1528 int lng, lat, spec; /* Longitude, latitude and spectral axis */
1529 /* indices (0-relative). */
1530 int cubeface; /* True if there is a CUBEFACE axis. */
1531 int *types; /* Coordinate type codes for each axis. */
1532 void *padding; /* (Dummy inserted for alignment purposes.) */
1533
1534 struct linprm lin; /* Linear transformation parameters. */
1535 struct celprm cel; /* Celestial transformation parameters. */
1536 struct spcprm spc; /* Spectral transformation parameters. */
1537
1538 /* Error handling */
1539 /*------------------------------------------------------------------------*/
1540 struct wcserr *err;
1541
1542 /* Private - the remainder are for memory management. */
1543 /*------------------------------------------------------------------------*/
1544 void *m_padding;
1545 int m_flag, m_naxis;
1546 double *m_crpix, *m_pc, *m_cdelt, *m_crval;
1547 char (*m_cunit)[72], (*m_ctype)[72];
1548 struct pvcard *m_pv;
1549 struct pscard *m_ps;
1550 double *m_cd, *m_crota;
1551 int *m_colax;
1552 char (*m_cname)[72];
1553 double *m_crder, *m_csyer;
1554 struct tabprm *m_tab;
1555 struct wtbarr *m_wtb;
1556};
1557
1558/* Size of the wcsprm struct in int units, used by the Fortran wrappers. */
1559#define WCSLEN (sizeof(struct wcsprm)/sizeof(int))
1560
1561
1562int wcsnpv(int n);
1563
1564int wcsnps(int n);
1565
1566int wcsini(int alloc, int naxis, struct wcsprm *wcs);
1567
1568int wcssub(int alloc, const struct wcsprm *wcssrc, int *nsub, int axes[],
1569 struct wcsprm *wcsdst);
1570
1571int wcscompare(int cmp, const struct wcsprm *wcs1, const struct wcsprm *wcs2,
1572 int *equal);
1573
1574int wcsfree(struct wcsprm *wcs);
1575
1576int wcsprt(const struct wcsprm *wcs);
1577
1578int wcsperr(const struct wcsprm *wcs, const char *prefix);
1579
1580int wcsbchk(struct wcsprm *wcs, int bounds);
1581
1582int wcsset(struct wcsprm *wcs);
1583
1584int wcsp2s(struct wcsprm *wcs, int ncoord, int nelem, const double pixcrd[],
1585 double imgcrd[], double phi[], double theta[], double world[],
1586 int stat[]);
1587
1588int wcss2p(struct wcsprm *wcs, int ncoord, int nelem, const double world[],
1589 double phi[], double theta[], double imgcrd[], double pixcrd[],
1590 int stat[]);
1591
1592int wcsmix(struct wcsprm *wcs, int mixpix, int mixcel, const double vspan[],
1593 double vstep, int viter, double world[], double phi[],
1594 double theta[], double imgcrd[], double pixcrd[]);
1595
1596int wcssptr(struct wcsprm *wcs, int *i, char ctype[9]);
1597
1598/* Defined mainly for backwards compatibility, use wcssub() instead. */
1599#define wcscopy(alloc, wcssrc, wcsdst) wcssub(alloc, wcssrc, 0x0, 0x0, wcsdst)
1600
1601
1602/* Deprecated. */
1603#define wcsini_errmsg wcs_errmsg
1604#define wcssub_errmsg wcs_errmsg
1605#define wcscopy_errmsg wcs_errmsg
1606#define wcsfree_errmsg wcs_errmsg
1607#define wcsprt_errmsg wcs_errmsg
1608#define wcsset_errmsg wcs_errmsg
1609#define wcsp2s_errmsg wcs_errmsg
1610#define wcss2p_errmsg wcs_errmsg
1611#define wcsmix_errmsg wcs_errmsg
1612
1613#ifdef __cplusplus
1614#undef wtbarr
1615}
1616#endif
1617
1618#endif /* WCSLIB_WCS */
1619