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