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