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