WCSLIB: wcs.h Source File

WCSLIB 7.4

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