WCSLIB 5.17

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