WCSLIB: wcs.h Source File

WCSLIB 6.2

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