wcslib (8.2.2)
1 /*============================================================================
2 WCSLIB 8.2 - an implementation of the FITS WCS standard.
3 Copyright (C) 1995-2023, Mark Calabretta
4
5 This file is part of WCSLIB.
6
7 WCSLIB is free software: you can redistribute it and/or modify it under the
8 terms of the GNU Lesser General Public License as published by the Free
9 Software Foundation, either version 3 of the License, or (at your option)
10 any later version.
11
12 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
13 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
14 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
15 more details.
16
17 You should have received a copy of the GNU Lesser General Public License
18 along with WCSLIB. If not, see http://www.gnu.org/licenses.
19
20 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
21 http://www.atnf.csiro.au/people/Mark.Calabretta
22 $Id: wcshdr.h,v 8.2.1.1 2023/11/16 10:05:57 mcalabre Exp mcalabre $
23 *=============================================================================
24 *
25 * WCSLIB 8.2 - C routines that implement the FITS World Coordinate System
26 * (WCS) standard. Refer to the README file provided with WCSLIB for an
27 * overview of the library.
28 *
29 *
30 * Summary of the wcshdr routines
31 * ------------------------------
32 * Routines in this suite are aimed at extracting WCS information from a FITS
33 * file. The information is encoded via keywords defined in
34 *
35 = "Representations of world coordinates in FITS",
36 = Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
37 =
38 = "Representations of celestial coordinates in FITS",
39 = Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (WCS Paper II)
40 =
41 = "Representations of spectral coordinates in FITS",
42 = Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
43 = 2006, A&A, 446, 747 (WCS Paper III)
44 =
45 = "Representations of distortions in FITS world coordinate systems",
46 = Calabretta, M.R. et al. (WCS Paper IV, draft dated 2004/04/22),
47 = available from http://www.atnf.csiro.au/people/Mark.Calabretta
48 =
49 = "Representations of time coordinates in FITS -
50 = Time and relative dimension in space",
51 = Rots, A.H., Bunclark, P.S., Calabretta, M.R., Allen, S.L.,
52 = Manchester, R.N., & Thompson, W.T. 2015, A&A, 574, A36 (WCS Paper VII)
53 *
54 * These routines provide the high-level interface between the FITS file and
55 * the WCS coordinate transformation routines.
56 *
57 * Additionally, function wcshdo() is provided to write out the contents of a
58 * wcsprm struct as a FITS header.
59 *
60 * Briefly, the anticipated sequence of operations is as follows:
61 *
62 * - 1: Open the FITS file and read the image or binary table header, e.g.
63 * using CFITSIO routine fits_hdr2str().
64 *
65 * - 2: Parse the header using wcspih() or wcsbth(); they will automatically
66 * interpret 'TAB' header keywords using wcstab().
67 *
68 * - 3: Allocate memory for, and read 'TAB' arrays from the binary table
69 * extension, e.g. using CFITSIO routine fits_read_wcstab() - refer to
70 * the prologue of getwcstab.h. wcsset() will automatically take
71 * control of this allocated memory, in particular causing it to be
72 * freed by wcsfree().
73 *
74 * - 4: Translate non-standard WCS usage using wcsfix(), see wcsfix.h.
75 *
76 * - 5: Initialize wcsprm struct(s) using wcsset() and calculate coordinates
77 * using wcsp2s() and/or wcss2p(). Refer to the prologue of wcs.h for a
78 * description of these and other high-level WCS coordinate
79 * transformation routines.
80 *
81 * - 6: Clean up by freeing memory with wcsvfree().
82 *
83 * In detail:
84 *
85 * - wcspih() is a high-level FITS WCS routine that parses an image header. It
86 * returns an array of up to 27 wcsprm structs on each of which it invokes
87 * wcstab().
88 *
89 * - wcsbth() is the analogue of wcspih() for use with binary tables; it
90 * handles image array and pixel list keywords. As an extension of the FITS
91 * WCS standard, it also recognizes image header keywords which may be used
92 * to provide default values via an inheritance mechanism.
93 *
94 * - wcstab() assists in filling in members of the wcsprm struct associated
95 * with coordinate lookup tables ('TAB'). These are based on arrays stored
96 * in a FITS binary table extension (BINTABLE) that are located by PVi_ma
97 * keywords in the image header.
98 *
99 * - wcsidx() and wcsbdx() are utility routines that return the index for a
100 * specified alternate coordinate descriptor in the array of wcsprm structs
101 * returned by wcspih() or wcsbth().
102 *
103 * - wcsvfree() deallocates memory for an array of wcsprm structs, such as
104 * returned by wcspih() or wcsbth().
105 *
106 * - wcshdo() writes out a wcsprm struct as a FITS header.
107 *
108 *
109 * wcspih() - FITS WCS parser routine for image headers
110 * ----------------------------------------------------
111 * wcspih() is a high-level FITS WCS routine that parses an image header,
112 * either that of a primary HDU or of an image extension. All WCS keywords
113 * defined in Papers I, II, III, IV, and VII are recognized, and also those
114 * used by the AIPS convention and certain other keywords that existed in early
115 * drafts of the WCS papers as explained in wcsbth() note 5. wcspih() also
116 * handles keywords associated with non-standard distortion functions described
117 * in the prologue of dis.h.
118 *
119 * Given a character array containing a FITS image header, wcspih() identifies
120 * and reads all WCS keywords for the primary coordinate representation and up
121 * to 26 alternate representations. It returns this information as an array of
122 * wcsprm structs.
123 *
124 * wcspih() invokes wcstab() on each of the wcsprm structs that it returns.
125 *
126 * Use wcsbth() in preference to wcspih() for FITS headers of unknown type;
127 * wcsbth() can parse image headers as well as binary table and pixel list
128 * headers, although it cannot handle keywords relating to distortion
129 * functions, which may only exist in an image header (primary or extension).
130 *
131 * Given and returned:
132 * header char[] Character array containing the (entire) FITS image
133 * header from which to identify and construct the
134 * coordinate representations, for example, as might be
135 * obtained conveniently via the CFITSIO routine
136 * fits_hdr2str().
137 *
138 * Each header "keyrecord" (formerly "card image")
139 * consists of exactly 80 7-bit ASCII printing characters
140 * in the range 0x20 to 0x7e (which excludes NUL, BS,
141 * TAB, LF, FF and CR) especially noting that the
142 * keyrecords are NOT null-terminated.
143 *
144 * For negative values of ctrl (see below), header[] is
145 * modified so that WCS keyrecords processed by wcspih()
146 * are removed from it.
147 *
148 * Given:
149 * nkeyrec int Number of keyrecords in header[].
150 *
151 * relax int Degree of permissiveness:
152 * 0: Recognize only FITS keywords defined by the
153 * published WCS standard.
154 * WCSHDR_all: Admit all recognized informal
155 * extensions of the WCS standard.
156 * Fine-grained control of the degree of permissiveness
157 * is also possible as explained in wcsbth() note 5.
158 *
159 * ctrl int Error reporting and other control options for invalid
160 * WCS and other header keyrecords:
161 * 0: Do not report any rejected header keyrecords.
162 * 1: Produce a one-line message stating the number
163 * of WCS keyrecords rejected (nreject).
164 * 2: Report each rejected keyrecord and the reason
165 * why it was rejected.
166 * 3: As above, but also report all non-WCS
167 * keyrecords that were discarded, and the number
168 * of coordinate representations (nwcs) found.
169 * 4: As above, but also report the accepted WCS
170 * keyrecords, with a summary of the number
171 * accepted as well as rejected.
172 * The report is written to stderr by default, or the
173 * stream set by wcsprintf_set().
174 *
175 * For ctrl < 0, WCS keyrecords processed by wcspih()
176 * are removed from header[]:
177 * -1: Remove only valid WCS keyrecords whose values
178 * were successfully extracted, nothing is
179 * reported.
180 * -2: As above, but also remove WCS keyrecords that
181 * were rejected, reporting each one and the
182 * reason that it was rejected.
183 * -3: As above, and also report the number of
184 * coordinate representations (nwcs) found.
185 * -11: Same as -1 but preserving global WCS-related
186 * keywords such as '{DATE,MJD}-{OBS,BEG,AVG,END}'
187 * and the other basic time-related keywords, and
188 * 'OBSGEO-{X,Y,Z,L,B,H}'.
189 * If any keyrecords are removed from header[] it will
190 * be null-terminated (NUL not being a legal FITS header
191 * character), otherwise it will contain its original
192 * complement of nkeyrec keyrecords and possibly not be
193 * null-terminated.
194 *
195 * Returned:
196 * nreject int* Number of WCS keywords rejected for syntax errors,
197 * illegal values, etc. Keywords not recognized as WCS
198 * keywords are simply ignored. Refer also to wcsbth()
199 * note 5.
200 *
201 * nwcs int* Number of coordinate representations found.
202 *
203 * wcs struct wcsprm**
204 * Pointer to an array of wcsprm structs containing up to
205 * 27 coordinate representations.
206 *
207 * Memory for the array is allocated by wcspih() which
208 * also invokes wcsini() for each struct to allocate
209 * memory for internal arrays and initialize their
210 * members to default values. Refer also to wcsbth()
211 * note 8. Note that wcsset() is not invoked on these
212 * structs.
213 *
214 * This allocated memory must be freed by the user, first
215 * by invoking wcsfree() for each struct, and then by
216 * freeing the array itself. A routine, wcsvfree(), is
217 * provided to do this (see below).
218 *
219 * Function return value:
220 * int Status return value:
221 * 0: Success.
222 * 1: Null wcsprm pointer passed.
223 * 2: Memory allocation failed.
224 * 4: Fatal error returned by Flex parser.
225 *
226 * Notes:
227 * 1: Refer to wcsbth() notes 1, 2, 3, 5, 7, and 8.
228 *
229 *
230 * wcsbth() - FITS WCS parser routine for binary table and image headers
231 * ---------------------------------------------------------------------
232 * wcsbth() is a high-level FITS WCS routine that parses a binary table header.
233 * It handles image array and pixel list WCS keywords which may be present
234 * together in one header.
235 *
236 * As an extension of the FITS WCS standard, wcsbth() also recognizes image
237 * header keywords in a binary table header. These may be used to provide
238 * default values via an inheritance mechanism discussed in note 5 (c.f.
239 * WCSHDR_AUXIMG and WCSHDR_ALLIMG), or may instead result in wcsprm structs
240 * that are not associated with any particular column. Thus wcsbth() can
241 * handle primary image and image extension headers in addition to binary table
242 * headers (it ignores NAXIS and does not rely on the presence of the TFIELDS
243 * keyword).
244 *
245 * All WCS keywords defined in Papers I, II, III, and VII are recognized, and
246 * also those used by the AIPS convention and certain other keywords that
247 * existed in early drafts of the WCS papers as explained in note 5 below.
248 *
249 * wcsbth() sets the colnum or colax[] members of the wcsprm structs that it
250 * returns with the column number of an image array or the column numbers
251 * associated with each pixel coordinate element in a pixel list. wcsprm
252 * structs that are not associated with any particular column, as may be
253 * derived from image header keywords, have colnum == 0.
254 *
255 * Note 6 below discusses the number of wcsprm structs returned by wcsbth(),
256 * and the circumstances in which image header keywords cause a struct to be
257 * created. See also note 9 concerning the number of separate images that may
258 * be stored in a pixel list.
259 *
260 * The API to wcsbth() is similar to that of wcspih() except for the addition
261 * of extra arguments that may be used to restrict its operation. Like
262 * wcspih(), wcsbth() invokes wcstab() on each of the wcsprm structs that it
263 * returns.
264 *
265 * Given and returned:
266 * header char[] Character array containing the (entire) FITS binary
267 * table, primary image, or image extension header from
268 * which to identify and construct the coordinate
269 * representations, for example, as might be obtained
270 * conveniently via the CFITSIO routine fits_hdr2str().
271 *
272 * Each header "keyrecord" (formerly "card image")
273 * consists of exactly 80 7-bit ASCII printing
274 * characters in the range 0x20 to 0x7e (which excludes
275 * NUL, BS, TAB, LF, FF and CR) especially noting that
276 * the keyrecords are NOT null-terminated.
277 *
278 * For negative values of ctrl (see below), header[] is
279 * modified so that WCS keyrecords processed by wcsbth()
280 * are removed from it.
281 *
282 * Given:
283 * nkeyrec int Number of keyrecords in header[].
284 *
285 * relax int Degree of permissiveness:
286 * 0: Recognize only FITS keywords defined by the
287 * published WCS standard.
288 * WCSHDR_all: Admit all recognized informal
289 * extensions of the WCS standard.
290 * Fine-grained control of the degree of permissiveness
291 * is also possible, as explained in note 5 below.
292 *
293 * ctrl int Error reporting and other control options for invalid
294 * WCS and other header keyrecords:
295 * 0: Do not report any rejected header keyrecords.
296 * 1: Produce a one-line message stating the number
297 * of WCS keyrecords rejected (nreject).
298 * 2: Report each rejected keyrecord and the reason
299 * why it was rejected.
300 * 3: As above, but also report all non-WCS
301 * keyrecords that were discarded, and the number
302 * of coordinate representations (nwcs) found.
303 * 4: As above, but also report the accepted WCS
304 * keyrecords, with a summary of the number
305 * accepted as well as rejected.
306 * The report is written to stderr by default, or the
307 * stream set by wcsprintf_set().
308 *
309 * For ctrl < 0, WCS keyrecords processed by wcsbth()
310 * are removed from header[]:
311 * -1: Remove only valid WCS keyrecords whose values
312 * were successfully extracted, nothing is
313 * reported.
314 * -2: Also remove WCS keyrecords that were rejected,
315 * reporting each one and the reason that it was
316 * rejected.
317 * -3: As above, and also report the number of
318 * coordinate representations (nwcs) found.
319 * -11: Same as -1 but preserving global WCS-related
320 * keywords such as '{DATE,MJD}-{OBS,BEG,AVG,END}'
321 * and the other basic time-related keywords, and
322 * 'OBSGEO-{X,Y,Z,L,B,H}'.
323 * If any keyrecords are removed from header[] it will
324 * be null-terminated (NUL not being a legal FITS header
325 * character), otherwise it will contain its original
326 * complement of nkeyrec keyrecords and possibly not be
327 * null-terminated.
328 *
329 * keysel int Vector of flag bits that may be used to restrict the
330 * keyword types considered:
331 * WCSHDR_IMGHEAD: Image header keywords.
332 * WCSHDR_BIMGARR: Binary table image array.
333 * WCSHDR_PIXLIST: Pixel list keywords.
334 * If zero, there is no restriction.
335 *
336 * Keywords such as EQUIna or RFRQna that are common to
337 * binary table image arrays and pixel lists (including
338 * WCSNna and TWCSna, as explained in note 4 below) are
339 * selected by both WCSHDR_BIMGARR and WCSHDR_PIXLIST.
340 * Thus if inheritance via WCSHDR_ALLIMG is enabled as
341 * discussed in note 5 and one of these shared keywords
342 * is present, then WCSHDR_IMGHEAD and WCSHDR_PIXLIST
343 * alone may be sufficient to cause the construction of
344 * coordinate descriptions for binary table image arrays.
345 *
346 * colsel int* Pointer to an array of table column numbers used to
347 * restrict the keywords considered by wcsbth().
348 *
349 * A null pointer may be specified to indicate that there
350 * is no restriction. Otherwise, the magnitude of
351 * cols[0] specifies the length of the array:
352 * cols[0] > 0: the columns are included,
353 * cols[0] < 0: the columns are excluded.
354 *
355 * For the pixel list keywords TPn_ka and TCn_ka (and
356 * TPCn_ka and TCDn_ka if WCSHDR_LONGKEY is enabled), it
357 * is an error for one column to be selected but not the
358 * other. This is unlike the situation with invalid
359 * keyrecords, which are simply rejected, because the
360 * error is not intrinsic to the header itself but
361 * arises in the way that it is processed.
362 *
363 * Returned:
364 * nreject int* Number of WCS keywords rejected for syntax errors,
365 * illegal values, etc. Keywords not recognized as WCS
366 * keywords are simply ignored, refer also to note 5
367 * below.
368 *
369 * nwcs int* Number of coordinate representations found.
370 *
371 * wcs struct wcsprm**
372 * Pointer to an array of wcsprm structs containing up
373 * to 27027 coordinate representations, refer to note 6
374 * below.
375 *
376 * Memory for the array is allocated by wcsbth() which
377 * also invokes wcsini() for each struct to allocate
378 * memory for internal arrays and initialize their
379 * members to default values. Refer also to note 8
380 * below. Note that wcsset() is not invoked on these
381 * structs.
382 *
383 * This allocated memory must be freed by the user, first
384 * by invoking wcsfree() for each struct, and then by
385 * freeing the array itself. A routine, wcsvfree(), is
386 * provided to do this (see below).
387 *
388 * Function return value:
389 * int Status return value:
390 * 0: Success.
391 * 1: Null wcsprm pointer passed.
392 * 2: Memory allocation failed.
393 * 3: Invalid column selection.
394 * 4: Fatal error returned by Flex parser.
395 *
396 * Notes:
397 * 1: wcspih() determines the number of coordinate axes independently for
398 * each alternate coordinate representation (denoted by the "a" value in
399 * keywords like CTYPEia) from the higher of
400 *
401 * a: NAXIS,
402 * b: WCSAXESa,
403 * c: The highest axis number in any parameterized WCS keyword. The
404 * keyvalue, as well as the keyword, must be syntactically valid
405 * otherwise it will not be considered.
406 *
407 * If none of these keyword types is present, i.e. if the header only
408 * contains auxiliary WCS keywords for a particular coordinate
409 * representation, then no coordinate description is constructed for it.
410 *
411 * wcsbth() is similar except that it ignores the NAXIS keyword if given
412 * an image header to process.
413 *
414 * The number of axes, which is returned as a member of the wcsprm
415 * struct, may differ for different coordinate representations of the
416 * same image.
417 *
418 * 2: wcspih() and wcsbth() enforce correct FITS "keyword = value" syntax
419 * with regard to "= " occurring in columns 9 and 10.
420 *
421 * However, they do recognize free-format character (NOST 100-2.0,
422 * Sect. 5.2.1), integer (Sect. 5.2.3), and floating-point values
423 * (Sect. 5.2.4) for all keywords.
424 *
425 * 3: Where CROTAn, CDi_ja, and PCi_ja occur together in one header wcspih()
426 * and wcsbth() treat them as described in the prologue to wcs.h.
427 *
428 * 4: WCS Paper I mistakenly defined the pixel list form of WCSNAMEa as
429 * TWCSna instead of WCSNna; the 'T' is meant to substitute for the axis
430 * number in the binary table form of the keyword - note that keywords
431 * defined in WCS Papers II, III, and VII that are not parameterized by
432 * axis number have identical forms for binary tables and pixel lists.
433 * Consequently wcsbth() always treats WCSNna and TWCSna as equivalent.
434 *
435 * 5: wcspih() and wcsbth() interpret the "relax" argument as a vector of
436 * flag bits to provide fine-grained control over what non-standard WCS
437 * keywords to accept. The flag bits are subject to change in future and
438 * should be set by using the preprocessor macros (see below) for the
439 * purpose.
440 *
441 * - WCSHDR_none: Don't accept any extensions (not even those in the
442 * errata). Treat non-conformant keywords in the same way as
443 * non-WCS keywords in the header, i.e. simply ignore them.
444 *
445 * - WCSHDR_all: Accept all extensions recognized by the parser.
446 *
447 * - WCSHDR_reject: Reject non-standard keyrecords (that are not otherwise
448 * explicitly accepted by one of the flags below). A message will
449 * optionally be printed on stderr by default, or the stream set
450 * by wcsprintf_set(), as determined by the ctrl argument, and
451 * nreject will be incremented.
452 *
453 * This flag may be used to signal the presence of non-standard
454 * keywords, otherwise they are simply passed over as though they
455 * did not exist in the header. It is mainly intended for testing
456 * conformance of a FITS header to the WCS standard.
457 *
458 * Keyrecords may be non-standard in several ways:
459 *
460 * - The keyword may be syntactically valid but with keyvalue of
461 * incorrect type or invalid syntax, or the keycomment may be
462 * malformed.
463 *
464 * - The keyword may strongly resemble a WCS keyword but not, in
465 * fact, be one because it does not conform to the standard.
466 * For example, "CRPIX01" looks like a CRPIXja keyword, but in
467 * fact the leading zero on the axis number violates the basic
468 * FITS standard. Likewise, "LONPOLE2" is not a valid
469 * LONPOLEa keyword in the WCS standard, and indeed there is
470 * nothing the parser can sensibly do with it.
471 *
472 * - Use of the keyword may be deprecated by the standard. Such
473 * will be rejected if not explicitly accepted via one of the
474 * flags below.
475 *
476 * - WCSHDR_strict: As for WCSHDR_reject, but also reject AIPS-convention
477 * keywords and all other deprecated usage that is not explicitly
478 * accepted.
479 *
480 * - WCSHDR_CROTAia: Accept CROTAia (wcspih()),
481 * iCROTna (wcsbth()),
482 * TCROTna (wcsbth()).
483 * - WCSHDR_VELREFa: Accept VELREFa.
484 * wcspih() always recognizes the AIPS-convention keywords,
485 * CROTAn, EPOCH, and VELREF for the primary representation
486 * (a = ' ') but alternates are non-standard.
487 *
488 * wcsbth() accepts EPOCHa and VELREFa only if WCSHDR_AUXIMG is
489 * also enabled.
490 *
491 * - WCSHDR_CD00i00j: Accept CD00i00j (wcspih()).
492 * - WCSHDR_PC00i00j: Accept PC00i00j (wcspih()).
493 * - WCSHDR_PROJPn: Accept PROJPn (wcspih()).
494 * These appeared in early drafts of WCS Paper I+II (before they
495 * were split) and are equivalent to CDi_ja, PCi_ja, and PVi_ma
496 * for the primary representation (a = ' '). PROJPn is
497 * equivalent to PVi_ma with m = n <= 9, and is associated
498 * exclusively with the latitude axis.
499 *
500 * - WCSHDR_CD0i_0ja: Accept CD0i_0ja (wcspih()).
501 * - WCSHDR_PC0i_0ja: Accept PC0i_0ja (wcspih()).
502 * - WCSHDR_PV0i_0ma: Accept PV0i_0ja (wcspih()).
503 * - WCSHDR_PS0i_0ma: Accept PS0i_0ja (wcspih()).
504 * Allow the numerical index to have a leading zero in doubly-
505 * parameterized keywords, for example, PC01_01. WCS Paper I
506 * (Sects 2.1.2 & 2.1.4) explicitly disallows leading zeroes.
507 * The FITS 3.0 standard document (Sect. 4.1.2.1) states that the
508 * index in singly-parameterized keywords (e.g. CTYPEia) "shall
509 * not have leading zeroes", and later in Sect. 8.1 that "leading
510 * zeroes must not be used" on PVi_ma and PSi_ma. However, by an
511 * oversight, it is silent on PCi_ja and CDi_ja.
512 *
513 * - WCSHDR_DOBSn (wcsbth() only): Allow DOBSn, the column-specific
514 * analogue of DATE-OBS. By an oversight this was never formally
515 * defined in the standard.
516 *
517 * - WCSHDR_OBSGLBHn (wcsbth() only): Allow OBSGLn, OBSGBn, and OBSGHn,
518 * the column-specific analogues of OBSGEO-L, OBSGEO-B, and
519 * OBSGEO-H. By an oversight these were never formally defined in
520 * the standard.
521 *
522 * - WCSHDR_RADECSYS: Accept RADECSYS. This appeared in early drafts of
523 * WCS Paper I+II and was subsequently replaced by RADESYSa.
524 *
525 * wcsbth() accepts RADECSYS only if WCSHDR_AUXIMG is also
526 * enabled.
527 *
528 * - WCSHDR_EPOCHa: Accept EPOCHa.
529 *
530 * - WCSHDR_VSOURCE: Accept VSOURCEa or VSOUna (wcsbth()). This appeared
531 * in early drafts of WCS Paper III and was subsequently dropped
532 * in favour of ZSOURCEa and ZSOUna.
533 *
534 * wcsbth() accepts VSOURCEa only if WCSHDR_AUXIMG is also
535 * enabled.
536 *
537 * - WCSHDR_DATEREF: Accept DATE-REF, MJD-REF, MJD-REFI, MJD-REFF, JDREF,
538 * JD-REFI, and JD-REFF as synonyms for the standard keywords,
539 * DATEREF, MJDREF, MJDREFI, MJDREFF, JDREF, JDREFI, and JDREFF.
540 * The latter buck the pattern set by the other date keywords
541 * ({DATE,MJD}-{OBS,BEG,AVG,END}), thereby increasing the
542 * potential for confusion and error.
543 *
544 * - WCSHDR_LONGKEY (wcsbth() only): Accept long forms of the alternate
545 * binary table and pixel list WCS keywords, i.e. with "a" non-
546 * blank. Specifically
547 *
548 # jCRPXna TCRPXna : jCRPXn jCRPna TCRPXn TCRPna CRPIXja
549 # - TPCn_ka : - ijPCna - TPn_ka PCi_ja
550 # - TCDn_ka : - ijCDna - TCn_ka CDi_ja
551 # iCDLTna TCDLTna : iCDLTn iCDEna TCDLTn TCDEna CDELTia
552 # iCUNIna TCUNIna : iCUNIn iCUNna TCUNIn TCUNna CUNITia
553 # iCTYPna TCTYPna : iCTYPn iCTYna TCTYPn TCTYna CTYPEia
554 # iCRVLna TCRVLna : iCRVLn iCRVna TCRVLn TCRVna CRVALia
555 # iPVn_ma TPVn_ma : - iVn_ma - TVn_ma PVi_ma
556 # iPSn_ma TPSn_ma : - iSn_ma - TSn_ma PSi_ma
557 *
558 * where the primary and standard alternate forms together with
559 * the image-header equivalent are shown rightwards of the colon.
560 *
561 * The long form of these keywords could be described as quasi-
562 * standard. TPCn_ka, iPVn_ma, and TPVn_ma appeared by mistake
563 * in the examples in WCS Paper II and subsequently these and
564 * also TCDn_ka, iPSn_ma and TPSn_ma were legitimized by the
565 * errata to the WCS papers.
566 *
567 * Strictly speaking, the other long forms are non-standard and
568 * in fact have never appeared in any draft of the WCS papers nor
569 * in the errata. However, as natural extensions of the primary
570 * form they are unlikely to be written with any other intention.
571 * Thus it should be safe to accept them provided, of course,
572 * that the resulting keyword does not exceed the 8-character
573 * limit.
574 *
575 * If WCSHDR_CNAMn is enabled then also accept
576 *
577 # iCNAMna TCNAMna : --- iCNAna --- TCNAna CNAMEia
578 # iCRDEna TCRDEna : --- iCRDna --- TCRDna CRDERia
579 # iCSYEna TCSYEna : --- iCSYna --- TCSYna CSYERia
580 # iCZPHna TCZPHna : --- iCZPna --- TCZPna CZPHSia
581 # iCPERna TCPERna : --- iCPRna --- TCPRna CPERIia
582 *
583 * Note that CNAMEia, CRDERia, CSYERia, CZPHSia, CPERIia, and
584 * their variants are not used by WCSLIB but are stored in the
585 * wcsprm struct as auxiliary information.
586 *
587 * - WCSHDR_CNAMn (wcsbth() only): Accept iCNAMn, iCRDEn, iCSYEn, iCZPHn,
588 * iCPERn, TCNAMn, TCRDEn, TCSYEn, TCZPHn, and TCPERn, i.e. with
589 * "a" blank. While non-standard, these are the obvious analogues
590 * of iCTYPn, TCTYPn, etc.
591 *
592 * - WCSHDR_AUXIMG (wcsbth() only): Allow the image-header form of an
593 * auxiliary WCS keyword with representation-wide scope to
594 * provide a default value for all images. This default may be
595 * overridden by the column-specific form of the keyword.
596 *
597 * For example, a keyword like EQUINOXa would apply to all image
598 * arrays in a binary table, or all pixel list columns with
599 * alternate representation "a" unless overridden by EQUIna.
600 *
601 * Specifically the keywords are:
602 *
603 # LONPOLEa for LONPna
604 # LATPOLEa for LATPna
605 # VELREF - ... (No column-specific form.)
606 # VELREFa - ... Only if WCSHDR_VELREFa is set.
607 *
608 * whose keyvalues are actually used by WCSLIB, and also keywords
609 * providing auxiliary information that is simply stored in the
610 * wcsprm struct:
611 *
612 # WCSNAMEa for WCSNna ... Or TWCSna (see below).
613 #
614 # DATE-OBS for DOBSn
615 # MJD-OBS for MJDOBn
616 #
617 # RADESYSa for RADEna
618 # RADECSYS for RADEna ... Only if WCSHDR_RADECSYS is set.
619 # EPOCH - ... (No column-specific form.)
620 # EPOCHa - ... Only if WCSHDR_EPOCHa is set.
621 # EQUINOXa for EQUIna
622 *
623 * where the image-header keywords on the left provide default
624 * values for the column specific keywords on the right.
625 *
626 * Note that, according to Sect. 8.1 of WCS Paper III, and
627 * Sect. 5.2 of WCS Paper VII, the following are always inherited:
628 *
629 # RESTFREQ for RFRQna
630 # RESTFRQa for RFRQna
631 # RESTWAVa for RWAVna
632 *
633 * being those actually used by WCSLIB, together with the
634 * following auxiliary keywords, many of which do not have binary
635 * table equivalents and therefore can only be inherited:
636 *
637 # TIMESYS -
638 # TREFPOS for TRPOSn
639 # TREFDIR for TRDIRn
640 # PLEPHEM -
641 # TIMEUNIT -
642 # DATEREF -
643 # MJDREF -
644 # MJDREFI -
645 # MJDREFF -
646 # JDREF -
647 # JDREFI -
648 # JDREFF -
649 # TIMEOFFS -
650 #
651 # DATE-BEG -
652 # DATE-AVG for DAVGn
653 # DATE-END -
654 # MJD-BEG -
655 # MJD-AVG for MJDAn
656 # MJD-END -
657 # JEPOCH -
658 # BEPOCH -
659 # TSTART -
660 # TSTOP -
661 # XPOSURE -
662 # TELAPSE -
663 #
664 # TIMSYER -
665 # TIMRDER -
666 # TIMEDEL -
667 # TIMEPIXR -
668 #
669 # OBSGEO-X for OBSGXn
670 # OBSGEO-Y for OBSGYn
671 # OBSGEO-Z for OBSGZn
672 # OBSGEO-L for OBSGLn
673 # OBSGEO-B for OBSGBn
674 # OBSGEO-H for OBSGHn
675 # OBSORBIT -
676 #
677 # SPECSYSa for SPECna
678 # SSYSOBSa for SOBSna
679 # VELOSYSa for VSYSna
680 # VSOURCEa for VSOUna ... Only if WCSHDR_VSOURCE is set.
681 # ZSOURCEa for ZSOUna
682 # SSYSSRCa for SSRCna
683 # VELANGLa for VANGna
684 *
685 * Global image-header keywords, such as MJD-OBS, apply to all
686 * alternate representations, and would therefore provide a
687 * default value for all images in the header.
688 *
689 * This auxiliary inheritance mechanism applies to binary table
690 * image arrays and pixel lists alike. Most of these keywords
691 * have no default value, the exceptions being LONPOLEa and
692 * LATPOLEa, and also RADESYSa and EQUINOXa which provide
693 * defaults for each other. Thus one potential difficulty in
694 * using WCSHDR_AUXIMG is that of erroneously inheriting one of
695 * these four keywords.
696 *
697 * Also, beware of potential inconsistencies that may arise where,
698 * for example, DATE-OBS is inherited, but MJD-OBS is overridden
699 * by MJDOBn and specifies a different time. Pairs in this
700 * category are:
701 *
702 = DATE-OBS/DOBSn versus MJD-OBS/MJDOBn
703 = DATE-AVG/DAVGn versus MJD-AVG/MJDAn
704 = RESTFRQa/RFRQna versus RESTWAVa/RWAVna
705 = OBSGEO-[XYZ]/OBSG[XYZ]n versus OBSGEO-[LBH]/OBSG[LBH]n
706 *
707 * The wcsfixi() routines datfix() and obsfix() are provided to
708 * check the consistency of these and other such pairs of
709 * keywords.
710 *
711 * Unlike WCSHDR_ALLIMG, the existence of one (or all) of these
712 * auxiliary WCS image header keywords will not by itself cause a
713 * wcsprm struct to be created for alternate representation "a".
714 * This is because they do not provide sufficient information to
715 * create a non-trivial coordinate representation when used in
716 * conjunction with the default values of those keywords that are
717 * parameterized by axis number, such as CTYPEia.
718 *
719 * - WCSHDR_ALLIMG (wcsbth() only): Allow the image-header form of *all*
720 * image header WCS keywords to provide a default value for all
721 * image arrays in a binary table (n.b. not pixel list). This
722 * default may be overridden by the column-specific form of the
723 * keyword.
724 *
725 * For example, a keyword like CRPIXja would apply to all image
726 * arrays in a binary table with alternate representation "a"
727 * unless overridden by jCRPna.
728 *
729 * Specifically the keywords are those listed above for
730 * WCSHDR_AUXIMG plus
731 *
732 # WCSAXESa for WCAXna
733 *
734 * which defines the coordinate dimensionality, and the following
735 * keywords that are parameterized by axis number:
736 *
737 # CRPIXja for jCRPna
738 # PCi_ja for ijPCna
739 # CDi_ja for ijCDna
740 # CDELTia for iCDEna
741 # CROTAi for iCROTn
742 # CROTAia - ... Only if WCSHDR_CROTAia is set.
743 # CUNITia for iCUNna
744 # CTYPEia for iCTYna
745 # CRVALia for iCRVna
746 # PVi_ma for iVn_ma
747 # PSi_ma for iSn_ma
748 #
749 # CNAMEia for iCNAna
750 # CRDERia for iCRDna
751 # CSYERia for iCSYna
752 # CZPHSia for iCZPna
753 # CPERIia for iCPRna
754 *
755 * where the image-header keywords on the left provide default
756 * values for the column specific keywords on the right.
757 *
758 * This full inheritance mechanism only applies to binary table
759 * image arrays, not pixel lists, because in the latter case
760 * there is no well-defined association between coordinate axis
761 * number and column number (see note 9 below).
762 *
763 * Note that CNAMEia, CRDERia, CSYERia, and their variants are
764 * not used by WCSLIB but are stored in the wcsprm struct as
765 * auxiliary information.
766 *
767 * Note especially that at least one wcsprm struct will be
768 * returned for each "a" found in one of the image header
769 * keywords listed above:
770 *
771 * - If the image header keywords for "a" ARE NOT inherited by a
772 * binary table, then the struct will not be associated with
773 * any particular table column number and it is up to the user
774 * to provide an association.
775 *
776 * - If the image header keywords for "a" ARE inherited by a
777 * binary table image array, then those keywords are considered
778 * to be "exhausted" and do not result in a separate wcsprm
779 * struct.
780 *
781 * For example, to accept CD00i00j and PC00i00j and reject all other
782 * extensions, use
783 *
784 = relax = WCSHDR_reject | WCSHDR_CD00i00j | WCSHDR_PC00i00j;
785 *
786 * The parser always treats EPOCH as subordinate to EQUINOXa if both are
787 * present, and VSOURCEa is always subordinate to ZSOURCEa.
788 *
789 * Likewise, VELREF is subordinate to the formalism of WCS Paper III, see
790 * spcaips().
791 *
792 * Neither wcspih() nor wcsbth() currently recognize the AIPS-convention
793 * keywords ALTRPIX or ALTRVAL which effectively define an alternative
794 * representation for a spectral axis.
795 *
796 * 6: Depending on what flags have been set in its "relax" argument,
797 * wcsbth() could return as many as 27027 wcsprm structs:
798 *
799 * - Up to 27 unattached representations derived from image header
800 * keywords.
801 *
802 * - Up to 27 structs for each of up to 999 columns containing an image
803 * arrays.
804 *
805 * - Up to 27 structs for a pixel list.
806 *
807 * Note that it is considered legitimate for a column to contain an image
808 * array and also form part of a pixel list, and in particular that
809 * wcsbth() does not check the TFORM keyword for a pixel list column to
810 * check that it is scalar.
811 *
812 * In practice, of course, a realistic binary table header is unlikely to
813 * contain more than a handful of images.
814 *
815 * In order for wcsbth() to create a wcsprm struct for a particular
816 * coordinate representation, at least one WCS keyword that defines an
817 * axis number must be present, either directly or by inheritance if
818 * WCSHDR_ALLIMG is set.
819 *
820 * When the image header keywords for an alternate representation are
821 * inherited by a binary table image array via WCSHDR_ALLIMG, those
822 * keywords are considered to be "exhausted" and do not result in a
823 * separate wcsprm struct. Otherwise they do.
824 *
825 * 7: Neither wcspih() nor wcsbth() check for duplicated keywords, in most
826 * cases they accept the last encountered.
827 *
828 * 8: wcspih() and wcsbth() use wcsnpv() and wcsnps() (refer to the prologue
829 * of wcs.h) to match the size of the pv[] and ps[] arrays in the wcsprm
830 * structs to the number in the header. Consequently there are no unused
831 * elements in the pv[] and ps[] arrays, indeed they will often be of
832 * zero length.
833 *
834 * 9: The FITS WCS standard for pixel lists assumes that a pixel list
835 * defines one and only one image, i.e. that each row of the binary table
836 * refers to just one event, e.g. the detection of a single photon or
837 * neutrino, for which the device "pixel" coordinates are stored in
838 * separate scalar columns of the table.
839 *
840 * In the absence of a standard for pixel lists - or even an informal
841 * description! - let alone a formal mechanism for identifying the columns
842 * containing pixel coordinates (as opposed to pixel values or metadata
843 * recorded at the time the photon or neutrino was detected), WCS Paper I
844 * discusses how the WCS keywords themselves may be used to identify them.
845 *
846 * In practice, however, pixel lists have been used to store multiple
847 * images. Besides not specifying how to identify columns, the pixel list
848 * convention is also silent on the method to be used to associate table
849 * columns with image axes.
850 *
851 * An additional shortcoming is the absence of a formal method for
852 * associating global binary-table WCS keywords, such as WCSNna or MJDOBn,
853 * with a pixel list image, whether one or several.
854 *
855 * In light of these uncertainties, wcsbth() simply collects all WCS
856 * keywords for a particular pixel list coordinate representation (i.e.
857 * the "a" value in TCTYna) into one wcsprm struct. However, these
858 * alternates need not be associated with the same table columns and this
859 * allows a pixel list to contain up to 27 separate images. As usual, if
860 * one of these representations happened to contain more than two
861 * celestial axes, for example, then an error would result when wcsset()
862 * is invoked on it. In this case the "colsel" argument could be used to
863 * restrict the columns used to construct the representation so that it
864 * only contained one pair of celestial axes.
865 *
866 * Global, binary-table WCS keywords are considered to apply to the pixel
867 * list image with matching alternate (e.g. the "a" value in LONPna or
868 * EQUIna), regardless of the table columns the image occupies. In other
869 * words, the column number is ignored (the "n" value in LONPna or
870 * EQUIna). This also applies for global, binary-table WCS keywords that
871 * have no alternates, such as MJDOBn and OBSGXn, which match all images
872 * in a pixel list. Take heed that this may lead to counterintuitive
873 * behaviour, especially where such a keyword references a column that
874 * does not store pixel coordinates, and moreso where the pixel list
875 * stores only a single image. In fact, as the column number, n, is
876 * ignored for such keywords, it would make no difference even if they
877 * referenced non-existent columns. Moreover, there is no requirement for
878 * consistency in the column numbers used for such keywords, even for
879 * OBSGXn, OBSGYn, and OBSGZn which are meant to define the elements of a
880 * coordinate vector. Although it would surely be perverse to construct a
881 * pixel list like this, such a situation may still arise in practice
882 * where columns are deleted from a binary table.
883 *
884 * The situation with global, binary-table WCS keywords becomes
885 * potentially even more confusing when image arrays and pixel list images
886 * coexist in one binary table. In that case, a keyword such as MJDOBn
887 * may legitimately appear multiple times with n referencing different
888 * image arrays. Which then is the one that applies to the pixel list
889 * images? In this implementation, it is the last instance that appears
890 * in the header, whether or not it is also associated with an image
891 * array.
892 *
893 *
894 * wcstab() - Tabular construction routine
895 * ---------------------------------------
896 * wcstab() assists in filling in the information in the wcsprm struct relating
897 * to coordinate lookup tables.
898 *
899 * Tabular coordinates ('TAB') present certain difficulties in that the main
900 * components of the lookup table - the multidimensional coordinate array plus
901 * an index vector for each dimension - are stored in a FITS binary table
902 * extension (BINTABLE). Information required to locate these arrays is stored
903 * in PVi_ma and PSi_ma keywords in the image header.
904 *
905 * wcstab() parses the PVi_ma and PSi_ma keywords associated with each 'TAB'
906 * axis and allocates memory in the wcsprm struct for the required number of
907 * tabprm structs. It sets as much of the tabprm struct as can be gleaned from
908 * the image header, and also sets up an array of wtbarr structs (described in
909 * the prologue of wtbarr.h) to assist in extracting the required arrays from
910 * the BINTABLE extension(s).
911 *
912 * It is then up to the user to allocate memory for, and copy arrays from the
913 * BINTABLE extension(s) into the tabprm structs. A CFITSIO routine,
914 * fits_read_wcstab(), has been provided for this purpose, see getwcstab.h.
915 * wcsset() will automatically take control of this allocated memory, in
916 * particular causing it to be freed by wcsfree(); the user must not attempt
917 * to free it after wcsset() has been called.
918 *
919 * Note that wcspih() and wcsbth() automatically invoke wcstab() on each of the
920 * wcsprm structs that they return.
921 *
922 * Given and returned:
923 * wcs struct wcsprm*
924 * Coordinate transformation parameters (see below).
925 *
926 * wcstab() sets ntab, tab, nwtb and wtb, allocating
927 * memory for the tab and wtb arrays. This allocated
928 * memory will be freed automatically by wcsfree().
929 *
930 * Function return value:
931 * int Status return value:
932 * 0: Success.
933 * 1: Null wcsprm pointer passed.
934 * 2: Memory allocation failed.
935 * 3: Invalid tabular parameters.
936 *
937 * For returns > 1, a detailed error message is set in
938 * wcsprm::err if enabled, see wcserr_enable().
939 *
940 *
941 * wcsidx() - Index alternate coordinate representations
942 * -----------------------------------------------------
943 * wcsidx() returns an array of 27 indices for the alternate coordinate
944 * representations in the array of wcsprm structs returned by wcspih(). For
945 * the array returned by wcsbth() it returns indices for the unattached
946 * (colnum == 0) representations derived from image header keywords - use
947 * wcsbdx() for those derived from binary table image arrays or pixel lists
948 * keywords.
949 *
950 * Given:
951 * nwcs int Number of coordinate representations in the array.
952 *
953 * wcs const struct wcsprm**
954 * Pointer to an array of wcsprm structs returned by
955 * wcspih() or wcsbth().
956 *
957 * Returned:
958 * alts int[27] Index of each alternate coordinate representation in
959 * the array: alts[0] for the primary, alts[1] for 'A',
960 * etc., set to -1 if not present.
961 *
962 * For example, if there was no 'P' representation then
963 *
964 = alts['P'-'A'+1] == -1;
965 *
966 * Otherwise, the address of its wcsprm struct would be
967 *
968 = wcs + alts['P'-'A'+1];
969 *
970 * Function return value:
971 * int Status return value:
972 * 0: Success.
973 * 1: Null wcsprm pointer passed.
974 *
975 *
976 * wcsbdx() - Index alternate coordinate representions
977 * ---------------------------------------------------
978 * wcsbdx() returns an array of 999 x 27 indices for the alternate coordinate
979 * representions for binary table image arrays xor pixel lists in the array of
980 * wcsprm structs returned by wcsbth(). Use wcsidx() for the unattached
981 * representations derived from image header keywords.
982 *
983 * Given:
984 * nwcs int Number of coordinate representations in the array.
985 *
986 * wcs const struct wcsprm**
987 * Pointer to an array of wcsprm structs returned by
988 * wcsbth().
989 *
990 * type int Select the type of coordinate representation:
991 * 0: binary table image arrays,
992 * 1: pixel lists.
993 *
994 * Returned:
995 * alts short[1000][28]
996 * Index of each alternate coordinate represention in the
997 * array: alts[col][0] for the primary, alts[col][1] for
998 * 'A', to alts[col][26] for 'Z', where col is the
999 * 1-relative column number, and col == 0 is used for
1000 * unattached image headers. Set to -1 if not present.
1001 *
1002 * alts[col][27] counts the number of coordinate
1003 * representations of the chosen type for each column.
1004 *
1005 * For example, if there was no 'P' represention for
1006 * column 13 then
1007 *
1008 = alts[13]['P'-'A'+1] == -1;
1009 *
1010 * Otherwise, the address of its wcsprm struct would be
1011 *
1012 = wcs + alts[13]['P'-'A'+1];
1013 *
1014 * Function return value:
1015 * int Status return value:
1016 * 0: Success.
1017 * 1: Null wcsprm pointer passed.
1018 *
1019 *
1020 * wcsvfree() - Free the array of wcsprm structs
1021 * ---------------------------------------------
1022 * wcsvfree() frees the memory allocated by wcspih() or wcsbth() for the array
1023 * of wcsprm structs, first invoking wcsfree() on each of the array members.
1024 *
1025 * Given and returned:
1026 * nwcs int* Number of coordinate representations found; set to 0
1027 * on return.
1028 *
1029 * wcs struct wcsprm**
1030 * Pointer to the array of wcsprm structs; set to 0x0 on
1031 * return.
1032 *
1033 * Function return value:
1034 * int Status return value:
1035 * 0: Success.
1036 * 1: Null wcsprm pointer passed.
1037 *
1038 *
1039 * wcshdo() - Write out a wcsprm struct as a FITS header
1040 * -----------------------------------------------------
1041 * wcshdo() translates a wcsprm struct into a FITS header. If the colnum
1042 * member of the struct is non-zero then a binary table image array header will
1043 * be produced. Otherwise, if the colax[] member of the struct is set non-zero
1044 * then a pixel list header will be produced. Otherwise, a primary image or
1045 * image extension header will be produced.
1046 *
1047 * If the struct was originally constructed from a header, e.g. by wcspih(),
1048 * the output header will almost certainly differ in a number of respects:
1049 *
1050 * - The output header only contains WCS-related keywords. In particular, it
1051 * does not contain syntactically-required keywords such as SIMPLE, NAXIS,
1052 * BITPIX, or END.
1053 *
1054 * - Elements of the PCi_ja matrix will be written if and only if they differ
1055 * from the unit matrix. Thus, if the matrix is unity then no elements
1056 * will be written.
1057 *
1058 * - The redundant keywords MJDREF, JDREF, JDREFI, JDREFF, all of which
1059 * duplicate MJDREFI + MJDREFF, are never written. OBSGEO-[LBH] are not
1060 * written if OBSGEO-[XYZ] are defined.
1061 *
1062 * - Deprecated (e.g. CROTAn, RESTFREQ, VELREF, RADECSYS, EPOCH, VSOURCEa) or
1063 * non-standard usage will be translated to standard (this is partially
1064 * dependent on whether wcsfix() was applied).
1065 *
1066 * - Additional keywords such as WCSAXESa, CUNITia, LONPOLEa and LATPOLEa may
1067 * appear.
1068 *
1069 * - Quantities will be converted to the units used internally, basically SI
1070 * with the addition of degrees.
1071 *
1072 * - Floating-point quantities may be given to a different decimal precision.
1073 *
1074 * - The original keycomments will be lost, although wcshdo() tries hard to
1075 * write meaningful comments.
1076 *
1077 * - Keyword order will almost certainly be changed.
1078 *
1079 * Keywords can be translated between the image array, binary table, and pixel
1080 * lists forms by manipulating the colnum or colax[] members of the wcsprm
1081 * struct.
1082 *
1083 * Given:
1084 * ctrl int Vector of flag bits that controls the degree of
1085 * permissiveness in departing from the published WCS
1086 * standard, and also controls the formatting of
1087 * floating-point keyvalues. Set it to zero to get the
1088 * default behaviour.
1089 *
1090 * Flag bits for the degree of permissiveness:
1091 * WCSHDO_none: Recognize only FITS keywords defined by
1092 * the published WCS standard.
1093 * WCSHDO_all: Admit all recognized informal extensions
1094 * of the WCS standard.
1095 * Fine-grained control of the degree of permissiveness
1096 * is also possible as explained in the notes below.
1097 *
1098 * As for controlling floating-point formatting, by
1099 * default wcshdo() uses "%20.12G" for non-parameterized
1100 * keywords such as LONPOLEa, and attempts to make the
1101 * header more human-readable by using the same "%f"
1102 * format for all values of each of the following
1103 * parameterized keywords: CRPIXja, PCi_ja, and CDELTia
1104 * (n.b. excluding CRVALia). Each has the same field
1105 * width and precision so that the decimal points line
1106 * up. The precision, allowing for up to 15 significant
1107 * digits, is chosen so that there are no excess trailing
1108 * zeroes. A similar formatting scheme applies by
1109 * default for distortion function parameters.
1110 *
1111 * However, where the values of, for example, CDELTia
1112 * differ by many orders of magnitude, the default
1113 * formatting scheme may cause unacceptable loss of
1114 * precision for the lower-valued keyvalues. Thus the
1115 * default behaviour may be overridden:
1116 * WCSHDO_P12: Use "%20.12G" format for all floating-
1117 * point keyvalues (12 significant digits).
1118 * WCSHDO_P13: Use "%21.13G" format for all floating-
1119 * point keyvalues (13 significant digits).
1120 * WCSHDO_P14: Use "%22.14G" format for all floating-
1121 * point keyvalues (14 significant digits).
1122 * WCSHDO_P15: Use "%23.15G" format for all floating-
1123 * point keyvalues (15 significant digits).
1124 * WCSHDO_P16: Use "%24.16G" format for all floating-
1125 * point keyvalues (16 significant digits).
1126 * WCSHDO_P17: Use "%25.17G" format for all floating-
1127 * point keyvalues (17 significant digits).
1128 * If more than one of the above flags are set, the
1129 * highest number of significant digits prevails. In
1130 * addition, there is an anciliary flag:
1131 * WCSHDO_EFMT: Use "%E" format instead of the default
1132 * "%G" format above.
1133 * Note that excess trailing zeroes are stripped off the
1134 * fractional part with "%G" (which never occurs with
1135 * "%E"). Note also that the higher-precision options
1136 * eat into the keycomment area. In this regard,
1137 * WCSHDO_P14 causes minimal disruption with "%G" format,
1138 * while WCSHDO_P13 is appropriate with "%E".
1139 *
1140 * Given and returned:
1141 * wcs struct wcsprm*
1142 * Pointer to a wcsprm struct containing coordinate
1143 * transformation parameters. Will be initialized if
1144 * necessary.
1145 *
1146 * Returned:
1147 * nkeyrec int* Number of FITS header keyrecords returned in the
1148 * "header" array.
1149 *
1150 * header char** Pointer to an array of char holding the header.
1151 * Storage for the array is allocated by wcshdo() in
1152 * blocks of 2880 bytes (32 x 80-character keyrecords)
1153 * and must be freed by the user to avoid memory leaks.
1154 * See wcsdealloc().
1155 *
1156 * Each keyrecord is 80 characters long and is *NOT*
1157 * null-terminated, so the first keyrecord starts at
1158 * (*header)[0], the second at (*header)[80], etc.
1159 *
1160 * Function return value:
1161 * int Status return value (associated with wcs_errmsg[]):
1162 * 0: Success.
1163 * 1: Null wcsprm pointer passed.
1164 * 2: Memory allocation failed.
1165 * 3: Linear transformation matrix is singular.
1166 * 4: Inconsistent or unrecognized coordinate axis
1167 * types.
1168 * 5: Invalid parameter value.
1169 * 6: Invalid coordinate transformation parameters.
1170 * 7: Ill-conditioned coordinate transformation
1171 * parameters.
1172 *
1173 * For returns > 1, a detailed error message is set in
1174 * wcsprm::err if enabled, see wcserr_enable().
1175 *
1176 * Notes:
1177 * 1: wcshdo() interprets the "relax" argument as a vector of flag bits to
1178 * provide fine-grained control over what non-standard WCS keywords to
1179 * write. The flag bits are subject to change in future and should be set
1180 * by using the preprocessor macros (see below) for the purpose.
1181 *
1182 * - WCSHDO_none: Don't use any extensions.
1183 *
1184 * - WCSHDO_all: Write all recognized extensions, equivalent to setting
1185 * each flag bit.
1186 *
1187 * - WCSHDO_safe: Write all extensions that are considered to be safe and
1188 * recommended.
1189 *
1190 * - WCSHDO_DOBSn: Write DOBSn, the column-specific analogue of DATE-OBS
1191 * for use in binary tables and pixel lists. WCS Paper III
1192 * introduced DATE-AVG and DAVGn but by an oversight DOBSn (the
1193 * obvious analogy) was never formally defined by the standard.
1194 * The alternative to using DOBSn is to write DATE-OBS which
1195 * applies to the whole table. This usage is considered to be
1196 * safe and is recommended.
1197 *
1198 * - WCSHDO_TPCn_ka: WCS Paper I defined
1199 *
1200 * - TPn_ka and TCn_ka for pixel lists
1201 *
1202 * but WCS Paper II uses TPCn_ka in one example and subsequently
1203 * the errata for the WCS papers legitimized the use of
1204 *
1205 * - TPCn_ka and TCDn_ka for pixel lists
1206 *
1207 * provided that the keyword does not exceed eight characters.
1208 * This usage is considered to be safe and is recommended because
1209 * of the non-mnemonic terseness of the shorter forms.
1210 *
1211 * - WCSHDO_PVn_ma: WCS Paper I defined
1212 *
1213 * - iVn_ma and iSn_ma for bintables and
1214 * - TVn_ma and TSn_ma for pixel lists
1215 *
1216 * but WCS Paper II uses iPVn_ma and TPVn_ma in the examples and
1217 * subsequently the errata for the WCS papers legitimized the use
1218 * of
1219 *
1220 * - iPVn_ma and iPSn_ma for bintables and
1221 * - TPVn_ma and TPSn_ma for pixel lists
1222 *
1223 * provided that the keyword does not exceed eight characters.
1224 * This usage is considered to be safe and is recommended because
1225 * of the non-mnemonic terseness of the shorter forms.
1226 *
1227 * - WCSHDO_CRPXna: For historical reasons WCS Paper I defined
1228 *
1229 * - jCRPXn, iCDLTn, iCUNIn, iCTYPn, and iCRVLn for bintables and
1230 * - TCRPXn, TCDLTn, TCUNIn, TCTYPn, and TCRVLn for pixel lists
1231 *
1232 * for use without an alternate version specifier. However,
1233 * because of the eight-character keyword constraint, in order to
1234 * accommodate column numbers greater than 99 WCS Paper I also
1235 * defined
1236 *
1237 * - jCRPna, iCDEna, iCUNna, iCTYna and iCRVna for bintables and
1238 * - TCRPna, TCDEna, TCUNna, TCTYna and TCRVna for pixel lists
1239 *
1240 * for use with an alternate version specifier (the "a"). Like
1241 * the PC, CD, PV, and PS keywords there is an obvious tendency to
1242 * confuse these two forms for column numbers up to 99. It is
1243 * very unlikely that any parser would reject keywords in the
1244 * first set with a non-blank alternate version specifier so this
1245 * usage is considered to be safe and is recommended.
1246 *
1247 * - WCSHDO_CNAMna: WCS Papers I and III defined
1248 *
1249 * - iCNAna, iCRDna, and iCSYna for bintables and
1250 * - TCNAna, TCRDna, and TCSYna for pixel lists
1251 *
1252 * By analogy with the above, the long forms would be
1253 *
1254 * - iCNAMna, iCRDEna, and iCSYEna for bintables and
1255 * - TCNAMna, TCRDEna, and TCSYEna for pixel lists
1256 *
1257 * Note that these keywords provide auxiliary information only,
1258 * none of them are needed to compute world coordinates. This
1259 * usage is potentially unsafe and is not recommended at this
1260 * time.
1261 *
1262 * - WCSHDO_WCSNna: In light of wcsbth() note 4, write WCSNna instead of
1263 * TWCSna for pixel lists. While wcsbth() treats WCSNna and
1264 * TWCSna as equivalent, other parsers may not. Consequently,
1265 * this usage is potentially unsafe and is not recommended at this
1266 * time.
1267 *
1268 *
1269 * Global variable: const char *wcshdr_errmsg[] - Status return messages
1270 * ---------------------------------------------------------------------
1271 * Error messages to match the status value returned from each function.
1272 * Use wcs_errmsg[] for status returns from wcshdo().
1273 *
1274 *===========================================================================*/
1275
1276 #ifndef WCSLIB_WCSHDR
1277 #define WCSLIB_WCSHDR
1278
1279 #include "wcs.h"
1280
1281 #ifdef __cplusplus
1282 extern "C" {
1283 #endif
1284
1285 #define WCSHDR_none 0x00000000
1286 #define WCSHDR_all 0x000FFFFF
1287 #define WCSHDR_reject 0x10000000
1288 #define WCSHDR_strict 0x20000000
1289
1290 #define WCSHDR_CROTAia 0x00000001
1291 #define WCSHDR_VELREFa 0x00000002
1292 #define WCSHDR_CD00i00j 0x00000004
1293 #define WCSHDR_PC00i00j 0x00000008
1294 #define WCSHDR_PROJPn 0x00000010
1295 #define WCSHDR_CD0i_0ja 0x00000020
1296 #define WCSHDR_PC0i_0ja 0x00000040
1297 #define WCSHDR_PV0i_0ma 0x00000080
1298 #define WCSHDR_PS0i_0ma 0x00000100
1299 #define WCSHDR_DOBSn 0x00000200
1300 #define WCSHDR_OBSGLBHn 0x00000400
1301 #define WCSHDR_RADECSYS 0x00000800
1302 #define WCSHDR_EPOCHa 0x00001000
1303 #define WCSHDR_VSOURCE 0x00002000
1304 #define WCSHDR_DATEREF 0x00004000
1305 #define WCSHDR_LONGKEY 0x00008000
1306 #define WCSHDR_CNAMn 0x00010000
1307 #define WCSHDR_AUXIMG 0x00020000
1308 #define WCSHDR_ALLIMG 0x00040000
1309
1310 #define WCSHDR_IMGHEAD 0x00100000
1311 #define WCSHDR_BIMGARR 0x00200000
1312 #define WCSHDR_PIXLIST 0x00400000
1313
1314 #define WCSHDO_none 0x00000
1315 #define WCSHDO_all 0x000FF
1316 #define WCSHDO_safe 0x0000F
1317 #define WCSHDO_DOBSn 0x00001
1318 #define WCSHDO_TPCn_ka 0x00002
1319 #define WCSHDO_PVn_ma 0x00004
1320 #define WCSHDO_CRPXna 0x00008
1321 #define WCSHDO_CNAMna 0x00010
1322 #define WCSHDO_WCSNna 0x00020
1323 #define WCSHDO_P12 0x01000
1324 #define WCSHDO_P13 0x02000
1325 #define WCSHDO_P14 0x04000
1326 #define WCSHDO_P15 0x08000
1327 #define WCSHDO_P16 0x10000
1328 #define WCSHDO_P17 0x20000
1329 #define WCSHDO_EFMT 0x40000
1330
1331
1332 extern const char *wcshdr_errmsg[];
1333
1334 enum wcshdr_errmsg_enum {
1335 WCSHDRERR_SUCCESS = 0, // Success.
1336 WCSHDRERR_NULL_POINTER = 1, // Null wcsprm pointer passed.
1337 WCSHDRERR_MEMORY = 2, // Memory allocation failed.
1338 WCSHDRERR_BAD_COLUMN = 3, // Invalid column selection.
1339 WCSHDRERR_PARSER = 4, // Fatal error returned by Flex
1340 // parser.
1341 WCSHDRERR_BAD_TABULAR_PARAMS = 5 // Invalid tabular parameters.
1342 };
1343
1344 int wcspih(char *header, int nkeyrec, int relax, int ctrl, int *nreject,
1345 int *nwcs, struct wcsprm **wcs);
1346
1347 int wcsbth(char *header, int nkeyrec, int relax, int ctrl, int keysel,
1348 int *colsel, int *nreject, int *nwcs, struct wcsprm **wcs);
1349
1350 int wcstab(struct wcsprm *wcs);
1351
1352 int wcsidx(int nwcs, struct wcsprm **wcs, int alts[27]);
1353
1354 int wcsbdx(int nwcs, struct wcsprm **wcs, int type, short alts[1000][28]);
1355
1356 int wcsvfree(int *nwcs, struct wcsprm **wcs);
1357
1358 int wcshdo(int ctrl, struct wcsprm *wcs, int *nkeyrec, char **header);
1359
1360
1361 #ifdef __cplusplus
1362 }
1363 #endif
1364
1365 #endif // WCSLIB_WCSHDR
Browse
Usage
Versions