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