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