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