WCSLIB  7.12
wcs.h
Go to the documentation of this file.
1 /*============================================================================
2  WCSLIB 7.12 - an implementation of the FITS WCS standard.
3  Copyright (C) 1995-2022, Mark Calabretta
4 
5  This file is part of WCSLIB.
6 
7  WCSLIB is free software: you can redistribute it and/or modify it under the
8  terms of the GNU Lesser General Public License as published by the Free
9  Software Foundation, either version 3 of the License, or (at your option)
10  any later version.
11 
12  WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
13  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
14  FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
15  more details.
16 
17  You should have received a copy of the GNU Lesser General Public License
18  along with WCSLIB. If not, see http://www.gnu.org/licenses.
19 
20  Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
21  http://www.atnf.csiro.au/people/Mark.Calabretta
22  $Id: wcs.h,v 7.12 2022/09/09 04:57:58 mcalabre Exp $
23 *=============================================================================
24 *
25 * WCSLIB 7.12 - C routines that implement the FITS World Coordinate System
26 * (WCS) standard. Refer to the README file provided with WCSLIB for an
27 * overview of the library.
28 *
29 *
30 * Summary of the wcs routines
31 * ---------------------------
32 * Routines in this suite implement the FITS World Coordinate System (WCS)
33 * standard which defines methods to be used for computing world coordinates
34 * from image pixel coordinates, and vice versa. The standard, and proposed
35 * extensions for handling distortions, are described in
36 *
37 = "Representations of world coordinates in FITS",
38 = Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
39 =
40 = "Representations of celestial coordinates in FITS",
41 = Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (WCS Paper II)
42 =
43 = "Representations of spectral coordinates in FITS",
44 = Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
45 = 2006, A&A, 446, 747 (WCS Paper III)
46 =
47 = "Representations of distortions in FITS world coordinate systems",
48 = Calabretta, M.R. et al. (WCS Paper IV, draft dated 2004/04/22),
49 = available from http://www.atnf.csiro.au/people/Mark.Calabretta
50 =
51 = "Mapping on the HEALPix grid",
52 = Calabretta, M.R., & Roukema, B.F. 2007, MNRAS, 381, 865 (WCS Paper V)
53 =
54 = "Representing the 'Butterfly' Projection in FITS -- Projection Code XPH",
55 = Calabretta, M.R., & Lowe, S.R. 2013, PASA, 30, e050 (WCS Paper VI)
56 =
57 = "Representations of time coordinates in FITS -
58 = Time and relative dimension in space",
59 = Rots, A.H., Bunclark, P.S., Calabretta, M.R., Allen, S.L.,
60 = Manchester, R.N., & Thompson, W.T. 2015, A&A, 574, A36 (WCS Paper VII)
61 *
62 * These routines are based on the wcsprm struct which contains all information
63 * needed for the computations. The struct contains some members that must be
64 * set by the user, and others that are maintained by these routines, somewhat
65 * like a C++ class but with no encapsulation.
66 *
67 * wcsnpv(), wcsnps(), wcsini(), wcsinit(), wcssub(), wcsfree(), and wcstrim(),
68 * are provided to manage the wcsprm struct, wcssize() computes its total size
69 * including allocated memory, and wcsprt() prints its contents. Refer to the
70 * description of the wcsprm struct for an explanation of the anticipated usage
71 * of these routines. wcscopy(), which does a deep copy of one wcsprm struct
72 * to another, is defined as a preprocessor macro function that invokes
73 * wcssub().
74 *
75 * wcsperr() prints the error message(s) (if any) stored in a wcsprm struct,
76 * and the linprm, celprm, prjprm, spcprm, and tabprm structs that it contains.
77 *
78 * A setup routine, wcsset(), computes intermediate values in the wcsprm struct
79 * from parameters in it that were supplied by the user. The struct always
80 * needs to be set up by wcsset() but this need not be called explicitly -
81 * refer to the explanation of wcsprm::flag.
82 *
83 * wcsp2s() and wcss2p() implement the WCS world coordinate transformations.
84 * In fact, they are high level driver routines for the WCS linear,
85 * logarithmic, celestial, spectral and tabular transformation routines
86 * described in lin.h, log.h, cel.h, spc.h and tab.h.
87 *
88 * Given either the celestial longitude or latitude plus an element of the
89 * pixel coordinate a hybrid routine, wcsmix(), iteratively solves for the
90 * unknown elements.
91 *
92 * wcsccs() changes the celestial coordinate system of a wcsprm struct, for
93 * example, from equatorial to galactic, and wcssptr() translates the spectral
94 * axis. For example, a 'FREQ' axis may be translated into 'ZOPT-F2W' and vice
95 * versa.
96 *
97 * wcslib_version() returns the WCSLIB version number.
98 *
99 * Quadcube projections:
100 * ---------------------
101 * The quadcube projections (TSC, CSC, QSC) may be represented in FITS in
102 * either of two ways:
103 *
104 * a: The six faces may be laid out in one plane and numbered as follows:
105 *
106 = 0
107 =
108 = 4 3 2 1 4 3 2
109 =
110 = 5
111 *
112 * Faces 2, 3 and 4 may appear on one side or the other (or both). The
113 * world-to-pixel routines map faces 2, 3 and 4 to the left but the
114 * pixel-to-world routines accept them on either side.
115 *
116 * b: The "COBE" convention in which the six faces are stored in a
117 * three-dimensional structure using a CUBEFACE axis indexed from
118 * 0 to 5 as above.
119 *
120 * These routines support both methods; wcsset() determines which is being
121 * used by the presence or absence of a CUBEFACE axis in ctype[]. wcsp2s()
122 * and wcss2p() translate the CUBEFACE axis representation to the single
123 * plane representation understood by the lower-level WCSLIB projection
124 * routines.
125 *
126 *
127 * wcsnpv() - Memory allocation for PVi_ma
128 * ---------------------------------------
129 * wcsnpv() sets or gets the value of NPVMAX (default 64). This global
130 * variable controls the number of pvcard structs, for holding PVi_ma
131 * keyvalues, that wcsini() should allocate space for. It is also used by
132 * wcsinit() as the default value of npvmax.
133 *
134 * PLEASE NOTE: This function is not thread-safe.
135 *
136 * Given:
137 * n int Value of NPVMAX; ignored if < 0. Use a value less
138 * than zero to get the current value.
139 *
140 * Function return value:
141 * int Current value of NPVMAX.
142 *
143 *
144 * wcsnps() - Memory allocation for PSi_ma
145 * ---------------------------------------
146 * wcsnps() sets or gets the value of NPSMAX (default 8). This global variable
147 * controls the number of pscard structs, for holding PSi_ma keyvalues, that
148 * wcsini() should allocate space for. It is also used by wcsinit() as the
149 * default value of npsmax.
150 *
151 * PLEASE NOTE: This function is not thread-safe.
152 *
153 * Given:
154 * n int Value of NPSMAX; ignored if < 0. Use a value less
155 * than zero to get the current value.
156 *
157 * Function return value:
158 * int Current value of NPSMAX.
159 *
160 *
161 * wcsini() - Default constructor for the wcsprm struct
162 * ----------------------------------------------------
163 * wcsini() is a thin wrapper on wcsinit(). It invokes it with npvmax,
164 * npsmax, and ndpmax set to -1 which causes it to use the values of the
165 * global variables NDPMAX, NPSMAX, and NDPMAX. It is thereby potentially
166 * thread-unsafe if these variables are altered dynamically via wcsnpv(),
167 * wcsnps(), and disndp(). Use wcsinit() for a thread-safe alternative in
168 * this case.
169 *
170 *
171 * wcsinit() - Default constructor for the wcsprm struct
172 * -----------------------------------------------------
173 * wcsinit() optionally allocates memory for arrays in a wcsprm struct and sets
174 * all members of the struct to default values.
175 *
176 * PLEASE NOTE: every wcsprm struct should be initialized by wcsinit(),
177 * possibly repeatedly. On the first invokation, and only the first
178 * invokation, wcsprm::flag must be set to -1 to initialize memory management,
179 * regardless of whether wcsinit() will actually be used to allocate memory.
180 *
181 * Given:
182 * alloc int If true, allocate memory unconditionally for the
183 * crpix, etc. arrays. Please note that memory is never
184 * allocated by wcsinit() for the auxprm, tabprm, nor
185 * wtbarr structs.
186 *
187 * If false, it is assumed that pointers to these arrays
188 * have been set by the user except if they are null
189 * pointers in which case memory will be allocated for
190 * them regardless. (In other words, setting alloc true
191 * saves having to initalize these pointers to zero.)
192 *
193 * naxis int The number of world coordinate axes. This is used to
194 * determine the length of the various wcsprm vectors and
195 * matrices and therefore the amount of memory to
196 * allocate for them.
197 *
198 * Given and returned:
199 * wcs struct wcsprm*
200 * Coordinate transformation parameters.
201 *
202 * Note that, in order to initialize memory management,
203 * wcsprm::flag should be set to -1 when wcs is
204 * initialized for the first time (memory leaks may
205 * result if it had already been initialized).
206 *
207 * Given:
208 * npvmax int The number of PVi_ma keywords to allocate space for.
209 * If set to -1, the value of the global variable NPVMAX
210 * will be used. This is potentially thread-unsafe if
211 * wcsnpv() is being used dynamically to alter its value.
212 *
213 * npsmax int The number of PSi_ma keywords to allocate space for.
214 * If set to -1, the value of the global variable NPSMAX
215 * will be used. This is potentially thread-unsafe if
216 * wcsnps() is being used dynamically to alter its value.
217 *
218 * ndpmax int The number of DPja or DQia keywords to allocate space
219 * for. If set to -1, the value of the global variable
220 * NDPMAX will be used. This is potentially
221 * thread-unsafe if disndp() is being used dynamically to
222 * alter its value.
223 *
224 * Function return value:
225 * int Status return value:
226 * 0: Success.
227 * 1: Null wcsprm pointer passed.
228 * 2: Memory allocation failed.
229 *
230 * For returns > 1, a detailed error message is set in
231 * wcsprm::err if enabled, see wcserr_enable().
232 *
233 *
234 * wcsauxi() - Default constructor for the auxprm struct
235 * -----------------------------------------------------
236 * wcsauxi() optionally allocates memory for an auxprm struct, attaches it to
237 * wcsprm, and sets all members of the struct to default values.
238 *
239 * Given:
240 * alloc int If true, allocate memory unconditionally for the
241 * auxprm struct.
242 *
243 * If false, it is assumed that wcsprm::aux has already
244 * been set to point to an auxprm struct, in which case
245 * the user is responsible for managing that memory.
246 * However, if wcsprm::aux is a null pointer, memory will
247 * be allocated regardless. (In other words, setting
248 * alloc true saves having to initalize the pointer to
249 * zero.)
250 *
251 * Given and returned:
252 * wcs struct wcsprm*
253 * Coordinate transformation parameters.
254 *
255 * Function return value:
256 * int Status return value:
257 * 0: Success.
258 * 1: Null wcsprm pointer passed.
259 * 2: Memory allocation failed.
260 *
261 *
262 * wcssub() - Subimage extraction routine for the wcsprm struct
263 * ------------------------------------------------------------
264 * wcssub() extracts the coordinate description for a subimage from a wcsprm
265 * struct. It does a deep copy, using wcsinit() to allocate memory for its
266 * arrays if required. Only the "information to be provided" part of the
267 * struct is extracted. Consequently, wcsset() need not have been, and won't
268 * be invoked on the struct from which the subimage is extracted. A call to
269 * wcsset() is required to set up the subimage struct.
270 *
271 * The world coordinate system of the subimage must be separable in the sense
272 * that the world coordinates at any point in the subimage must depend only on
273 * the pixel coordinates of the axes extracted. In practice, this means that
274 * the linear transformation matrix of the original image must not contain
275 * non-zero off-diagonal terms that associate any of the subimage axes with any
276 * of the non-subimage axes. Likewise, if any distortions are associated with
277 * the subimage axes, they must not depend on any of the axes that are not
278 * being extracted.
279 *
280 * Note that while the required elements of the tabprm array are extracted, the
281 * wtbarr array is not. (Thus it is not appropriate to call wcssub() after
282 * wcstab() but before filling the tabprm structs - refer to wcshdr.h.)
283 *
284 * wcssub() can also add axes to a wcsprm struct. The new axes will be created
285 * using the defaults set by wcsinit() which produce a simple, unnamed, linear
286 * axis with world coordinate equal to the pixel coordinate. These default
287 * values can be changed afterwards, before invoking wcsset().
288 *
289 * Given:
290 * alloc int If true, allocate memory for the crpix, etc. arrays in
291 * the destination. Otherwise, it is assumed that
292 * pointers to these arrays have been set by the user
293 * except if they are null pointers in which case memory
294 * will be allocated for them regardless.
295 *
296 * wcssrc const struct wcsprm*
297 * Struct to extract from.
298 *
299 * Given and returned:
300 * nsub int*
301 * axes int[] Vector of length *nsub containing the image axis
302 * numbers (1-relative) to extract. Order is
303 * significant; axes[0] is the axis number of the input
304 * image that corresponds to the first axis in the
305 * subimage, etc.
306 *
307 * Use an axis number of 0 to create a new axis using
308 * the defaults set by wcsinit(). They can be changed
309 * later.
310 *
311 * nsub (the pointer) may be set to zero, and so also may
312 * *nsub, which is interpreted to mean all axes in the
313 * input image; the number of axes will be returned if
314 * nsub != 0x0. axes itself (the pointer) may be set to
315 * zero to indicate the first *nsub axes in their
316 * original order.
317 *
318 * Set both nsub (or *nsub) and axes to zero to do a deep
319 * copy of one wcsprm struct to another.
320 *
321 * Subimage extraction by coordinate axis type may be
322 * done by setting the elements of axes[] to the
323 * following special preprocessor macro values:
324 *
325 * WCSSUB_LONGITUDE: Celestial longitude.
326 * WCSSUB_LATITUDE: Celestial latitude.
327 * WCSSUB_CUBEFACE: Quadcube CUBEFACE axis.
328 * WCSSUB_SPECTRAL: Spectral axis.
329 * WCSSUB_STOKES: Stokes axis.
330 * WCSSUB_TIME: Time axis.
331 *
332 * Refer to the notes (below) for further usage examples.
333 *
334 * On return, *nsub will be set to the number of axes in
335 * the subimage; this may be zero if there were no axes
336 * of the required type(s) (in which case no memory will
337 * be allocated). axes[] will contain the axis numbers
338 * that were extracted, or 0 for newly created axes. The
339 * vector length must be sufficient to contain all axis
340 * numbers. No checks are performed to verify that the
341 * coordinate axes are consistent, this is done by
342 * wcsset().
343 *
344 * wcsdst struct wcsprm*
345 * Struct describing the subimage. wcsprm::flag should
346 * be set to -1 if wcsdst was not previously initialized
347 * (memory leaks may result if it was previously
348 * initialized).
349 *
350 * Function return value:
351 * int Status return value:
352 * 0: Success.
353 * 1: Null wcsprm pointer passed.
354 * 2: Memory allocation failed.
355 * 12: Invalid subimage specification.
356 * 13: Non-separable subimage coordinate system.
357 *
358 * For returns > 1, a detailed error message is set in
359 * wcsprm::err if enabled, see wcserr_enable().
360 *
361 * Notes:
362 * 1: Combinations of subimage axes of particular types may be extracted in
363 * the same order as they occur in the input image by combining
364 * preprocessor codes, for example
365 *
366 = *nsub = 1;
367 = axes[0] = WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_SPECTRAL;
368 *
369 * would extract the longitude, latitude, and spectral axes in the same
370 * order as the input image. If one of each were present, *nsub = 3 would
371 * be returned.
372 *
373 * For convenience, WCSSUB_CELESTIAL is defined as the combination
374 * WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_CUBEFACE.
375 *
376 * The codes may also be negated to extract all but the types specified,
377 * for example
378 *
379 = *nsub = 4;
380 = axes[0] = WCSSUB_LONGITUDE;
381 = axes[1] = WCSSUB_LATITUDE;
382 = axes[2] = WCSSUB_CUBEFACE;
383 = axes[3] = -(WCSSUB_SPECTRAL | WCSSUB_STOKES);
384 *
385 * The last of these specifies all axis types other than spectral or
386 * Stokes. Extraction is done in the order specified by axes[] a
387 * longitude axis (if present) would be extracted first (via axes[0]) and
388 * not subsequently (via axes[3]). Likewise for the latitude and cubeface
389 * axes in this example.
390 *
391 * From the foregoing, it is apparent that the value of *nsub returned may
392 * be less than or greater than that given. However, it will never exceed
393 * the number of axes in the input image (plus the number of newly-created
394 * axes if any were specified on input).
395 *
396 *
397 * wcscompare() - Compare two wcsprm structs for equality
398 * ------------------------------------------------------
399 * wcscompare() compares two wcsprm structs for equality.
400 *
401 * Given:
402 * cmp int A bit field controlling the strictness of the
403 * comparison. When 0, all fields must be identical.
404 *
405 * The following constants may be or'ed together to
406 * relax the comparison:
407 * WCSCOMPARE_ANCILLARY: Ignore ancillary keywords
408 * that don't change the WCS transformation, such
409 * as DATE-OBS or EQUINOX.
410 * WCSCOMPARE_TILING: Ignore integral differences in
411 * CRPIXja. This is the 'tiling' condition, where
412 * two WCSes cover different regions of the same
413 * map projection and align on the same map grid.
414 * WCSCOMPARE_CRPIX: Ignore any differences at all in
415 * CRPIXja. The two WCSes cover different regions
416 * of the same map projection but may not align on
417 * the same map grid. Overrides WCSCOMPARE_TILING.
418 *
419 * tol double Tolerance for comparison of floating-point values.
420 * For example, for tol == 1e-6, all floating-point
421 * values in the structs must be equal to the first 6
422 * decimal places. A value of 0 implies exact equality.
423 *
424 * wcs1 const struct wcsprm*
425 * The first wcsprm struct to compare.
426 *
427 * wcs2 const struct wcsprm*
428 * The second wcsprm struct to compare.
429 *
430 * Returned:
431 * equal int* Non-zero when the given structs are equal.
432 *
433 * Function return value:
434 * int Status return value:
435 * 0: Success.
436 * 1: Null pointer passed.
437 *
438 *
439 * wcscopy() macro - Copy routine for the wcsprm struct
440 * ----------------------------------------------------
441 * wcscopy() does a deep copy of one wcsprm struct to another. As of
442 * WCSLIB 3.6, it is implemented as a preprocessor macro that invokes
443 * wcssub() with the nsub and axes pointers both set to zero.
444 *
445 *
446 * wcsfree() - Destructor for the wcsprm struct
447 * --------------------------------------------
448 * wcsfree() frees memory allocated for the wcsprm arrays by wcsinit() and/or
449 * wcsset(). wcsinit() records the memory it allocates and wcsfree() will only
450 * attempt to free this.
451 *
452 * PLEASE NOTE: wcsfree() must not be invoked on a wcsprm struct that was not
453 * initialized by wcsinit().
454 *
455 * Given and returned:
456 * wcs struct wcsprm*
457 * Coordinate transformation parameters.
458 *
459 * Function return value:
460 * int Status return value:
461 * 0: Success.
462 * 1: Null wcsprm pointer passed.
463 *
464 *
465 * wcstrim() - Free unused arrays in the wcsprm struct
466 * ---------------------------------------------------
467 * wcstrim() frees memory allocated by wcsinit() for arrays in the wcsprm
468 * struct that remains unused after it has been set up by wcsset().
469 *
470 * The free'd array members are associated with FITS WCS keyrecords that are
471 * rarely used and usually just bloat the struct: wcsprm::crota, wcsprm::colax,
472 * wcsprm::cname, wcsprm::crder, wcsprm::csyer, wcsprm::czphs, and
473 * wcsprm::cperi. If unused, wcsprm::pv, wcsprm::ps, and wcsprm::cd are also
474 * freed.
475 *
476 * Once these arrays have been freed, a test such as
477 =
478 = if (!undefined(wcs->cname[i])) {...}
479 =
480 * must be protected as follows
481 =
482 = if (wcs->cname && !undefined(wcs->cname[i])) {...}
483 =
484 * In addition, if wcsprm::npv is non-zero but less than wcsprm::npvmax, then
485 * the unused space in wcsprm::pv will be recovered (using realloc()).
486 * Likewise for wcsprm::ps.
487 *
488 * Given and returned:
489 * wcs struct wcsprm*
490 * Coordinate transformation parameters.
491 *
492 * Function return value:
493 * int Status return value:
494 * 0: Success.
495 * 1: Null wcsprm pointer passed.
496 * 14: wcsprm struct is unset.
497 *
498 *
499 * wcssize() - Compute the size of a wcsprm struct
500 * -----------------------------------------------
501 * wcssize() computes the full size of a wcsprm struct, including allocated
502 * memory.
503 *
504 * Given:
505 * wcs const struct wcsprm*
506 * Coordinate transformation parameters.
507 *
508 * If NULL, the base size of the struct and the allocated
509 * size are both set to zero.
510 *
511 * Returned:
512 * sizes int[2] The first element is the base size of the struct as
513 * returned by sizeof(struct wcsprm). The second element
514 * is the total allocated size, in bytes, assuming that
515 * the allocation was done by wcsini(). This figure
516 * includes memory allocated for members of constituent
517 * structs, such as wcsprm::lin.
518 *
519 * It is not an error for the struct not to have been set
520 * up via wcsset(), which normally results in additional
521 * memory allocation.
522 *
523 * Function return value:
524 * int Status return value:
525 * 0: Success.
526 *
527 *
528 * auxsize() - Compute the size of a auxprm struct
529 * -----------------------------------------------
530 * auxsize() computes the full size of a auxprm struct, including allocated
531 * memory.
532 *
533 * Given:
534 * aux const struct auxprm*
535 * Auxiliary coordinate information.
536 *
537 * If NULL, the base size of the struct and the allocated
538 * size are both set to zero.
539 *
540 * Returned:
541 * sizes int[2] The first element is the base size of the struct as
542 * returned by sizeof(struct auxprm). The second element
543 * is the total allocated size, in bytes, currently zero.
544 *
545 * Function return value:
546 * int Status return value:
547 * 0: Success.
548 *
549 *
550 * wcsprt() - Print routine for the wcsprm struct
551 * ----------------------------------------------
552 * wcsprt() prints the contents of a wcsprm struct using wcsprintf(). Mainly
553 * intended for diagnostic purposes.
554 *
555 * Given:
556 * wcs const struct wcsprm*
557 * Coordinate transformation parameters.
558 *
559 * Function return value:
560 * int Status return value:
561 * 0: Success.
562 * 1: Null wcsprm pointer passed.
563 *
564 *
565 * wcsperr() - Print error messages from a wcsprm struct
566 * -----------------------------------------------------
567 * wcsperr() prints the error message(s), if any, stored in a wcsprm struct,
568 * and the linprm, celprm, prjprm, spcprm, and tabprm structs that it contains.
569 * If there are no errors then nothing is printed. It uses wcserr_prt(), q.v.
570 *
571 * Given:
572 * wcs const struct wcsprm*
573 * Coordinate transformation parameters.
574 *
575 * prefix const char *
576 * If non-NULL, each output line will be prefixed with
577 * this string.
578 *
579 * Function return value:
580 * int Status return value:
581 * 0: Success.
582 * 1: Null wcsprm pointer passed.
583 *
584 *
585 * wcsbchk() - Enable/disable bounds checking
586 * ------------------------------------------
587 * wcsbchk() is used to control bounds checking in the projection routines.
588 * Note that wcsset() always enables bounds checking. wcsbchk() will invoke
589 * wcsset() on the wcsprm struct beforehand if necessary.
590 *
591 * Given and returned:
592 * wcs struct wcsprm*
593 * Coordinate transformation parameters.
594 *
595 * Given:
596 * bounds int If bounds&1 then enable strict bounds checking for the
597 * spherical-to-Cartesian (s2x) transformation for the
598 * AZP, SZP, TAN, SIN, ZPN, and COP projections.
599 *
600 * If bounds&2 then enable strict bounds checking for the
601 * Cartesian-to-spherical (x2s) transformation for the
602 * HPX and XPH projections.
603 *
604 * If bounds&4 then enable bounds checking on the native
605 * coordinates returned by the Cartesian-to-spherical
606 * (x2s) transformations using prjchk().
607 *
608 * Zero it to disable all checking.
609 *
610 * Function return value:
611 * int Status return value:
612 * 0: Success.
613 * 1: Null wcsprm pointer passed.
614 *
615 *
616 * wcsset() - Setup routine for the wcsprm struct
617 * ----------------------------------------------
618 * wcsset() sets up a wcsprm struct according to information supplied within
619 * it (refer to the description of the wcsprm struct).
620 *
621 * wcsset() recognizes the NCP projection and converts it to the equivalent SIN
622 * projection and likewise translates GLS into SFL. It also translates the
623 * AIPS spectral types ('FREQ-LSR', 'FELO-HEL', etc.), possibly changing the
624 * input header keywords wcsprm::ctype and/or wcsprm::specsys if necessary.
625 *
626 * Note that this routine need not be called directly; it will be invoked by
627 * wcsp2s() and wcss2p() if the wcsprm::flag is anything other than a
628 * predefined magic value.
629 *
630 * Given and returned:
631 * wcs struct wcsprm*
632 * Coordinate transformation parameters.
633 *
634 * Function return value:
635 * int Status return value:
636 * 0: Success.
637 * 1: Null wcsprm pointer passed.
638 * 2: Memory allocation failed.
639 * 3: Linear transformation matrix is singular.
640 * 4: Inconsistent or unrecognized coordinate axis
641 * types.
642 * 5: Invalid parameter value.
643 * 6: Invalid coordinate transformation parameters.
644 * 7: Ill-conditioned coordinate transformation
645 * parameters.
646 *
647 * For returns > 1, a detailed error message is set in
648 * wcsprm::err if enabled, see wcserr_enable().
649 *
650 * Notes:
651 * 1: wcsset() always enables strict bounds checking in the projection
652 * routines (via a call to prjini()). Use wcsbchk() to modify
653 * bounds-checking after wcsset() is invoked.
654 *
655 *
656 * wcsp2s() - Pixel-to-world transformation
657 * ----------------------------------------
658 * wcsp2s() transforms pixel coordinates to world coordinates.
659 *
660 * Given and returned:
661 * wcs struct wcsprm*
662 * Coordinate transformation parameters.
663 *
664 * Given:
665 * ncoord,
666 * nelem int The number of coordinates, each of vector length
667 * nelem but containing wcs.naxis coordinate elements.
668 * Thus nelem must equal or exceed the value of the
669 * NAXIS keyword unless ncoord == 1, in which case nelem
670 * is not used.
671 *
672 * pixcrd const double[ncoord][nelem]
673 * Array of pixel coordinates.
674 *
675 * Returned:
676 * imgcrd double[ncoord][nelem]
677 * Array of intermediate world coordinates. For
678 * celestial axes, imgcrd[][wcs.lng] and
679 * imgcrd[][wcs.lat] are the projected x-, and
680 * y-coordinates in pseudo "degrees". For spectral
681 * axes, imgcrd[][wcs.spec] is the intermediate spectral
682 * coordinate, in SI units.
683 *
684 * phi,theta double[ncoord]
685 * Longitude and latitude in the native coordinate system
686 * of the projection [deg].
687 *
688 * world double[ncoord][nelem]
689 * Array of world coordinates. For celestial axes,
690 * world[][wcs.lng] and world[][wcs.lat] are the
691 * celestial longitude and latitude [deg]. For
692 * spectral axes, imgcrd[][wcs.spec] is the intermediate
693 * spectral coordinate, in SI units.
694 *
695 * stat int[ncoord]
696 * Status return value for each coordinate:
697 * 0: Success.
698 * 1+: A bit mask indicating invalid pixel coordinate
699 * element(s).
700 *
701 * Function return value:
702 * int Status return value:
703 * 0: Success.
704 * 1: Null wcsprm pointer passed.
705 * 2: Memory allocation failed.
706 * 3: Linear transformation matrix is singular.
707 * 4: Inconsistent or unrecognized coordinate axis
708 * types.
709 * 5: Invalid parameter value.
710 * 6: Invalid coordinate transformation parameters.
711 * 7: Ill-conditioned coordinate transformation
712 * parameters.
713 * 8: One or more of the pixel coordinates were
714 * invalid, as indicated by the stat vector.
715 *
716 * For returns > 1, a detailed error message is set in
717 * wcsprm::err if enabled, see wcserr_enable().
718 *
719 *
720 * wcss2p() - World-to-pixel transformation
721 * ----------------------------------------
722 * wcss2p() transforms world coordinates to pixel coordinates.
723 *
724 * Given and returned:
725 * wcs struct wcsprm*
726 * Coordinate transformation parameters.
727 *
728 * Given:
729 * ncoord,
730 * nelem int The number of coordinates, each of vector length nelem
731 * but containing wcs.naxis coordinate elements. Thus
732 * nelem must equal or exceed the value of the NAXIS
733 * keyword unless ncoord == 1, in which case nelem is not
734 * used.
735 *
736 * world const double[ncoord][nelem]
737 * Array of world coordinates. For celestial axes,
738 * world[][wcs.lng] and world[][wcs.lat] are the
739 * celestial longitude and latitude [deg]. For spectral
740 * axes, world[][wcs.spec] is the spectral coordinate, in
741 * SI units.
742 *
743 * Returned:
744 * phi,theta double[ncoord]
745 * Longitude and latitude in the native coordinate
746 * system of the projection [deg].
747 *
748 * imgcrd double[ncoord][nelem]
749 * Array of intermediate world coordinates. For
750 * celestial axes, imgcrd[][wcs.lng] and
751 * imgcrd[][wcs.lat] are the projected x-, and
752 * y-coordinates in pseudo "degrees". For quadcube
753 * projections with a CUBEFACE axis the face number is
754 * also returned in imgcrd[][wcs.cubeface]. For
755 * spectral axes, imgcrd[][wcs.spec] is the intermediate
756 * spectral coordinate, in SI units.
757 *
758 * pixcrd double[ncoord][nelem]
759 * Array of pixel coordinates.
760 *
761 * stat int[ncoord]
762 * Status return value for each coordinate:
763 * 0: Success.
764 * 1+: A bit mask indicating invalid world coordinate
765 * element(s).
766 *
767 * Function return value:
768 * int Status return value:
769 * 0: Success.
770 * 1: Null wcsprm pointer passed.
771 * 2: Memory allocation failed.
772 * 3: Linear transformation matrix is singular.
773 * 4: Inconsistent or unrecognized coordinate axis
774 * types.
775 * 5: Invalid parameter value.
776 * 6: Invalid coordinate transformation parameters.
777 * 7: Ill-conditioned coordinate transformation
778 * parameters.
779 * 9: One or more of the world coordinates were
780 * invalid, as indicated by the stat vector.
781 *
782 * For returns > 1, a detailed error message is set in
783 * wcsprm::err if enabled, see wcserr_enable().
784 *
785 *
786 * wcsmix() - Hybrid coordinate transformation
787 * -------------------------------------------
788 * wcsmix(), given either the celestial longitude or latitude plus an element
789 * of the pixel coordinate, solves for the remaining elements by iterating on
790 * the unknown celestial coordinate element using wcss2p(). Refer also to the
791 * notes below.
792 *
793 * Given and returned:
794 * wcs struct wcsprm*
795 * Indices for the celestial coordinates obtained
796 * by parsing the wcsprm::ctype[].
797 *
798 * Given:
799 * mixpix int Which element of the pixel coordinate is given.
800 *
801 * mixcel int Which element of the celestial coordinate is given:
802 * 1: Celestial longitude is given in
803 * world[wcs.lng], latitude returned in
804 * world[wcs.lat].
805 * 2: Celestial latitude is given in
806 * world[wcs.lat], longitude returned in
807 * world[wcs.lng].
808 *
809 * vspan const double[2]
810 * Solution interval for the celestial coordinate [deg].
811 * The ordering of the two limits is irrelevant.
812 * Longitude ranges may be specified with any convenient
813 * normalization, for example [-120,+120] is the same as
814 * [240,480], except that the solution will be returned
815 * with the same normalization, i.e. lie within the
816 * interval specified.
817 *
818 * vstep const double
819 * Step size for solution search [deg]. If zero, a
820 * sensible, although perhaps non-optimal default will be
821 * used.
822 *
823 * viter int If a solution is not found then the step size will be
824 * halved and the search recommenced. viter controls how
825 * many times the step size is halved. The allowed range
826 * is 5 - 10.
827 *
828 * Given and returned:
829 * world double[naxis]
830 * World coordinate elements. world[wcs.lng] and
831 * world[wcs.lat] are the celestial longitude and
832 * latitude [deg]. Which is given and which returned
833 * depends on the value of mixcel. All other elements
834 * are given.
835 *
836 * Returned:
837 * phi,theta double[naxis]
838 * Longitude and latitude in the native coordinate
839 * system of the projection [deg].
840 *
841 * imgcrd double[naxis]
842 * Image coordinate elements. imgcrd[wcs.lng] and
843 * imgcrd[wcs.lat] are the projected x-, and
844 * y-coordinates in pseudo "degrees".
845 *
846 * Given and returned:
847 * pixcrd double[naxis]
848 * Pixel coordinate. The element indicated by mixpix is
849 * given and the remaining elements are returned.
850 *
851 * Function return value:
852 * int Status return value:
853 * 0: Success.
854 * 1: Null wcsprm pointer passed.
855 * 2: Memory allocation failed.
856 * 3: Linear transformation matrix is singular.
857 * 4: Inconsistent or unrecognized coordinate axis
858 * types.
859 * 5: Invalid parameter value.
860 * 6: Invalid coordinate transformation parameters.
861 * 7: Ill-conditioned coordinate transformation
862 * parameters.
863 * 10: Invalid world coordinate.
864 * 11: No solution found in the specified interval.
865 *
866 * For returns > 1, a detailed error message is set in
867 * wcsprm::err if enabled, see wcserr_enable().
868 *
869 * Notes:
870 * 1: Initially the specified solution interval is checked to see if it's a
871 * "crossing" interval. If it isn't, a search is made for a crossing
872 * solution by iterating on the unknown celestial coordinate starting at
873 * the upper limit of the solution interval and decrementing by the
874 * specified step size. A crossing is indicated if the trial value of the
875 * pixel coordinate steps through the value specified. If a crossing
876 * interval is found then the solution is determined by a modified form of
877 * "regula falsi" division of the crossing interval. If no crossing
878 * interval was found within the specified solution interval then a search
879 * is made for a "non-crossing" solution as may arise from a point of
880 * tangency. The process is complicated by having to make allowance for
881 * the discontinuities that occur in all map projections.
882 *
883 * Once one solution has been determined others may be found by subsequent
884 * invokations of wcsmix() with suitably restricted solution intervals.
885 *
886 * Note the circumstance that arises when the solution point lies at a
887 * native pole of a projection in which the pole is represented as a
888 * finite curve, for example the zenithals and conics. In such cases two
889 * or more valid solutions may exist but wcsmix() only ever returns one.
890 *
891 * Because of its generality wcsmix() is very compute-intensive. For
892 * compute-limited applications more efficient special-case solvers could
893 * be written for simple projections, for example non-oblique cylindrical
894 * projections.
895 *
896 *
897 * wcsccs() - Change celestial coordinate system
898 * ---------------------------------------------
899 * wcsccs() changes the celestial coordinate system of a wcsprm struct. For
900 * example, from equatorial to galactic coordinates.
901 *
902 * Parameters that define the spherical coordinate transformation, essentially
903 * being three Euler angles, must be provided. Thereby wcsccs() does not need
904 * prior knowledge of specific celestial coordinate systems. It also has the
905 * advantage of making it completely general.
906 *
907 * Auxiliary members of the wcsprm struct relating to equatorial celestial
908 * coordinate systems may also be changed.
909 *
910 * Only orthodox spherical coordinate systems are supported. That is, they
911 * must be right-handed, with latitude increasing from zero at the equator to
912 * +90 degrees at the pole. This precludes systems such as aziumuth and zenith
913 * distance, which, however, could be handled as negative azimuth and
914 * elevation.
915 *
916 * PLEASE NOTE: Information in the wcsprm struct relating to the original
917 * coordinate system will be overwritten and therefore lost. If this is
918 * undesirable, invoke wcsccs() on a copy of the struct made with wcssub().
919 * The wcsprm struct is reset on return with an explicit call to wcsset().
920 *
921 * Given and returned:
922 * wcs struct wcsprm*
923 * Coordinate transformation parameters. Particular
924 * "values to be given" elements of the wcsprm struct
925 * are modified.
926 *
927 * Given:
928 * lng2p1,
929 * lat2p1 double Longitude and latitude in the new celestial coordinate
930 * system of the pole (i.e. latitude +90) of the original
931 * system [deg]. See notes 1 and 2 below.
932 *
933 * lng1p2 double Longitude in the original celestial coordinate system
934 * of the pole (i.e. latitude +90) of the new system
935 * [deg]. See note 1 below.
936 *
937 * clng,clat const char*
938 * Longitude and latitude identifiers of the new CTYPEia
939 * celestial axis codes, without trailing dashes. For
940 * example, "RA" and "DEC" or "GLON" and "GLAT". Up to
941 * four characters are used, longer strings need not be
942 * null-terminated.
943 *
944 * radesys const char*
945 * Used when transforming to equatorial coordinates,
946 * identified by clng == "RA" and clat = "DEC". May be
947 * set to the null pointer to preserve the current value.
948 * Up to 71 characters are used, longer strings need not
949 * be null-terminated.
950 *
951 * If the new coordinate system is anything other than
952 * equatorial, then wcsprm::radesys will be cleared.
953 *
954 * equinox double Used when transforming to equatorial coordinates. May
955 * be set to zero to preserve the current value.
956 *
957 * If the new coordinate system is not equatorial, then
958 * wcsprm::equinox will be marked as undefined.
959 *
960 * alt const char*
961 * Character code for alternate coordinate descriptions
962 * (i.e. the 'a' in keyword names such as CTYPEia). This
963 * is blank for the primary coordinate description, or
964 * one of the 26 upper-case letters, A-Z. May be set to
965 * the null pointer, or null string if no change is
966 * required.
967 *
968 * Function return value:
969 * int Status return value:
970 * 0: Success.
971 * 1: Null wcsprm pointer passed.
972 * 12: Invalid subimage specification (no celestial
973 * axes).
974 *
975 * Notes:
976 * 1: Follows the prescription given in WCS Paper II, Sect. 2.7 for changing
977 * celestial coordinates.
978 *
979 * The implementation takes account of indeterminacies that arise in that
980 * prescription in the particular cases where one of the poles of the new
981 * system is at the fiducial point, or one of them is at the native pole.
982 *
983 * 2: If lat2p1 == +90, i.e. where the poles of the two coordinate systems
984 * coincide, then the spherical coordinate transformation becomes a simple
985 * change in origin of longitude given by
986 * lng2 = lng1 + (lng2p1 - lng1p2 - 180), and lat2 = lat1, where
987 * (lng2,lat2) are coordinates in the new system, and (lng1,lat1) are
988 * coordinates in the original system.
989 *
990 * Likewise, if lat2p1 == -90, then lng2 = -lng1 + (lng2p1 + lng1p2), and
991 * lat2 = -lat1.
992 *
993 * 3: For example, if the original coordinate system is B1950 equatorial and
994 * the desired new coordinate system is galactic, then
995 *
996 * - (lng2p1,lat2p1) are the galactic coordinates of the B1950 celestial
997 * pole, defined by the IAU to be (123.0,+27.4), and lng1p2 is the B1950
998 * right ascension of the galactic pole, defined as 192.25. Clearly
999 * these coordinates are fixed for a particular coordinate
1000 * transformation.
1001 *
1002 * - (clng,clat) would be 'GLON' and 'GLAT', these being the FITS standard
1003 * identifiers for galactic coordinates.
1004 *
1005 * - Since the new coordinate system is not equatorial, wcsprm::radesys
1006 * and wcsprm::equinox will be cleared.
1007 *
1008 * 4. The coordinates required for some common transformations (obtained from
1009 * https://ned.ipac.caltech.edu/coordinate_calculator) are as follows:
1010 *
1011 = (123.0000,+27.4000) galactic coordinates of B1950 celestial pole,
1012 = (192.2500,+27.4000) B1950 equatorial coordinates of galactic pole.
1013 *
1014 = (122.9319,+27.1283) galactic coordinates of J2000 celestial pole,
1015 = (192.8595,+27.1283) J2000 equatorial coordinates of galactic pole.
1016 *
1017 = (359.6774,+89.7217) B1950 equatorial coordinates of J2000 pole,
1018 = (180.3162,+89.7217) J2000 equatorial coordinates of B1950 pole.
1019 *
1020 = (270.0000,+66.5542) B1950 equatorial coordinates of B1950 ecliptic pole,
1021 = ( 90.0000,+66.5542) B1950 ecliptic coordinates of B1950 celestial pole.
1022 *
1023 = (270.0000,+66.5607) J2000 equatorial coordinates of J2000 ecliptic pole,
1024 = ( 90.0000,+66.5607) J2000 ecliptic coordinates of J2000 celestial pole.
1025 *
1026 = ( 26.7315,+15.6441) supergalactic coordinates of B1950 celestial pole,
1027 = (283.1894,+15.6441) B1950 equatorial coordinates of supergalactic pole.
1028 *
1029 = ( 26.4505,+15.7089) supergalactic coordinates of J2000 celestial pole,
1030 = (283.7542,+15.7089) J2000 equatorial coordinates of supergalactic pole.
1031 *
1032 *
1033 * wcssptr() - Spectral axis translation
1034 * -------------------------------------
1035 * wcssptr() translates the spectral axis in a wcsprm struct. For example, a
1036 * 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.
1037 *
1038 * PLEASE NOTE: Information in the wcsprm struct relating to the original
1039 * coordinate system will be overwritten and therefore lost. If this is
1040 * undesirable, invoke wcssptr() on a copy of the struct made with wcssub().
1041 * The wcsprm struct is reset on return with an explicit call to wcsset().
1042 *
1043 * Given and returned:
1044 * wcs struct wcsprm*
1045 * Coordinate transformation parameters.
1046 *
1047 * i int* Index of the spectral axis (0-relative). If given < 0
1048 * it will be set to the first spectral axis identified
1049 * from the ctype[] keyvalues in the wcsprm struct.
1050 *
1051 * ctype char[9] Desired spectral CTYPEia. Wildcarding may be used as
1052 * for the ctypeS2 argument to spctrn() as described in
1053 * the prologue of spc.h, i.e. if the final three
1054 * characters are specified as "???", or if just the
1055 * eighth character is specified as '?', the correct
1056 * algorithm code will be substituted and returned.
1057 *
1058 * Function return value:
1059 * int Status return value:
1060 * 0: Success.
1061 * 1: Null wcsprm pointer passed.
1062 * 2: Memory allocation failed.
1063 * 3: Linear transformation matrix is singular.
1064 * 4: Inconsistent or unrecognized coordinate axis
1065 * types.
1066 * 5: Invalid parameter value.
1067 * 6: Invalid coordinate transformation parameters.
1068 * 7: Ill-conditioned coordinate transformation
1069 * parameters.
1070 * 12: Invalid subimage specification (no spectral
1071 * axis).
1072 *
1073 * For returns > 1, a detailed error message is set in
1074 * wcsprm::err if enabled, see wcserr_enable().
1075 *
1076 *
1077 * wcslib_version() - WCSLIB version number
1078 * ----------------------------------------
1079 * wcslib_version() returns the WCSLIB version number.
1080 *
1081 * The major version number changes when the ABI changes or when the license
1082 * conditions change. ABI changes typically result from a change to the
1083 * contents of one of the structs. The major version number is used to
1084 * distinguish between incompatible versions of the sharable library.
1085 *
1086 * The minor version number changes with new functionality or bug fixes that do
1087 * not involve a change in the ABI.
1088 *
1089 * The auxiliary version number (which is often absent) signals changes to the
1090 * documentation, test suite, build procedures, or any other change that does
1091 * not affect the compiled library.
1092 *
1093 * Returned:
1094 * vers[3] int[3] The broken-down version number:
1095 * 0: Major version number.
1096 * 1: Minor version number.
1097 * 2: Auxiliary version number (zero if absent).
1098 * May be given as a null pointer if not required.
1099 *
1100 * Function return value:
1101 * char* A null-terminated, statically allocated string
1102 * containing the version number in the usual form, i.e.
1103 * "<major>.<minor>.<auxiliary>".
1104 *
1105 *
1106 * wcsprm struct - Coordinate transformation parameters
1107 * ----------------------------------------------------
1108 * The wcsprm struct contains information required to transform world
1109 * coordinates. It consists of certain members that must be set by the user
1110 * ("given") and others that are set by the WCSLIB routines ("returned").
1111 * While the addresses of the arrays themselves may be set by wcsinit() if it
1112 * (optionally) allocates memory, their contents must be set by the user.
1113 *
1114 * Some parameters that are given are not actually required for transforming
1115 * coordinates. These are described as "auxiliary"; the struct simply provides
1116 * a place to store them, though they may be used by wcshdo() in constructing a
1117 * FITS header from a wcsprm struct. Some of the returned values are supplied
1118 * for informational purposes and others are for internal use only as
1119 * indicated.
1120 *
1121 * In practice, it is expected that a WCS parser would scan the FITS header to
1122 * determine the number of coordinate axes. It would then use wcsinit() to
1123 * allocate memory for arrays in the wcsprm struct and set default values.
1124 * Then as it reread the header and identified each WCS keyrecord it would load
1125 * the value into the relevant wcsprm array element. This is essentially what
1126 * wcspih() does - refer to the prologue of wcshdr.h. As the final step,
1127 * wcsset() is invoked, either directly or indirectly, to set the derived
1128 * members of the wcsprm struct. wcsset() strips off trailing blanks in all
1129 * string members and null-fills the character array.
1130 *
1131 * int flag
1132 * (Given and returned) This flag must be set to zero whenever any of the
1133 * following wcsprm struct members are set or changed:
1134 *
1135 * - wcsprm::naxis (q.v., not normally set by the user),
1136 * - wcsprm::crpix,
1137 * - wcsprm::pc,
1138 * - wcsprm::cdelt,
1139 * - wcsprm::crval,
1140 * - wcsprm::cunit,
1141 * - wcsprm::ctype,
1142 * - wcsprm::lonpole,
1143 * - wcsprm::latpole,
1144 * - wcsprm::restfrq,
1145 * - wcsprm::restwav,
1146 * - wcsprm::npv,
1147 * - wcsprm::pv,
1148 * - wcsprm::nps,
1149 * - wcsprm::ps,
1150 * - wcsprm::cd,
1151 * - wcsprm::crota,
1152 * - wcsprm::altlin,
1153 * - wcsprm::ntab,
1154 * - wcsprm::nwtb,
1155 * - wcsprm::tab,
1156 * - wcsprm::wtb.
1157 *
1158 * This signals the initialization routine, wcsset(), to recompute the
1159 * returned members of the linprm, celprm, spcprm, and tabprm structs.
1160 * wcsset() will reset flag to indicate that this has been done.
1161 *
1162 * PLEASE NOTE: flag should be set to -1 when wcsinit() is called for the
1163 * first time for a particular wcsprm struct in order to initialize memory
1164 * management. It must ONLY be used on the first initialization otherwise
1165 * memory leaks may result.
1166 *
1167 * int naxis
1168 * (Given or returned) Number of pixel and world coordinate elements.
1169 *
1170 * If wcsinit() is used to initialize the linprm struct (as would normally
1171 * be the case) then it will set naxis from the value passed to it as a
1172 * function argument. The user should not subsequently modify it.
1173 *
1174 * double *crpix
1175 * (Given) Address of the first element of an array of double containing
1176 * the coordinate reference pixel, CRPIXja.
1177 *
1178 * double *pc
1179 * (Given) Address of the first element of the PCi_ja (pixel coordinate)
1180 * transformation matrix. The expected order is
1181 *
1182 = struct wcsprm wcs;
1183 = wcs.pc = {PC1_1, PC1_2, PC2_1, PC2_2};
1184 *
1185 * This may be constructed conveniently from a 2-D array via
1186 *
1187 = double m[2][2] = {{PC1_1, PC1_2},
1188 = {PC2_1, PC2_2}};
1189 *
1190 * which is equivalent to
1191 *
1192 = double m[2][2];
1193 = m[0][0] = PC1_1;
1194 = m[0][1] = PC1_2;
1195 = m[1][0] = PC2_1;
1196 = m[1][1] = PC2_2;
1197 *
1198 * The storage order for this 2-D array is the same as for the 1-D array,
1199 * whence
1200 *
1201 = wcs.pc = *m;
1202 *
1203 * would be legitimate.
1204 *
1205 * double *cdelt
1206 * (Given) Address of the first element of an array of double containing
1207 * the coordinate increments, CDELTia.
1208 *
1209 * double *crval
1210 * (Given) Address of the first element of an array of double containing
1211 * the coordinate reference values, CRVALia.
1212 *
1213 * char (*cunit)[72]
1214 * (Given) Address of the first element of an array of char[72] containing
1215 * the CUNITia keyvalues which define the units of measurement of the
1216 * CRVALia, CDELTia, and CDi_ja keywords.
1217 *
1218 * As CUNITia is an optional header keyword, cunit[][72] may be left blank
1219 * but otherwise is expected to contain a standard units specification as
1220 * defined by WCS Paper I. Utility function wcsutrn(), described in
1221 * wcsunits.h, is available to translate commonly used non-standard units
1222 * specifications but this must be done as a separate step before invoking
1223 * wcsset().
1224 *
1225 * For celestial axes, if cunit[][72] is not blank, wcsset() uses
1226 * wcsunits() to parse it and scale cdelt[], crval[], and cd[][*] to
1227 * degrees. It then resets cunit[][72] to "deg".
1228 *
1229 * For spectral axes, if cunit[][72] is not blank, wcsset() uses wcsunits()
1230 * to parse it and scale cdelt[], crval[], and cd[][*] to SI units. It
1231 * then resets cunit[][72] accordingly.
1232 *
1233 * wcsset() ignores cunit[][72] for other coordinate types; cunit[][72] may
1234 * be used to label coordinate values.
1235 *
1236 * These variables accomodate the longest allowed string-valued FITS
1237 * keyword, being limited to 68 characters, plus the null-terminating
1238 * character.
1239 *
1240 * char (*ctype)[72]
1241 * (Given) Address of the first element of an array of char[72] containing
1242 * the coordinate axis types, CTYPEia.
1243 *
1244 * The ctype[][72] keyword values must be in upper case and there must be
1245 * zero or one pair of matched celestial axis types, and zero or one
1246 * spectral axis. The ctype[][72] strings should be padded with blanks on
1247 * the right and null-terminated so that they are at least eight characters
1248 * in length.
1249 *
1250 * These variables accomodate the longest allowed string-valued FITS
1251 * keyword, being limited to 68 characters, plus the null-terminating
1252 * character.
1253 *
1254 * double lonpole
1255 * (Given and returned) The native longitude of the celestial pole, phi_p,
1256 * given by LONPOLEa [deg] or by PVi_2a [deg] attached to the longitude
1257 * axis which takes precedence if defined, and ...
1258 * double latpole
1259 * (Given and returned) ... the native latitude of the celestial pole,
1260 * theta_p, given by LATPOLEa [deg] or by PVi_3a [deg] attached to the
1261 * longitude axis which takes precedence if defined.
1262 *
1263 * lonpole and latpole may be left to default to values set by wcsinit()
1264 * (see celprm::ref), but in any case they will be reset by wcsset() to
1265 * the values actually used. Note therefore that if the wcsprm struct is
1266 * reused without resetting them, whether directly or via wcsinit(), they
1267 * will no longer have their default values.
1268 *
1269 * double restfrq
1270 * (Given) The rest frequency [Hz], and/or ...
1271 * double restwav
1272 * (Given) ... the rest wavelength in vacuo [m], only one of which need be
1273 * given, the other should be set to zero.
1274 *
1275 * int npv
1276 * (Given) The number of entries in the wcsprm::pv[] array.
1277 *
1278 * int npvmax
1279 * (Given or returned) The length of the wcsprm::pv[] array.
1280 *
1281 * npvmax will be set by wcsinit() if it allocates memory for wcsprm::pv[],
1282 * otherwise it must be set by the user. See also wcsnpv().
1283 *
1284 * struct pvcard *pv
1285 * (Given) Address of the first element of an array of length npvmax of
1286 * pvcard structs.
1287 *
1288 * As a FITS header parser encounters each PVi_ma keyword it should load it
1289 * into a pvcard struct in the array and increment npv. wcsset()
1290 * interprets these as required.
1291 *
1292 * Note that, if they were not given, wcsset() resets the entries for
1293 * PVi_1a, PVi_2a, PVi_3a, and PVi_4a for longitude axis i to match
1294 * phi_0 and theta_0 (the native longitude and latitude of the reference
1295 * point), LONPOLEa and LATPOLEa respectively.
1296 *
1297 * int nps
1298 * (Given) The number of entries in the wcsprm::ps[] array.
1299 *
1300 * int npsmax
1301 * (Given or returned) The length of the wcsprm::ps[] array.
1302 *
1303 * npsmax will be set by wcsinit() if it allocates memory for wcsprm::ps[],
1304 * otherwise it must be set by the user. See also wcsnps().
1305 *
1306 * struct pscard *ps
1307 * (Given) Address of the first element of an array of length npsmax of
1308 * pscard structs.
1309 *
1310 * As a FITS header parser encounters each PSi_ma keyword it should load it
1311 * into a pscard struct in the array and increment nps. wcsset()
1312 * interprets these as required (currently no PSi_ma keyvalues are
1313 * recognized).
1314 *
1315 * double *cd
1316 * (Given) For historical compatibility, the wcsprm struct supports two
1317 * alternate specifications of the linear transformation matrix, those
1318 * associated with the CDi_ja keywords, and ...
1319 * double *crota
1320 * (Given) ... those associated with the CROTAi keywords. Although these
1321 * may not formally co-exist with PCi_ja, the approach taken here is simply
1322 * to ignore them if given in conjunction with PCi_ja.
1323 *
1324 * int altlin
1325 * (Given) altlin is a bit flag that denotes which of the PCi_ja, CDi_ja
1326 * and CROTAi keywords are present in the header:
1327 *
1328 * - Bit 0: PCi_ja is present.
1329 *
1330 * - Bit 1: CDi_ja is present.
1331 *
1332 * Matrix elements in the IRAF convention are equivalent to the product
1333 * CDi_ja = CDELTia * PCi_ja, but the defaults differ from that of the
1334 * PCi_ja matrix. If one or more CDi_ja keywords are present then all
1335 * unspecified CDi_ja default to zero. If no CDi_ja (or CROTAi) keywords
1336 * are present, then the header is assumed to be in PCi_ja form whether
1337 * or not any PCi_ja keywords are present since this results in an
1338 * interpretation of CDELTia consistent with the original FITS
1339 * specification.
1340 *
1341 * While CDi_ja may not formally co-exist with PCi_ja, it may co-exist
1342 * with CDELTia and CROTAi which are to be ignored.
1343 *
1344 * - Bit 2: CROTAi is present.
1345 *
1346 * In the AIPS convention, CROTAi may only be associated with the
1347 * latitude axis of a celestial axis pair. It specifies a rotation in
1348 * the image plane that is applied AFTER the CDELTia; any other CROTAi
1349 * keywords are ignored.
1350 *
1351 * CROTAi may not formally co-exist with PCi_ja.
1352 *
1353 * CROTAi and CDELTia may formally co-exist with CDi_ja but if so are to
1354 * be ignored.
1355 *
1356 * - Bit 3: PCi_ja + CDELTia was derived from CDi_ja by wcspcx().
1357 *
1358 * This bit is set by wcspcx() when it derives PCi_ja and CDELTia from
1359 * CDi_ja via an orthonormal decomposition. In particular, it signals
1360 * wcsset() not to replace PCi_ja by a copy of CDi_ja with CDELTia set
1361 * to unity.
1362 *
1363 * CDi_ja and CROTAi keywords, if found, are to be stored in the wcsprm::cd
1364 * and wcsprm::crota arrays which are dimensioned similarly to wcsprm::pc
1365 * and wcsprm::cdelt. FITS header parsers should use the following
1366 * procedure:
1367 *
1368 * - Whenever a PCi_ja keyword is encountered: altlin |= 1;
1369 *
1370 * - Whenever a CDi_ja keyword is encountered: altlin |= 2;
1371 *
1372 * - Whenever a CROTAi keyword is encountered: altlin |= 4;
1373 *
1374 * If none of these bits are set the PCi_ja representation results, i.e.
1375 * wcsprm::pc and wcsprm::cdelt will be used as given.
1376 *
1377 * These alternate specifications of the linear transformation matrix are
1378 * translated immediately to PCi_ja by wcsset() and are invisible to the
1379 * lower-level WCSLIB routines. In particular, unless bit 3 is also set,
1380 * wcsset() resets wcsprm::cdelt to unity if CDi_ja is present (and no
1381 * PCi_ja).
1382 *
1383 * If CROTAi are present but none is associated with the latitude axis
1384 * (and no PCi_ja or CDi_ja), then wcsset() reverts to a unity PCi_ja
1385 * matrix.
1386 *
1387 * int velref
1388 * (Given) AIPS velocity code VELREF, refer to spcaips().
1389 *
1390 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1391 * wcsprm::velref is changed.
1392 *
1393 * char alt[4]
1394 * (Given, auxiliary) Character code for alternate coordinate descriptions
1395 * (i.e. the 'a' in keyword names such as CTYPEia). This is blank for the
1396 * primary coordinate description, or one of the 26 upper-case letters,
1397 * A-Z.
1398 *
1399 * An array of four characters is provided for alignment purposes, only the
1400 * first is used.
1401 *
1402 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1403 * wcsprm::alt is changed.
1404 *
1405 * int colnum
1406 * (Given, auxiliary) Where the coordinate representation is associated
1407 * with an image-array column in a FITS binary table, this variable may be
1408 * used to record the relevant column number.
1409 *
1410 * It should be set to zero for an image header or pixel list.
1411 *
1412 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1413 * wcsprm::colnum is changed.
1414 *
1415 * int *colax
1416 * (Given, auxiliary) Address of the first element of an array of int
1417 * recording the column numbers for each axis in a pixel list.
1418 *
1419 * The array elements should be set to zero for an image header or image
1420 * array in a binary table.
1421 *
1422 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1423 * wcsprm::colax is changed.
1424 *
1425 * char (*cname)[72]
1426 * (Given, auxiliary) The address of the first element of an array of
1427 * char[72] containing the coordinate axis names, CNAMEia.
1428 *
1429 * These variables accomodate the longest allowed string-valued FITS
1430 * keyword, being limited to 68 characters, plus the null-terminating
1431 * character.
1432 *
1433 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1434 * wcsprm::cname is changed.
1435 *
1436 * double *crder
1437 * (Given, auxiliary) Address of the first element of an array of double
1438 * recording the random error in the coordinate value, CRDERia.
1439 *
1440 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1441 * wcsprm::crder is changed.
1442 *
1443 * double *csyer
1444 * (Given, auxiliary) Address of the first element of an array of double
1445 * recording the systematic error in the coordinate value, CSYERia.
1446 *
1447 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1448 * wcsprm::csyer is changed.
1449 *
1450 * double *czphs
1451 * (Given, auxiliary) Address of the first element of an array of double
1452 * recording the time at the zero point of a phase axis, CZPHSia.
1453 *
1454 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1455 * wcsprm::czphs is changed.
1456 *
1457 * double *cperi
1458 * (Given, auxiliary) Address of the first element of an array of double
1459 * recording the period of a phase axis, CPERIia.
1460 *
1461 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1462 * wcsprm::cperi is changed.
1463 *
1464 * char wcsname[72]
1465 * (Given, auxiliary) The name given to the coordinate representation,
1466 * WCSNAMEa. This variable accomodates the longest allowed string-valued
1467 * FITS keyword, being limited to 68 characters, plus the null-terminating
1468 * character.
1469 *
1470 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1471 * wcsprm::wcsname is changed.
1472 *
1473 * char timesys[72]
1474 * (Given, auxiliary) TIMESYS keyvalue, being the time scale (UTC, TAI,
1475 * etc.) in which all other time-related auxiliary header values are
1476 * recorded. Also defines the time scale for an image axis with CTYPEia
1477 * set to 'TIME'.
1478 *
1479 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1480 * wcsprm::timesys is changed.
1481 *
1482 * char trefpos[72]
1483 * (Given, auxiliary) TREFPOS keyvalue, being the location in space where
1484 * the recorded time is valid.
1485 *
1486 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1487 * wcsprm::trefpos is changed.
1488 *
1489 * char trefdir[72]
1490 * (Given, auxiliary) TREFDIR keyvalue, being the reference direction used
1491 * in calculating a pathlength delay.
1492 *
1493 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1494 * wcsprm::trefdir is changed.
1495 *
1496 * char plephem[72]
1497 * (Given, auxiliary) PLEPHEM keyvalue, being the Solar System ephemeris
1498 * used for calculating a pathlength delay.
1499 *
1500 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1501 * wcsprm::plephem is changed.
1502 *
1503 * char timeunit[72]
1504 * (Given, auxiliary) TIMEUNIT keyvalue, being the time units in which
1505 * the following header values are expressed: TSTART, TSTOP, TIMEOFFS,
1506 * TIMSYER, TIMRDER, TIMEDEL. It also provides the default value for
1507 * CUNITia for time axes.
1508 *
1509 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1510 * wcsprm::timeunit is changed.
1511 *
1512 * char dateref[72]
1513 * (Given, auxiliary) DATEREF keyvalue, being the date of a reference epoch
1514 * relative to which other time measurements refer.
1515 *
1516 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1517 * wcsprm::dateref is changed.
1518 *
1519 * double mjdref[2]
1520 * (Given, auxiliary) MJDREF keyvalue, equivalent to DATEREF expressed as
1521 * a Modified Julian Date (MJD = JD - 2400000.5). The value is given as
1522 * the sum of the two-element vector, allowing increased precision.
1523 *
1524 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1525 * wcsprm::mjdref is changed.
1526 *
1527 * double timeoffs
1528 * (Given, auxiliary) TIMEOFFS keyvalue, being a time offset, which may be
1529 * used, for example, to provide a uniform clock correction for times
1530 * referenced to DATEREF.
1531 *
1532 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1533 * wcsprm::timeoffs is changed.
1534 *
1535 * char dateobs[72]
1536 * (Given, auxiliary) DATE-OBS keyvalue, being the date at the start of the
1537 * observation unless otherwise explained in the DATE-OBS keycomment, in
1538 * ISO format, yyyy-mm-ddThh:mm:ss.
1539 *
1540 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1541 * wcsprm::dateobs is changed.
1542 *
1543 * char datebeg[72]
1544 * (Given, auxiliary) DATE-BEG keyvalue, being the date at the start of the
1545 * observation in ISO format, yyyy-mm-ddThh:mm:ss.
1546 *
1547 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1548 * wcsprm::datebeg is changed.
1549 *
1550 * char dateavg[72]
1551 * (Given, auxiliary) DATE-AVG keyvalue, being the date at a representative
1552 * mid-point of the observation in ISO format, yyyy-mm-ddThh:mm:ss.
1553 *
1554 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1555 * wcsprm::dateavg is changed.
1556 *
1557 * char dateend[72]
1558 * (Given, auxiliary) DATE-END keyvalue, baing the date at the end of the
1559 * observation in ISO format, yyyy-mm-ddThh:mm:ss.
1560 *
1561 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1562 * wcsprm::dateend is changed.
1563 *
1564 * double mjdobs
1565 * (Given, auxiliary) MJD-OBS keyvalue, equivalent to DATE-OBS expressed
1566 * as a Modified Julian Date (MJD = JD - 2400000.5).
1567 *
1568 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1569 * wcsprm::mjdobs is changed.
1570 *
1571 * double mjdbeg
1572 * (Given, auxiliary) MJD-BEG keyvalue, equivalent to DATE-BEG expressed
1573 * as a Modified Julian Date (MJD = JD - 2400000.5).
1574 *
1575 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1576 * wcsprm::mjdbeg is changed.
1577 *
1578 * double mjdavg
1579 * (Given, auxiliary) MJD-AVG keyvalue, equivalent to DATE-AVG expressed
1580 * as a Modified Julian Date (MJD = JD - 2400000.5).
1581 *
1582 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1583 * wcsprm::mjdavg is changed.
1584 *
1585 * double mjdend
1586 * (Given, auxiliary) MJD-END keyvalue, equivalent to DATE-END expressed
1587 * as a Modified Julian Date (MJD = JD - 2400000.5).
1588 *
1589 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1590 * wcsprm::mjdend is changed.
1591 *
1592 * double jepoch
1593 * (Given, auxiliary) JEPOCH keyvalue, equivalent to DATE-OBS expressed
1594 * as a Julian epoch.
1595 *
1596 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1597 * wcsprm::jepoch is changed.
1598 *
1599 * double bepoch
1600 * (Given, auxiliary) BEPOCH keyvalue, equivalent to DATE-OBS expressed
1601 * as a Besselian epoch
1602 *
1603 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1604 * wcsprm::bepoch is changed.
1605 *
1606 * double tstart
1607 * (Given, auxiliary) TSTART keyvalue, equivalent to DATE-BEG expressed
1608 * as a time in units of TIMEUNIT relative to DATEREF+TIMEOFFS.
1609 *
1610 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1611 * wcsprm::tstart is changed.
1612 *
1613 * double tstop
1614 * (Given, auxiliary) TSTOP keyvalue, equivalent to DATE-END expressed
1615 * as a time in units of TIMEUNIT relative to DATEREF+TIMEOFFS.
1616 *
1617 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1618 * wcsprm::tstop is changed.
1619 *
1620 * double xposure
1621 * (Given, auxiliary) XPOSURE keyvalue, being the effective exposure time
1622 * in units of TIMEUNIT.
1623 *
1624 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1625 * wcsprm::xposure is changed.
1626 *
1627 * double telapse
1628 * (Given, auxiliary) TELAPSE keyvalue, equivalent to the elapsed time
1629 * between DATE-BEG and DATE-END, in units of TIMEUNIT.
1630 *
1631 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1632 * wcsprm::telapse is changed.
1633 *
1634 * double timsyer
1635 * (Given, auxiliary) TIMSYER keyvalue, being the absolute error of the
1636 * time values, in units of TIMEUNIT.
1637 *
1638 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1639 * wcsprm::timsyer is changed.
1640 *
1641 * double timrder
1642 * (Given, auxiliary) TIMRDER keyvalue, being the accuracy of time stamps
1643 * relative to each other, in units of TIMEUNIT.
1644 *
1645 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1646 * wcsprm::timrder is changed.
1647 *
1648 * double timedel
1649 * (Given, auxiliary) TIMEDEL keyvalue, being the resolution of the time
1650 * stamps.
1651 *
1652 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1653 * wcsprm::timedel is changed.
1654 *
1655 * double timepixr
1656 * (Given, auxiliary) TIMEPIXR keyvalue, being the relative position of the
1657 * time stamps in binned time intervals, a value between 0.0 and 1.0.
1658 *
1659 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1660 * wcsprm::timepixr is changed.
1661 *
1662 * double obsgeo[6]
1663 * (Given, auxiliary) Location of the observer in a standard terrestrial
1664 * reference frame. The first three give ITRS Cartesian coordinates
1665 * OBSGEO-X [m], OBSGEO-Y [m], OBSGEO-Z [m], and the second three give
1666 * OBSGEO-L [deg], OBSGEO-B [deg], OBSGEO-H [m], which are related through
1667 * a standard transformation.
1668 *
1669 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1670 * wcsprm::obsgeo is changed.
1671 *
1672 * char obsorbit[72]
1673 * (Given, auxiliary) OBSORBIT keyvalue, being the URI, URL, or name of an
1674 * orbit ephemeris file giving spacecraft coordinates relating to TREFPOS.
1675 *
1676 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1677 * wcsprm::obsorbit is changed.
1678 *
1679 * char radesys[72]
1680 * (Given, auxiliary) The equatorial or ecliptic coordinate system type,
1681 * RADESYSa.
1682 *
1683 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1684 * wcsprm::radesys is changed.
1685 *
1686 * double equinox
1687 * (Given, auxiliary) The equinox associated with dynamical equatorial or
1688 * ecliptic coordinate systems, EQUINOXa (or EPOCH in older headers). Not
1689 * applicable to ICRS equatorial or ecliptic coordinates.
1690 *
1691 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1692 * wcsprm::equinox is changed.
1693 *
1694 * char specsys[72]
1695 * (Given, auxiliary) Spectral reference frame (standard of rest),
1696 * SPECSYSa.
1697 *
1698 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1699 * wcsprm::specsys is changed.
1700 *
1701 * char ssysobs[72]
1702 * (Given, auxiliary) The spectral reference frame in which there is no
1703 * differential variation in the spectral coordinate across the
1704 * field-of-view, SSYSOBSa.
1705 *
1706 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1707 * wcsprm::ssysobs is changed.
1708 *
1709 * double velosys
1710 * (Given, auxiliary) The relative radial velocity [m/s] between the
1711 * observer and the selected standard of rest in the direction of the
1712 * celestial reference coordinate, VELOSYSa.
1713 *
1714 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1715 * wcsprm::velosys is changed.
1716 *
1717 * double zsource
1718 * (Given, auxiliary) The redshift, ZSOURCEa, of the source.
1719 *
1720 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1721 * wcsprm::zsource is changed.
1722 *
1723 * char ssyssrc[72]
1724 * (Given, auxiliary) The spectral reference frame (standard of rest),
1725 * SSYSSRCa, in which wcsprm::zsource was measured.
1726 *
1727 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1728 * wcsprm::ssyssrc is changed.
1729 *
1730 * double velangl
1731 * (Given, auxiliary) The angle [deg] that should be used to decompose an
1732 * observed velocity into radial and transverse components.
1733 *
1734 * It is not necessary to reset the wcsprm struct (via wcsset()) when
1735 * wcsprm::velangl is changed.
1736 *
1737 * struct auxprm *aux
1738 * (Given, auxiliary) This struct holds auxiliary coordinate system
1739 * information of a specialist nature. While these parameters may be
1740 * widely recognized within particular fields of astronomy, they differ
1741 * from the above auxiliary parameters in not being defined by any of the
1742 * FITS WCS standards. Collecting them together in a separate struct that
1743 * is allocated only when required helps to control bloat in the size of
1744 * the wcsprm struct.
1745 *
1746 * int ntab
1747 * (Given) See wcsprm::tab.
1748 *
1749 * int nwtb
1750 * (Given) See wcsprm::wtb.
1751 *
1752 * struct tabprm *tab
1753 * (Given) Address of the first element of an array of ntab tabprm structs
1754 * for which memory has been allocated. These are used to store tabular
1755 * transformation parameters.
1756 *
1757 * Although technically wcsprm::ntab and tab are "given", they will
1758 * normally be set by invoking wcstab(), whether directly or indirectly.
1759 *
1760 * The tabprm structs contain some members that must be supplied and others
1761 * that are derived. The information to be supplied comes primarily from
1762 * arrays stored in one or more FITS binary table extensions. These
1763 * arrays, referred to here as "wcstab arrays", are themselves located by
1764 * parameters stored in the FITS image header.
1765 *
1766 * struct wtbarr *wtb
1767 * (Given) Address of the first element of an array of nwtb wtbarr structs
1768 * for which memory has been allocated. These are used in extracting
1769 * wcstab arrays from a FITS binary table.
1770 *
1771 * Although technically wcsprm::nwtb and wtb are "given", they will
1772 * normally be set by invoking wcstab(), whether directly or indirectly.
1773 *
1774 * char lngtyp[8]
1775 * (Returned) Four-character WCS celestial longitude and ...
1776 * char lattyp[8]
1777 * (Returned) ... latitude axis types. e.g. "RA", "DEC", "GLON", "GLAT",
1778 * etc. extracted from 'RA--', 'DEC-', 'GLON', 'GLAT', etc. in the first
1779 * four characters of CTYPEia but with trailing dashes removed. (Declared
1780 * as char[8] for alignment reasons.)
1781 *
1782 * int lng
1783 * (Returned) Index for the longitude coordinate, and ...
1784 * int lat
1785 * (Returned) ... index for the latitude coordinate, and ...
1786 * int spec
1787 * (Returned) ... index for the spectral coordinate in the imgcrd[][] and
1788 * world[][] arrays in the API of wcsp2s(), wcss2p() and wcsmix().
1789 *
1790 * These may also serve as indices into the pixcrd[][] array provided that
1791 * the PCi_ja matrix does not transpose axes.
1792 *
1793 * int cubeface
1794 * (Returned) Index into the pixcrd[][] array for the CUBEFACE axis. This
1795 * is used for quadcube projections where the cube faces are stored on a
1796 * separate axis (see wcs.h).
1797 *
1798 * int *types
1799 * (Returned) Address of the first element of an array of int containing a
1800 * four-digit type code for each axis.
1801 *
1802 * - First digit (i.e. 1000s):
1803 * - 0: Non-specific coordinate type.
1804 * - 1: Stokes coordinate.
1805 * - 2: Celestial coordinate (including CUBEFACE).
1806 * - 3: Spectral coordinate.
1807 * - 4: Time coordinate.
1808 *
1809 * - Second digit (i.e. 100s):
1810 * - 0: Linear axis.
1811 * - 1: Quantized axis (STOKES, CUBEFACE).
1812 * - 2: Non-linear celestial axis.
1813 * - 3: Non-linear spectral axis.
1814 * - 4: Logarithmic axis.
1815 * - 5: Tabular axis.
1816 *
1817 * - Third digit (i.e. 10s):
1818 * - 0: Group number, e.g. lookup table number, being an index into the
1819 * tabprm array (see above).
1820 *
1821 * - The fourth digit is used as a qualifier depending on the axis type.
1822 *
1823 * - For celestial axes:
1824 * - 0: Longitude coordinate.
1825 * - 1: Latitude coordinate.
1826 * - 2: CUBEFACE number.
1827 *
1828 * - For lookup tables: the axis number in a multidimensional table.
1829 *
1830 * CTYPEia in "4-3" form with unrecognized algorithm code will have its
1831 * type set to -1 and generate an error.
1832 *
1833 * struct linprm lin
1834 * (Returned) Linear transformation parameters (usage is described in the
1835 * prologue to lin.h).
1836 *
1837 * struct celprm cel
1838 * (Returned) Celestial transformation parameters (usage is described in
1839 * the prologue to cel.h).
1840 *
1841 * struct spcprm spc
1842 * (Returned) Spectral transformation parameters (usage is described in the
1843 * prologue to spc.h).
1844 *
1845 * struct wcserr *err
1846 * (Returned) If enabled, when an error status is returned, this struct
1847 * contains detailed information about the error, see wcserr_enable().
1848 *
1849 * int m_flag
1850 * (For internal use only.)
1851 * int m_naxis
1852 * (For internal use only.)
1853 * double *m_crpix
1854 * (For internal use only.)
1855 * double *m_pc
1856 * (For internal use only.)
1857 * double *m_cdelt
1858 * (For internal use only.)
1859 * double *m_crval
1860 * (For internal use only.)
1861 * char (*m_cunit)[72]
1862 * (For internal use only.)
1863 * char (*m_ctype)[72]
1864 * (For internal use only.)
1865 * struct pvcard *m_pv
1866 * (For internal use only.)
1867 * struct pscard *m_ps
1868 * (For internal use only.)
1869 * double *m_cd
1870 * (For internal use only.)
1871 * double *m_crota
1872 * (For internal use only.)
1873 * int *m_colax
1874 * (For internal use only.)
1875 * char (*m_cname)[72]
1876 * (For internal use only.)
1877 * double *m_crder
1878 * (For internal use only.)
1879 * double *m_csyer
1880 * (For internal use only.)
1881 * double *m_czphs
1882 * (For internal use only.)
1883 * double *m_cperi
1884 * (For internal use only.)
1885 * struct tabprm *m_tab
1886 * (For internal use only.)
1887 * struct wtbarr *m_wtb
1888 * (For internal use only.)
1889 *
1890 *
1891 * pvcard struct - Store for PVi_ma keyrecords
1892 * -------------------------------------------
1893 * The pvcard struct is used to pass the parsed contents of PVi_ma keyrecords
1894 * to wcsset() via the wcsprm struct.
1895 *
1896 * All members of this struct are to be set by the user.
1897 *
1898 * int i
1899 * (Given) Axis number (1-relative), as in the FITS PVi_ma keyword. If
1900 * i == 0, wcsset() will replace it with the latitude axis number.
1901 *
1902 * int m
1903 * (Given) Parameter number (non-negative), as in the FITS PVi_ma keyword.
1904 *
1905 * double value
1906 * (Given) Parameter value.
1907 *
1908 *
1909 * pscard struct - Store for PSi_ma keyrecords
1910 * -------------------------------------------
1911 * The pscard struct is used to pass the parsed contents of PSi_ma keyrecords
1912 * to wcsset() via the wcsprm struct.
1913 *
1914 * All members of this struct are to be set by the user.
1915 *
1916 * int i
1917 * (Given) Axis number (1-relative), as in the FITS PSi_ma keyword.
1918 *
1919 * int m
1920 * (Given) Parameter number (non-negative), as in the FITS PSi_ma keyword.
1921 *
1922 * char value[72]
1923 * (Given) Parameter value.
1924 *
1925 *
1926 * auxprm struct - Additional auxiliary parameters
1927 * -----------------------------------------------
1928 * The auxprm struct holds auxiliary coordinate system information of a
1929 * specialist nature. It is anticipated that this struct will expand in future
1930 * to accomodate additional parameters.
1931 *
1932 * All members of this struct are to be set by the user.
1933 *
1934 * double rsun_ref
1935 * (Given, auxiliary) Reference radius of the Sun used in coordinate
1936 * calculations (m).
1937 *
1938 * double dsun_obs
1939 * (Given, auxiliary) Distance between the centre of the Sun and the
1940 * observer (m).
1941 *
1942 * double crln_obs
1943 * (Given, auxiliary) Carrington heliographic longitude of the observer
1944 * (deg).
1945 *
1946 * double hgln_obs
1947 * (Given, auxiliary) Stonyhurst heliographic longitude of the observer
1948 * (deg).
1949 *
1950 * double hglt_obs
1951 * (Given, auxiliary) Heliographic latitude (Carrington or Stonyhurst) of
1952 * the observer (deg).
1953 *
1954 *
1955 * Global variable: const char *wcs_errmsg[] - Status return messages
1956 * ------------------------------------------------------------------
1957 * Error messages to match the status value returned from each function.
1958 *
1959 *===========================================================================*/
1960 
1961 #ifndef WCSLIB_WCS
1962 #define WCSLIB_WCS
1963 
1964 #include "lin.h"
1965 #include "cel.h"
1966 #include "spc.h"
1967 
1968 #ifdef __cplusplus
1969 extern "C" {
1970 #define wtbarr wtbarr_s // See prologue of wtbarr.h.
1971 #endif
1972 
1973 #define WCSSUB_LONGITUDE 0x1001
1974 #define WCSSUB_LATITUDE 0x1002
1975 #define WCSSUB_CUBEFACE 0x1004
1976 #define WCSSUB_CELESTIAL 0x1007
1977 #define WCSSUB_SPECTRAL 0x1008
1978 #define WCSSUB_STOKES 0x1010
1979 #define WCSSUB_TIME 0x1020
1980 
1981 
1982 #define WCSCOMPARE_ANCILLARY 0x0001
1983 #define WCSCOMPARE_TILING 0x0002
1984 #define WCSCOMPARE_CRPIX 0x0004
1985 
1986 
1987 extern const char *wcs_errmsg[];
1988 
1990  WCSERR_SUCCESS = 0, // Success.
1991  WCSERR_NULL_POINTER = 1, // Null wcsprm pointer passed.
1992  WCSERR_MEMORY = 2, // Memory allocation failed.
1993  WCSERR_SINGULAR_MTX = 3, // Linear transformation matrix is singular.
1994  WCSERR_BAD_CTYPE = 4, // Inconsistent or unrecognized coordinate
1995  // axis type.
1996  WCSERR_BAD_PARAM = 5, // Invalid parameter value.
1997  WCSERR_BAD_COORD_TRANS = 6, // Unrecognized coordinate transformation
1998  // parameter.
1999  WCSERR_ILL_COORD_TRANS = 7, // Ill-conditioned coordinate transformation
2000  // parameter.
2001  WCSERR_BAD_PIX = 8, // One or more of the pixel coordinates were
2002  // invalid.
2003  WCSERR_BAD_WORLD = 9, // One or more of the world coordinates were
2004  // invalid.
2005  WCSERR_BAD_WORLD_COORD = 10, // Invalid world coordinate.
2006  WCSERR_NO_SOLUTION = 11, // No solution found in the specified
2007  // interval.
2008  WCSERR_BAD_SUBIMAGE = 12, // Invalid subimage specification.
2009  WCSERR_NON_SEPARABLE = 13, // Non-separable subimage coordinate system.
2010  WCSERR_UNSET = 14 // wcsprm struct is unset.
2011 };
2012 
2013 
2014 // Struct used for storing PVi_ma keywords.
2015 struct pvcard {
2016  int i; // Axis number, as in PVi_ma (1-relative).
2017  int m; // Parameter number, ditto (0-relative).
2018  double value; // Parameter value.
2019 };
2020 
2021 // Size of the pvcard struct in int units, used by the Fortran wrappers.
2022 #define PVLEN (sizeof(struct pvcard)/sizeof(int))
2023 
2024 // Struct used for storing PSi_ma keywords.
2025 struct pscard {
2026  int i; // Axis number, as in PSi_ma (1-relative).
2027  int m; // Parameter number, ditto (0-relative).
2028  char value[72]; // Parameter value.
2029 };
2030 
2031 // Size of the pscard struct in int units, used by the Fortran wrappers.
2032 #define PSLEN (sizeof(struct pscard)/sizeof(int))
2033 
2034 // Struct used to hold additional auxiliary parameters.
2035 struct auxprm {
2036  double rsun_ref; // Solar radius.
2037  double dsun_obs; // Distance from Sun centre to observer.
2038  double crln_obs; // Carrington heliographic lng of observer.
2039  double hgln_obs; // Stonyhurst heliographic lng of observer.
2040  double hglt_obs; // Heliographic latitude of observer.
2041 };
2042 
2043 // Size of the auxprm struct in int units, used by the Fortran wrappers.
2044 #define AUXLEN (sizeof(struct auxprm)/sizeof(int))
2045 
2046 
2047 struct wcsprm {
2048  // Initialization flag (see the prologue above).
2049  //--------------------------------------------------------------------------
2050  int flag; // Set to zero to force initialization.
2051 
2052  // FITS header keyvalues to be provided (see the prologue above).
2053  //--------------------------------------------------------------------------
2054  int naxis; // Number of axes (pixel and coordinate).
2055  double *crpix; // CRPIXja keyvalues for each pixel axis.
2056  double *pc; // PCi_ja linear transformation matrix.
2057  double *cdelt; // CDELTia keyvalues for each coord axis.
2058  double *crval; // CRVALia keyvalues for each coord axis.
2059 
2060  char (*cunit)[72]; // CUNITia keyvalues for each coord axis.
2061  char (*ctype)[72]; // CTYPEia keyvalues for each coord axis.
2062 
2063  double lonpole; // LONPOLEa keyvalue.
2064  double latpole; // LATPOLEa keyvalue.
2065 
2066  double restfrq; // RESTFRQa keyvalue.
2067  double restwav; // RESTWAVa keyvalue.
2068 
2069  int npv; // Number of PVi_ma keywords, and the
2070  int npvmax; // number for which space was allocated.
2071  struct pvcard *pv; // PVi_ma keywords for each i and m.
2072 
2073  int nps; // Number of PSi_ma keywords, and the
2074  int npsmax; // number for which space was allocated.
2075  struct pscard *ps; // PSi_ma keywords for each i and m.
2076 
2077  // Alternative header keyvalues (see the prologue above).
2078  //--------------------------------------------------------------------------
2079  double *cd; // CDi_ja linear transformation matrix.
2080  double *crota; // CROTAi keyvalues for each coord axis.
2081  int altlin; // Alternative representations
2082  // Bit 0: PCi_ja is present,
2083  // Bit 1: CDi_ja is present,
2084  // Bit 2: CROTAi is present.
2085  int velref; // AIPS velocity code, VELREF.
2086 
2087  // Auxiliary coordinate system information of a general nature. Not
2088  // used by WCSLIB. Refer to the prologue comments above for a brief
2089  // explanation of these values.
2090  char alt[4];
2091  int colnum;
2092  int *colax;
2093  // Auxiliary coordinate axis information.
2094  char (*cname)[72];
2095  double *crder;
2096  double *csyer;
2097  double *czphs;
2098  double *cperi;
2099 
2100  char wcsname[72];
2101  // Time reference system and measurement.
2102  char timesys[72], trefpos[72], trefdir[72], plephem[72];
2103  char timeunit[72];
2104  char dateref[72];
2105  double mjdref[2];
2106  double timeoffs;
2107  // Data timestamps and durations.
2108  char dateobs[72], datebeg[72], dateavg[72], dateend[72];
2110  double jepoch, bepoch;
2111  double tstart, tstop;
2112  double xposure, telapse;
2113  // Timing accuracy.
2114  double timsyer, timrder;
2116  // Spatial & celestial reference frame.
2117  double obsgeo[6];
2118  char obsorbit[72];
2119  char radesys[72];
2120  double equinox;
2121  char specsys[72];
2122  char ssysobs[72];
2123  double velosys;
2124  double zsource;
2125  char ssyssrc[72];
2126  double velangl;
2127 
2128  // Additional auxiliary coordinate system information of a specialist
2129  // nature. Not used by WCSLIB. Refer to the prologue comments above.
2130  struct auxprm *aux;
2131 
2132  // Coordinate lookup tables (see the prologue above).
2133  //--------------------------------------------------------------------------
2134  int ntab; // Number of separate tables.
2135  int nwtb; // Number of wtbarr structs.
2136  struct tabprm *tab; // Tabular transformation parameters.
2137  struct wtbarr *wtb; // Array of wtbarr structs.
2138 
2139  //--------------------------------------------------------------------------
2140  // Information derived from the FITS header keyvalues by wcsset().
2141  //--------------------------------------------------------------------------
2142  char lngtyp[8], lattyp[8]; // Celestial axis types, e.g. RA, DEC.
2143  int lng, lat, spec; // Longitude, latitude and spectral axis
2144  // indices (0-relative).
2145  int cubeface; // True if there is a CUBEFACE axis.
2146  int *types; // Coordinate type codes for each axis.
2147 
2148  struct linprm lin; // Linear transformation parameters.
2149  struct celprm cel; // Celestial transformation parameters.
2150  struct spcprm spc; // Spectral transformation parameters.
2151 
2152  //--------------------------------------------------------------------------
2153  // THE REMAINDER OF THE WCSPRM STRUCT IS PRIVATE.
2154  //--------------------------------------------------------------------------
2155 
2156  // Error handling, if enabled.
2157  //--------------------------------------------------------------------------
2158  struct wcserr *err;
2159 
2160  // Memory management.
2161  //--------------------------------------------------------------------------
2163  double *m_crpix, *m_pc, *m_cdelt, *m_crval;
2164  char (*m_cunit)[72], (*m_ctype)[72];
2165  struct pvcard *m_pv;
2166  struct pscard *m_ps;
2167  double *m_cd, *m_crota;
2168  int *m_colax;
2169  char (*m_cname)[72];
2171  struct auxprm *m_aux;
2172  struct tabprm *m_tab;
2173  struct wtbarr *m_wtb;
2174 };
2175 
2176 // Size of the wcsprm struct in int units, used by the Fortran wrappers.
2177 #define WCSLEN (sizeof(struct wcsprm)/sizeof(int))
2178 
2179 
2180 int wcsnpv(int n);
2181 
2182 int wcsnps(int n);
2183 
2184 int wcsini(int alloc, int naxis, struct wcsprm *wcs);
2185 
2186 int wcsinit(int alloc, int naxis, struct wcsprm *wcs, int npvmax, int npsmax,
2187  int ndpmax);
2188 
2189 int wcsauxi(int alloc, struct wcsprm *wcs);
2190 
2191 int wcssub(int alloc, const struct wcsprm *wcssrc, int *nsub, int axes[],
2192  struct wcsprm *wcsdst);
2193 
2194 int wcscompare(int cmp, double tol, const struct wcsprm *wcs1,
2195  const struct wcsprm *wcs2, int *equal);
2196 
2197 int wcsfree(struct wcsprm *wcs);
2198 
2199 int wcstrim(struct wcsprm *wcs);
2200 
2201 int wcssize(const struct wcsprm *wcs, int sizes[2]);
2202 
2203 int auxsize(const struct auxprm *aux, int sizes[2]);
2204 
2205 int wcsprt(const struct wcsprm *wcs);
2206 
2207 int wcsperr(const struct wcsprm *wcs, const char *prefix);
2208 
2209 int wcsbchk(struct wcsprm *wcs, int bounds);
2210 
2211 int wcsset(struct wcsprm *wcs);
2212 
2213 int wcsp2s(struct wcsprm *wcs, int ncoord, int nelem, const double pixcrd[],
2214  double imgcrd[], double phi[], double theta[], double world[],
2215  int stat[]);
2216 
2217 int wcss2p(struct wcsprm *wcs, int ncoord, int nelem, const double world[],
2218  double phi[], double theta[], double imgcrd[], double pixcrd[],
2219  int stat[]);
2220 
2221 int wcsmix(struct wcsprm *wcs, int mixpix, int mixcel, const double vspan[2],
2222  double vstep, int viter, double world[], double phi[],
2223  double theta[], double imgcrd[], double pixcrd[]);
2224 
2225 int wcsccs(struct wcsprm *wcs, double lng2p1, double lat2p1, double lng1p2,
2226  const char *clng, const char *clat, const char *radesys,
2227  double equinox, const char *alt);
2228 
2229 int wcssptr(struct wcsprm *wcs, int *i, char ctype[9]);
2230 
2231 const char* wcslib_version(int vers[3]);
2232 
2233 // Defined mainly for backwards compatibility, use wcssub() instead.
2234 #define wcscopy(alloc, wcssrc, wcsdst) wcssub(alloc, wcssrc, 0x0, 0x0, wcsdst)
2235 
2236 
2237 // Deprecated.
2238 #define wcsini_errmsg wcs_errmsg
2239 #define wcssub_errmsg wcs_errmsg
2240 #define wcscopy_errmsg wcs_errmsg
2241 #define wcsfree_errmsg wcs_errmsg
2242 #define wcsprt_errmsg wcs_errmsg
2243 #define wcsset_errmsg wcs_errmsg
2244 #define wcsp2s_errmsg wcs_errmsg
2245 #define wcss2p_errmsg wcs_errmsg
2246 #define wcsmix_errmsg wcs_errmsg
2247 
2248 #ifdef __cplusplus
2249 #undef wtbarr
2250 }
2251 #endif
2252 
2253 #endif // WCSLIB_WCS
Additional auxiliary parameters.
Definition: wcs.h:2035
double dsun_obs
Definition: wcs.h:2037
double hglt_obs
Definition: wcs.h:2040
double hgln_obs
Definition: wcs.h:2039
double crln_obs
Definition: wcs.h:2038
double rsun_ref
Definition: wcs.h:2036
Celestial transformation parameters.
Definition: cel.h:423
Linear transformation parameters.
Definition: lin.h:680
Store for PSi_ma keyrecords.
Definition: wcs.h:2025
int i
Definition: wcs.h:2026
int m
Definition: wcs.h:2027
char value[72]
Definition: wcs.h:2028
Store for PVi_ma keyrecords.
Definition: wcs.h:2015
double value
Definition: wcs.h:2018
int i
Definition: wcs.h:2016
int m
Definition: wcs.h:2017
Spectral transformation parameters.
Definition: spc.h:832
Tabular transformation parameters.
Definition: tab.h:573
Error message handling.
Definition: wcserr.h:243
Coordinate transformation parameters.
Definition: wcs.h:2047
char timeunit[72]
Definition: wcs.h:2103
struct pscard * m_ps
Definition: wcs.h:2166
char timesys[72]
Definition: wcs.h:2102
struct pvcard * pv
Definition: wcs.h:2071
char dateref[72]
Definition: wcs.h:2104
double mjdavg
Definition: wcs.h:2109
int lng
Definition: wcs.h:2143
double * czphs
Definition: wcs.h:2097
char(* m_cname)[72]
Definition: wcs.h:2169
double zsource
Definition: wcs.h:2124
double * m_crder
Definition: wcs.h:2170
int npv
Definition: wcs.h:2069
double timrder
Definition: wcs.h:2114
char trefpos[72]
Definition: wcs.h:2102
double telapse
Definition: wcs.h:2112
double * m_csyer
Definition: wcs.h:2170
double tstart
Definition: wcs.h:2111
double * csyer
Definition: wcs.h:2096
double * m_crpix
Definition: wcs.h:2163
double * cperi
Definition: wcs.h:2098
double mjdend
Definition: wcs.h:2109
char wcsname[72]
Definition: wcs.h:2100
struct tabprm * tab
Definition: wcs.h:2136
struct linprm lin
Definition: wcs.h:2148
double * pc
Definition: wcs.h:2056
int flag
Definition: wcs.h:2050
struct auxprm * aux
Definition: wcs.h:2130
int npsmax
Definition: wcs.h:2074
double * m_cdelt
Definition: wcs.h:2163
double timeoffs
Definition: wcs.h:2106
double * crder
Definition: wcs.h:2095
int nps
Definition: wcs.h:2073
int * m_colax
Definition: wcs.h:2168
double * m_crval
Definition: wcs.h:2163
double timepixr
Definition: wcs.h:2115
double * m_crota
Definition: wcs.h:2167
double * m_cperi
Definition: wcs.h:2170
int m_flag
Definition: wcs.h:2162
char lngtyp[8]
Definition: wcs.h:2142
double restwav
Definition: wcs.h:2067
double latpole
Definition: wcs.h:2064
int m_naxis
Definition: wcs.h:2162
char radesys[72]
Definition: wcs.h:2119
double * m_pc
Definition: wcs.h:2163
struct pvcard * m_pv
Definition: wcs.h:2165
int naxis
Definition: wcs.h:2054
double * m_czphs
Definition: wcs.h:2170
int * colax
Definition: wcs.h:2092
double * crval
Definition: wcs.h:2058
double * m_cd
Definition: wcs.h:2167
double tstop
Definition: wcs.h:2111
double obsgeo[6]
Definition: wcs.h:2117
double timsyer
Definition: wcs.h:2114
int nwtb
Definition: wcs.h:2135
char ssyssrc[72]
Definition: wcs.h:2125
double equinox
Definition: wcs.h:2120
int altlin
Definition: wcs.h:2081
struct wtbarr * wtb
Definition: wcs.h:2137
int npvmax
Definition: wcs.h:2070
char(* cname)[72]
Definition: wcs.h:2094
double jepoch
Definition: wcs.h:2110
int ntab
Definition: wcs.h:2134
char ssysobs[72]
Definition: wcs.h:2122
struct pscard * ps
Definition: wcs.h:2075
int colnum
Definition: wcs.h:2091
char datebeg[72]
Definition: wcs.h:2108
double velangl
Definition: wcs.h:2126
double mjdbeg
Definition: wcs.h:2109
char(* cunit)[72]
Definition: wcs.h:2060
double bepoch
Definition: wcs.h:2110
double mjdref[2]
Definition: wcs.h:2105
char trefdir[72]
Definition: wcs.h:2102
char plephem[72]
Definition: wcs.h:2102
char dateobs[72]
Definition: wcs.h:2108
double * crpix
Definition: wcs.h:2055
int * types
Definition: wcs.h:2146
int lat
Definition: wcs.h:2143
int spec
Definition: wcs.h:2143
char specsys[72]
Definition: wcs.h:2121
double mjdobs
Definition: wcs.h:2109
double xposure
Definition: wcs.h:2112
int velref
Definition: wcs.h:2085
struct celprm cel
Definition: wcs.h:2149
struct wtbarr * m_wtb
Definition: wcs.h:2173
char dateend[72]
Definition: wcs.h:2108
struct auxprm * m_aux
Definition: wcs.h:2171
double restfrq
Definition: wcs.h:2066
double * cdelt
Definition: wcs.h:2057
int cubeface
Definition: wcs.h:2145
struct tabprm * m_tab
Definition: wcs.h:2172
char obsorbit[72]
Definition: wcs.h:2118
char(* ctype)[72]
Definition: wcs.h:2061
char lattyp[8]
Definition: wcs.h:2142
char dateavg[72]
Definition: wcs.h:2108
char alt[4]
Definition: wcs.h:2090
struct spcprm spc
Definition: wcs.h:2150
double timedel
Definition: wcs.h:2115
double * crota
Definition: wcs.h:2080
char(* m_cunit)[72]
Definition: wcs.h:2164
double velosys
Definition: wcs.h:2123
struct wcserr * err
Definition: wcs.h:2158
double lonpole
Definition: wcs.h:2063
double * cd
Definition: wcs.h:2079
Extraction of coordinate lookup tables from BINTABLE.
Definition: getwcstab.h:167
int i
Definition: getwcstab.h:168
wcs_errmsg_enum
Definition: wcs.h:1989
@ WCSERR_BAD_WORLD
Definition: wcs.h:2003
@ WCSERR_BAD_PIX
Definition: wcs.h:2001
@ WCSERR_SINGULAR_MTX
Definition: wcs.h:1993
@ WCSERR_NON_SEPARABLE
Definition: wcs.h:2009
@ WCSERR_BAD_CTYPE
Definition: wcs.h:1994
@ WCSERR_MEMORY
Definition: wcs.h:1992
@ WCSERR_BAD_WORLD_COORD
Definition: wcs.h:2005
@ WCSERR_BAD_COORD_TRANS
Definition: wcs.h:1997
@ WCSERR_NO_SOLUTION
Definition: wcs.h:2006
@ WCSERR_BAD_SUBIMAGE
Definition: wcs.h:2008
@ WCSERR_SUCCESS
Definition: wcs.h:1990
@ WCSERR_UNSET
Definition: wcs.h:2010
@ WCSERR_NULL_POINTER
Definition: wcs.h:1991
@ WCSERR_ILL_COORD_TRANS
Definition: wcs.h:1999
@ WCSERR_BAD_PARAM
Definition: wcs.h:1996
int wcsmix(struct wcsprm *wcs, int mixpix, int mixcel, const double vspan[2], double vstep, int viter, double world[], double phi[], double theta[], double imgcrd[], double pixcrd[])
Hybrid coordinate transformation.
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.
int wcsini(int alloc, int naxis, struct wcsprm *wcs)
Default constructor for the wcsprm struct.
const char * wcslib_version(int vers[3])
int wcssize(const struct wcsprm *wcs, int sizes[2])
Compute the size of a wcsprm struct.
int wcsnpv(int n)
Memory allocation for PVi_ma.
int wcsfree(struct wcsprm *wcs)
Destructor for the wcsprm struct.
int auxsize(const struct auxprm *aux, int sizes[2])
Compute the size of a auxprm struct.
int wcssptr(struct wcsprm *wcs, int *i, char ctype[9])
Spectral axis translation.
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 wcscompare(int cmp, double tol, const struct wcsprm *wcs1, const struct wcsprm *wcs2, int *equal)
Compare two wcsprm structs for equality.
int wcsccs(struct wcsprm *wcs, double lng2p1, double lat2p1, double lng1p2, const char *clng, const char *clat, const char *radesys, double equinox, const char *alt)
Change celestial coordinate system.
int wcssub(int alloc, const struct wcsprm *wcssrc, int *nsub, int axes[], struct wcsprm *wcsdst)
Subimage extraction routine for the wcsprm struct.
int wcsperr(const struct wcsprm *wcs, const char *prefix)
Print error messages from a wcsprm struct.
int wcsauxi(int alloc, struct wcsprm *wcs)
Default constructor for the auxprm struct.
int wcsinit(int alloc, int naxis, struct wcsprm *wcs, int npvmax, int npsmax, int ndpmax)
Default constructor for the wcsprm struct.
int wcstrim(struct wcsprm *wcs)
Free unused arrays in the wcsprm struct.
int wcsprt(const struct wcsprm *wcs)
Print routine for the wcsprm struct.
const char * wcs_errmsg[]
Status return messages.
int wcsset(struct wcsprm *wcs)
Setup routine for the wcsprm struct.
int wcsnps(int n)
Memory allocation for PSi_ma.
int wcsbchk(struct wcsprm *wcs, int bounds)
Enable/disable bounds checking.