00001 /*============================================================================ 00002 00003 WCSLIB 4.8 - an implementation of the FITS WCS standard. 00004 Copyright (C) 1995-2011, Mark Calabretta 00005 00006 This file is part of WCSLIB. 00007 00008 WCSLIB is free software: you can redistribute it and/or modify it under the 00009 terms of the GNU Lesser General Public License as published by the Free 00010 Software Foundation, either version 3 of the License, or (at your option) 00011 any later version. 00012 00013 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY 00014 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00015 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for 00016 more details. 00017 00018 You should have received a copy of the GNU Lesser General Public License 00019 along with WCSLIB. If not, see <http://www.gnu.org/licenses/>. 00020 00021 Correspondence concerning WCSLIB may be directed to: 00022 Internet email: mcalabre@atnf.csiro.au 00023 Postal address: Dr. Mark Calabretta 00024 Australia Telescope National Facility, CSIRO 00025 PO Box 76 00026 Epping NSW 1710 00027 AUSTRALIA 00028 00029 Author: Mark Calabretta, Australia Telescope National Facility 00030 http://www.atnf.csiro.au/~mcalabre/index.html 00031 $Id: wcshdr.h,v 4.8.1.1 2011/08/15 08:07:06 cal103 Exp cal103 $ 00032 *============================================================================= 00033 * 00034 * WCSLIB 4.8 - C routines that implement the FITS World Coordinate System 00035 * (WCS) standard. Refer to 00036 * 00037 * "Representations of world coordinates in FITS", 00038 * Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I) 00039 * 00040 * "Representations of celestial coordinates in FITS", 00041 * Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (Paper II) 00042 * 00043 * "Representations of spectral coordinates in FITS", 00044 * Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L. 00045 * 2006, A&A, 446, 747 (Paper III) 00046 * 00047 * Refer to the README file provided with WCSLIB for an overview of the 00048 * library. 00049 * 00050 * 00051 * Summary of the wcshdr routines 00052 * ------------------------------ 00053 * Routines in this suite are aimed at extracting WCS information from a FITS 00054 * file. They provide the high-level interface between the FITS file and the 00055 * WCS coordinate transformation routines. 00056 * 00057 * Additionally, function wcshdo() is provided to write out the contents of a 00058 * wcsprm struct as a FITS header. 00059 * 00060 * Briefly, the anticipated sequence of operations is as follows: 00061 * 00062 * - 1: Open the FITS file and read the image or binary table header, e.g. 00063 * using CFITSIO routine fits_hdr2str(). 00064 * 00065 * - 2: Parse the header using wcspih() or wcsbth(); they will automatically 00066 * interpret 'TAB' header keywords using wcstab(). 00067 * 00068 * - 3: Allocate memory for, and read 'TAB' arrays from the binary table 00069 * extension, e.g. using CFITSIO routine fits_read_wcstab() - refer to 00070 * the prologue of getwcstab.h. wcsset() will automatically take 00071 * control of this allocated memory, in particular causing it to be 00072 * free'd by wcsfree(). 00073 * 00074 * - 4: Translate non-standard WCS usage using wcsfix(), see wcsfix.h. 00075 * 00076 * - 5: Initialize wcsprm struct(s) using wcsset() and calculate coordinates 00077 * using wcsp2s() and/or wcss2p(). Refer to the prologue of wcs.h for a 00078 * description of these and other high-level WCS coordinate 00079 * transformation routines. 00080 * 00081 * - 6: Clean up by freeing memory with wcsvfree(). 00082 * 00083 * In detail: 00084 * 00085 * - wcspih() is a high-level FITS WCS routine that parses an image header. It 00086 * returns an array of up to 27 wcsprm structs on each of which it invokes 00087 * wcstab(). 00088 * 00089 * - wcsbth() is the analogue of wcspih() for use with binary tables; it 00090 * handles image array and pixel list keywords. As an extension of the FITS 00091 * WCS standard, it also recognizes image header keywords which may be used 00092 * to provide default values via an inheritance mechanism. 00093 * 00094 * - wcstab() assists in filling in members of the wcsprm struct associated 00095 * with coordinate lookup tables ('TAB'). These are based on arrays stored 00096 * in a FITS binary table extension (BINTABLE) that are located by PVi_ma 00097 * keywords in the image header. 00098 * 00099 * - wcsidx() and wcsbdx() are utility routines that return the index for a 00100 * specified alternate coordinate descriptor in the array of wcsprm structs 00101 * returned by wcspih() or wcsbth(). 00102 * 00103 * - wcsvfree() deallocates memory for an array of wcsprm structs, such as 00104 * returned by wcspih() or wcsbth(). 00105 * 00106 * - wcshdo() writes out a wcsprm struct as a FITS header. 00107 * 00108 * 00109 * wcspih() - FITS WCS parser routine for image headers 00110 * ---------------------------------------------------- 00111 * wcspih() is a high-level FITS WCS routine that parses an image header, 00112 * either that of a primary HDU or of an image extension. All WCS keywords 00113 * defined in Papers I, II, and III are recognized, and also those used by the 00114 * AIPS convention and certain other keywords that existed in early drafts of 00115 * the WCS papers as explained in wcsbth() note 5. 00116 * 00117 * Given a character array containing a FITS image header, wcspih() identifies 00118 * and reads all WCS keywords for the primary coordinate representation and up 00119 * to 26 alternate representations. It returns this information as an array of 00120 * wcsprm structs. 00121 * 00122 * wcspih() invokes wcstab() on each of the wcsprm structs that it returns. 00123 * 00124 * Use wcsbth() in preference to wcspih() for FITS headers of unknown type; 00125 * wcsbth() can parse image headers as well as binary table and pixel list 00126 * headers. 00127 * 00128 * Given and returned: 00129 * header char[] Character array containing the (entire) FITS image 00130 * header from which to identify and construct the 00131 * coordinate representations, for example, as might be 00132 * obtained conveniently via the CFITSIO routine 00133 * fits_hdr2str(). 00134 * 00135 * Each header "keyrecord" (formerly "card image") 00136 * consists of exactly 80 7-bit ASCII printing characters 00137 * in the range 0x20 to 0x7e (which excludes NUL, BS, 00138 * TAB, LF, FF and CR) especially noting that the 00139 * keyrecords are NOT null-terminated. 00140 * 00141 * For negative values of ctrl (see below), header[] is 00142 * modified so that WCS keyrecords processed by wcspih() 00143 * are removed from it. 00144 * 00145 * Given: 00146 * nkeyrec int Number of keyrecords in header[]. 00147 * 00148 * relax int Degree of permissiveness: 00149 * 0: Recognize only FITS keywords defined by the 00150 * published WCS standard. 00151 * WCSHDR_all: Admit all recognized informal 00152 * extensions of the WCS standard. 00153 * Fine-grained control of the degree of permissiveness 00154 * is also possible as explained in wcsbth() note 5. 00155 * 00156 * ctrl int Error reporting and other control options for invalid 00157 * WCS and other header keyrecords: 00158 * 0: Do not report any rejected header keyrecords. 00159 * 1: Produce a one-line message stating the number 00160 * of WCS keyrecords rejected (nreject). 00161 * 2: Report each rejected keyrecord and the reason 00162 * why it was rejected. 00163 * 3: As above, but also report all non-WCS 00164 * keyrecords that were discarded, and the number 00165 * of coordinate representations (nwcs) found. 00166 * The report is written to stderr. 00167 * 00168 * For ctrl < 0, WCS keyrecords processed by wcspih() 00169 * are removed from header[]: 00170 * -1: Remove only valid WCS keyrecords whose values 00171 * were successfully extracted, nothing is 00172 * reported. 00173 * -2: Also remove WCS keyrecords that were rejected, 00174 * reporting each one and the reason that it was 00175 * rejected. 00176 * -3: As above, and also report the number of 00177 * coordinate representations (nwcs) found. 00178 * -11: Same as -1 but preserving the basic keywords 00179 * '{DATE,MJD}-{OBS,AVG}' and 'OBSGEO-{X,Y,Z}'. 00180 * If any keyrecords are removed from header[] it will 00181 * be null-terminated (NUL not being a legal FITS header 00182 * character), otherwise it will contain its original 00183 * complement of nkeyrec keyrecords and possibly not be 00184 * null-terminated. 00185 * 00186 * Returned: 00187 * nreject int* Number of WCS keywords rejected for syntax errors, 00188 * illegal values, etc. Keywords not recognized as WCS 00189 * keywords are simply ignored. Refer also to wcsbth() 00190 * note 5. 00191 * 00192 * nwcs int* Number of coordinate representations found. 00193 * 00194 * wcs struct wcsprm** 00195 * Pointer to an array of wcsprm structs containing up to 00196 * 27 coordinate representations. 00197 * 00198 * Memory for the array is allocated by wcspih() which 00199 * also invokes wcsini() for each struct to allocate 00200 * memory for internal arrays and initialize their 00201 * members to default values. Refer also to wcsbth() 00202 * note 8. Note that wcsset() is not invoked on these 00203 * structs. 00204 * 00205 * This allocated memory must be freed by the user, first 00206 * by invoking wcsfree() for each struct, and then by 00207 * freeing the array itself. A routine, wcsvfree(), is 00208 * provided to do this (see below). 00209 * 00210 * Function return value: 00211 * int Status return value: 00212 * 0: Success. 00213 * 1: Null wcsprm pointer passed. 00214 * 2: Memory allocation failed. 00215 * 4: Fatal error returned by Flex parser. 00216 * 00217 * Notes: 00218 * Refer to wcsbth() notes 1, 2, 3, 5, 7, and 8. 00219 * 00220 * 00221 * wcsbth() - FITS WCS parser routine for binary table and image headers 00222 * --------------------------------------------------------------------- 00223 * wcsbth() is a high-level FITS WCS routine that parses a binary table header. 00224 * It handles image array and pixel list WCS keywords which may be present 00225 * together in one header. 00226 * 00227 * As an extension of the FITS WCS standard, wcsbth() also recognizes image 00228 * header keywords in a binary table header. These may be used to provide 00229 * default values via an inheritance mechanism discussed in note 5 (c.f. 00230 * WCSHDR_AUXIMG and WCSHDR_ALLIMG), or may instead result in wcsprm structs 00231 * that are not associated with any particular column. Thus wcsbth() can 00232 * handle primary image and image extension headers in addition to binary table 00233 * headers (it ignores NAXIS and does not rely on the presence of the TFIELDS 00234 * keyword). 00235 * 00236 * All WCS keywords defined in Papers I, II, and III are recognized, and also 00237 * those used by the AIPS convention and certain other keywords that existed in 00238 * early drafts of the WCS papers as explained in note 5 below. 00239 * 00240 * wcsbth() sets the colnum or colax[] members of the wcsprm structs that it 00241 * returns with the column number of an image array or the column numbers 00242 * associated with each pixel coordinate element in a pixel list. wcsprm 00243 * structs that are not associated with any particular column, as may be 00244 * derived from image header keywords, have colnum == 0. 00245 * 00246 * Note 6 below discusses the number of wcsprm structs returned by wcsbth(), 00247 * and the circumstances in which image header keywords cause a struct to be 00248 * created. See also note 9 concerning the number of separate images that may 00249 * be stored in a pixel list. 00250 * 00251 * The API to wcsbth() is similar to that of wcspih() except for the addition 00252 * of extra arguments that may be used to restrict its operation. Like 00253 * wcspih(), wcsbth() invokes wcstab() on each of the wcsprm structs that it 00254 * returns. 00255 * 00256 * Given and returned: 00257 * header char[] Character array containing the (entire) FITS binary 00258 * table, primary image, or image extension header from 00259 * which to identify and construct the coordinate 00260 * representations, for example, as might be obtained 00261 * conveniently via the CFITSIO routine fits_hdr2str(). 00262 * 00263 * Each header "keyrecord" (formerly "card image") 00264 * consists of exactly 80 7-bit ASCII printing 00265 * characters in the range 0x20 to 0x7e (which excludes 00266 * NUL, BS, TAB, LF, FF and CR) especially noting that 00267 * the keyrecords are NOT null-terminated. 00268 * 00269 * For negative values of ctrl (see below), header[] is 00270 * modified so that WCS keyrecords processed by wcsbth() 00271 * are removed from it. 00272 * 00273 * Given: 00274 * nkeyrec int Number of keyrecords in header[]. 00275 * 00276 * relax int Degree of permissiveness: 00277 * 0: Recognize only FITS keywords defined by the 00278 * published WCS standard. 00279 * WCSHDR_all: Admit all recognized informal 00280 * extensions of the WCS standard. 00281 * Fine-grained control of the degree of permissiveness 00282 * is also possible, as explained in note 5 below. 00283 * 00284 * ctrl int Error reporting and other control options for invalid 00285 * WCS and other header keyrecords: 00286 * 0: Do not report any rejected header keyrecords. 00287 * 1: Produce a one-line message stating the number 00288 * of WCS keyrecords rejected (nreject). 00289 * 2: Report each rejected keyrecord and the reason 00290 * why it was rejected. 00291 * 3: As above, but also report all non-WCS 00292 * keyrecords that were discarded, and the number 00293 * of coordinate representations (nwcs) found. 00294 * The report is written to stderr. 00295 * 00296 * For ctrl < 0, WCS keyrecords processed by wcsbth() 00297 * are removed from header[]: 00298 * -1: Remove only valid WCS keyrecords whose values 00299 * were successfully extracted, nothing is 00300 * reported. 00301 * -2: Also remove WCS keyrecords that were rejected, 00302 * reporting each one and the reason that it was 00303 * rejected. 00304 * -3: As above, and also report the number of 00305 * coordinate representations (nwcs) found. 00306 * -11: Same as -1 but preserving the basic keywords 00307 * '{DATE,MJD}-{OBS,AVG}' and 'OBSGEO-{X,Y,Z}'. 00308 * If any keyrecords are removed from header[] it will 00309 * be null-terminated (NUL not being a legal FITS header 00310 * character), otherwise it will contain its original 00311 * complement of nkeyrec keyrecords and possibly not be 00312 * null-terminated. 00313 * 00314 * keysel int Vector of flag bits that may be used to restrict the 00315 * keyword types considered: 00316 * WCSHDR_IMGHEAD: Image header keywords. 00317 * WCSHDR_BIMGARR: Binary table image array. 00318 * WCSHDR_PIXLIST: Pixel list keywords. 00319 * If zero, there is no restriction. 00320 * 00321 * Keywords such as EQUIna or RFRQna that are common to 00322 * binary table image arrays and pixel lists (including 00323 * WCSNna and TWCSna, as explained in note 4 below) are 00324 * selected by both WCSHDR_BIMGARR and WCSHDR_PIXLIST. 00325 * Thus if inheritance via WCSHDR_ALLIMG is enabled as 00326 * discussed in note 5 and one of these shared keywords 00327 * is present, then WCSHDR_IMGHEAD and WCSHDR_PIXLIST 00328 * alone may be sufficient to cause the construction of 00329 * coordinate descriptions for binary table image arrays. 00330 * 00331 * colsel int* Pointer to an array of table column numbers used to 00332 * restrict the keywords considered by wcsbth(). 00333 * 00334 * A null pointer may be specified to indicate that there 00335 * is no restriction. Otherwise, the magnitude of 00336 * cols[0] specifies the length of the array: 00337 * cols[0] > 0: the columns are included, 00338 * cols[0] < 0: the columns are excluded. 00339 * 00340 * For the pixel list keywords TPn_ka and TCn_ka (and 00341 * TPCn_ka and TCDn_ka if WCSHDR_LONGKEY is enabled), it 00342 * is an error for one column to be selected but not the 00343 * other. This is unlike the situation with invalid 00344 * keyrecords, which are simply rejected, because the 00345 * error is not intrinsic to the header itself but 00346 * arises in the way that it is processed. 00347 * 00348 * Returned: 00349 * nreject int* Number of WCS keywords rejected for syntax errors, 00350 * illegal values, etc. Keywords not recognized as WCS 00351 * keywords are simply ignored, refer also to note 5 00352 * below. 00353 * 00354 * nwcs int* Number of coordinate representations found. 00355 * 00356 * wcs struct wcsprm** 00357 * Pointer to an array of wcsprm structs containing up 00358 * to 27027 coordinate representations, refer to note 6 00359 * below. 00360 * 00361 * Memory for the array is allocated by wcsbth() which 00362 * also invokes wcsini() for each struct to allocate 00363 * memory for internal arrays and initialize their 00364 * members to default values. Refer also to note 8 00365 * below. Note that wcsset() is not invoked on these 00366 * structs. 00367 * 00368 * This allocated memory must be freed by the user, first 00369 * by invoking wcsfree() for each struct, and then by 00370 * freeing the array itself. A routine, wcsvfree(), is 00371 * provided to do this (see below). 00372 * 00373 * Function return value: 00374 * int Status return value: 00375 * 0: Success. 00376 * 1: Null wcsprm pointer passed. 00377 * 2: Memory allocation failed. 00378 * 3: Invalid column selection. 00379 * 4: Fatal error returned by Flex parser. 00380 * 00381 * Notes: 00382 * 1: wcspih() determines the number of coordinate axes independently for 00383 * each alternate coordinate representation (denoted by the "a" value in 00384 * keywords like CTYPEia) from the higher of 00385 * 00386 * a: NAXIS, 00387 * b: WCSAXESa, 00388 * c: The highest axis number in any parameterized WCS keyword. The 00389 * keyvalue, as well as the keyword, must be syntactically valid 00390 * otherwise it will not be considered. 00391 * 00392 * If none of these keyword types is present, i.e. if the header only 00393 * contains auxiliary WCS keywords for a particular coordinate 00394 * representation, then no coordinate description is constructed for it. 00395 * 00396 * wcsbth() is similar except that it ignores the NAXIS keyword if given 00397 * an image header to process. 00398 * 00399 * The number of axes, which is returned as a member of the wcsprm 00400 * struct, may differ for different coordinate representations of the 00401 * same image. 00402 * 00403 * 2: wcspih() and wcsbth() enforce correct FITS "keyword = value" syntax 00404 * with regard to "= " occurring in columns 9 and 10. 00405 * 00406 * However, they do recognize free-format character (NOST 100-2.0, 00407 * Sect. 5.2.1), integer (Sect. 5.2.3), and floating-point values 00408 * (Sect. 5.2.4) for all keywords. 00409 * 00410 * 3: Where CROTAn, CDi_ja, and PCi_ja occur together in one header wcspih() 00411 * and wcsbth() treat them as described in the prologue to wcs.h. 00412 * 00413 * 4: WCS Paper I mistakenly defined the pixel list form of WCSNAMEa as 00414 * TWCSna instead of WCSNna; the 'T' is meant to substitute for the axis 00415 * number in the binary table form of the keyword - note that keywords 00416 * defined in WCS Papers II and III that are not parameterised by axis 00417 * number have identical forms for binary tables and pixel lists. 00418 * Consequently wcsbth() always treats WCSNna and TWCSna as equivalent. 00419 * 00420 * 5: wcspih() and wcsbth() interpret the "relax" argument as a vector of 00421 * flag bits to provide fine-grained control over what non-standard WCS 00422 * keywords to accept. The flag bits are subject to change in future and 00423 * should be set by using the preprocessor macros (see below) for the 00424 * purpose. 00425 * 00426 * - WCSHDR_none: Don't accept any extensions (not even those in the 00427 * errata). Treat non-conformant keywords in the same way as 00428 * non-WCS keywords in the header, i.e. simply ignore them. 00429 * 00430 * - WCSHDR_all: Accept all extensions recognized by the parser. 00431 * 00432 * - WCSHDR_reject: Reject non-standard keywords (that are not otherwise 00433 * accepted). A message will optionally be printed on stderr, as 00434 * determined by the ctrl argument, and nreject will be 00435 * incremented. 00436 * 00437 * This flag may be used to signal the presence of non-standard 00438 * keywords, otherwise they are simply passed over as though they 00439 * did not exist in the header. 00440 * 00441 * Useful for testing conformance of a FITS header to the WCS 00442 * standard. 00443 * 00444 * - WCSHDR_CROTAia: Accept CROTAia (wcspih()), 00445 * iCROTna (wcsbth()), 00446 * TCROTna (wcsbth()). 00447 * - WCSHDR_EPOCHa: Accept EPOCHa. 00448 * - WCSHDR_VELREFa: Accept VELREFa. 00449 * wcspih() always recognizes the AIPS-convention keywords, 00450 * CROTAn, EPOCH, and VELREF for the primary representation 00451 * (a = ' ') but alternates are non-standard. 00452 * 00453 * wcsbth() accepts EPOCHa and VELREFa only if WCSHDR_AUXIMG is 00454 * also enabled. 00455 * 00456 * - WCSHDR_CD00i00j: Accept CD00i00j (wcspih()). 00457 * - WCSHDR_PC00i00j: Accept PC00i00j (wcspih()). 00458 * - WCSHDR_PROJPn: Accept PROJPn (wcspih()). 00459 * These appeared in early drafts of WCS Paper I+II (before they 00460 * were split) and are equivalent to CDi_ja, PCi_ja, and PVi_ma 00461 * for the primary representation (a = ' '). PROJPn is 00462 * equivalent to PVi_ma with m = n <= 9, and is associated 00463 * exclusively with the latitude axis. 00464 * 00465 * - WCSHDR_RADECSYS: Accept RADECSYS. This appeared in early drafts of 00466 * WCS Paper I+II and was subsequently replaced by RADESYSa. 00467 * 00468 * wcsbth() accepts RADECSYS only if WCSHDR_AUXIMG is also 00469 * enabled. 00470 * 00471 * - WCSHDR_VSOURCE: Accept VSOURCEa or VSOUna (wcsbth()). This appeared 00472 * in early drafts of WCS Paper III and was subsequently dropped 00473 * in favour of ZSOURCEa and ZSOUna. 00474 * 00475 * wcsbth() accepts VSOURCEa only if WCSHDR_AUXIMG is also 00476 * enabled. 00477 * 00478 * - WCSHDR_DOBSn (wcsbth() only): Allow DOBSn, the column-specific analogue 00479 * of DATE-OBS. By an oversight this was never formally defined 00480 * in the standard. 00481 * 00482 * - WCSHDR_LONGKEY (wcsbth() only): Accept long forms of the alternate 00483 * binary table and pixel list WCS keywords, i.e. with "a" non- 00484 * blank. Specifically 00485 * 00486 # jCRPXna TCRPXna : jCRPXn jCRPna TCRPXn TCRPna CRPIXja 00487 # - TPCn_ka : - ijPCna - TPn_ka PCi_ja 00488 # - TCDn_ka : - ijCDna - TCn_ka CDi_ja 00489 # iCDLTna TCDLTna : iCDLTn iCDEna TCDLTn TCDEna CDELTia 00490 # iCUNIna TCUNIna : iCUNIn iCUNna TCUNIn TCUNna CUNITia 00491 # iCTYPna TCTYPna : iCTYPn iCTYna TCTYPn TCTYna CTYPEia 00492 # iCRVLna TCRVLna : iCRVLn iCRVna TCRVLn TCRVna CRVALia 00493 # iPVn_ma TPVn_ma : - iVn_ma - TVn_ma PVi_ma 00494 # iPSn_ma TPSn_ma : - iSn_ma - TSn_ma PSi_ma 00495 * 00496 * where the primary and standard alternate forms together with 00497 * the image-header equivalent are shown rightwards of the colon. 00498 * 00499 * The long form of these keywords could be described as quasi- 00500 * standard. TPCn_ka, iPVn_ma, and TPVn_ma appeared by mistake 00501 * in the examples in WCS Paper II and subsequently these and 00502 * also TCDn_ka, iPSn_ma and TPSn_ma were legitimized by the 00503 * errata to the WCS papers. 00504 * 00505 * Strictly speaking, the other long forms are non-standard and 00506 * in fact have never appeared in any draft of the WCS papers nor 00507 * in the errata. However, as natural extensions of the primary 00508 * form they are unlikely to be written with any other intention. 00509 * Thus it should be safe to accept them provided, of course, 00510 * that the resulting keyword does not exceed the 8-character 00511 * limit. 00512 * 00513 * If WCSHDR_CNAMn is enabled then also accept 00514 * 00515 # iCNAMna TCNAMna : --- iCNAna --- TCNAna CNAMEia 00516 # iCRDEna TCRDEna : --- iCRDna --- TCRDna CRDERia 00517 # iCSYEna TCSYEna : --- iCSYna --- TCSYna CSYERia 00518 * 00519 * Note that CNAMEia, CRDERia, CSYERia, and their variants are 00520 * not used by WCSLIB but are stored in the wcsprm struct as 00521 * auxiliary information. 00522 * 00523 * - WCSHDR_CNAMn (wcsbth() only): Accept iCNAMn, iCRDEn, iCSYEn, TCNAMn, 00524 * TCRDEn, and TCSYEn, i.e. with "a" blank. While non-standard, 00525 * these are the obvious analogues of iCTYPn, TCTYPn, etc. 00526 * 00527 * - WCSHDR_AUXIMG (wcsbth() only): Allow the image-header form of an 00528 * auxiliary WCS keyword with representation-wide scope to 00529 * provide a default value for all images. This default may be 00530 * overridden by the column-specific form of the keyword. 00531 * 00532 * For example, a keyword like EQUINOXa would apply to all image 00533 * arrays in a binary table, or all pixel list columns with 00534 * alternate representation "a" unless overridden by EQUIna. 00535 * 00536 * Specifically the keywords are: 00537 * 00538 # LATPOLEa for LATPna 00539 # LONPOLEa for LONPna 00540 # RESTFREQ for RFRQna 00541 # RESTFRQa for RFRQna 00542 # RESTWAVa for RWAVna 00543 * 00544 * whose keyvalues are actually used by WCSLIB, and also keywords 00545 * that provide auxiliary information that is simply stored in 00546 * the wcsprm struct: 00547 * 00548 # EPOCH - ... (No column-specific form.) 00549 # EPOCHa - ... Only if WCSHDR_EPOCHa is set. 00550 # EQUINOXa for EQUIna 00551 # RADESYSa for RADEna 00552 # RADECSYS for RADEna ... Only if WCSHDR_RADECSYS is set. 00553 # SPECSYSa for SPECna 00554 # SSYSOBSa for SOBSna 00555 # SSYSSRCa for SSRCna 00556 # VELOSYSa for VSYSna 00557 # VELANGLa for VANGna 00558 # VELREF - ... (No column-specific form.) 00559 # VELREFa - ... Only if WCSHDR_VELREFa is set. 00560 # VSOURCEa for VSOUna ... Only if WCSHDR_VSOURCE is set. 00561 # WCSNAMEa for WCSNna ... Or TWCSna (see below). 00562 # ZSOURCEa for ZSOUna 00563 * 00564 # DATE-AVG for DAVGn 00565 # DATE-OBS for DOBSn 00566 # MJD-AVG for MJDAn 00567 # MJD-OBS for MJDOBn 00568 # OBSGEO-X for OBSGXn 00569 # OBSGEO-Y for OBSGYn 00570 # OBSGEO-Z for OBSGZn 00571 * 00572 * where the image-header keywords on the left provide default 00573 * values for the column specific keywords on the right. 00574 * 00575 * Keywords in the last group, such as MJD-OBS, apply to all 00576 * alternate representations, so MJD-OBS would provide a default 00577 * value for all images in the header. 00578 * 00579 * This auxiliary inheritance mechanism applies to binary table 00580 * image arrays and pixel lists alike. Most of these keywords 00581 * have no default value, the exceptions being LONPOLEa and 00582 * LATPOLEa, and also RADESYSa and EQUINOXa which provide 00583 * defaults for each other. Thus the only potential difficulty 00584 * in using WCSHDR_AUXIMG is that of erroneously inheriting one 00585 * of these four keywords. 00586 * 00587 * Unlike WCSHDR_ALLIMG, the existence of one (or all) of these 00588 * auxiliary WCS image header keywords will not by itself cause a 00589 * wcsprm struct to be created for alternate representation "a". 00590 * This is because they do not provide sufficient information to 00591 * create a non-trivial coordinate representation when used in 00592 * conjunction with the default values of those keywords, such as 00593 * CTYPEia, that are parameterized by axis number. 00594 * 00595 * - WCSHDR_ALLIMG (wcsbth() only): Allow the image-header form of *all* 00596 * image header WCS keywords to provide a default value for all 00597 * image arrays in a binary table (n.b. not pixel list). This 00598 * default may be overridden by the column-specific form of the 00599 * keyword. 00600 * 00601 * For example, a keyword like CRPIXja would apply to all image 00602 * arrays in a binary table with alternate representation "a" 00603 * unless overridden by jCRPna. 00604 * 00605 * Specifically the keywords are those listed above for 00606 * WCSHDR_AUXIMG plus 00607 * 00608 # WCSAXESa for WCAXna 00609 * 00610 * which defines the coordinate dimensionality, and the following 00611 * keywords which are parameterized by axis number: 00612 * 00613 # CRPIXja for jCRPna 00614 # PCi_ja for ijPCna 00615 # CDi_ja for ijCDna 00616 # CDELTia for iCDEna 00617 # CROTAi for iCROTn 00618 # CROTAia - ... Only if WCSHDR_CROTAia is set. 00619 # CUNITia for iCUNna 00620 # CTYPEia for iCTYna 00621 # CRVALia for iCRVna 00622 # PVi_ma for iVn_ma 00623 # PSi_ma for iSn_ma 00624 * 00625 # CNAMEia for iCNAna 00626 # CRDERia for iCRDna 00627 # CSYERia for iCSYna 00628 * 00629 * where the image-header keywords on the left provide default 00630 * values for the column specific keywords on the right. 00631 * 00632 * This full inheritance mechanism only applies to binary table 00633 * image arrays, not pixel lists, because in the latter case 00634 * there is no well-defined association between coordinate axis 00635 * number and column number. 00636 * 00637 * Note that CNAMEia, CRDERia, CSYERia, and their variants are 00638 * not used by WCSLIB but are stored in the wcsprm struct as 00639 * auxiliary information. 00640 * 00641 * Note especially that at least one wcsprm struct will be 00642 * returned for each "a" found in one of the image header 00643 * keywords listed above: 00644 * 00645 * - If the image header keywords for "a" ARE NOT inherited by a 00646 * binary table, then the struct will not be associated with 00647 * any particular table column number and it is up to the user 00648 * to provide an association. 00649 * 00650 * - If the image header keywords for "a" ARE inherited by a 00651 * binary table image array, then those keywords are considered 00652 * to be "exhausted" and do not result in a separate wcsprm 00653 * struct. 00654 * 00655 * For example, to accept CD00i00j and PC00i00j and reject all other 00656 * extensions, use 00657 * 00658 = relax = WCSHDR_reject | WCSHDR_CD00i00j | WCSHDR_PC00i00j; 00659 * 00660 * The parser always treats EPOCH as subordinate to EQUINOXa if both are 00661 * present, and VSOURCEa is always subordinate to ZSOURCEa. 00662 * 00663 * Likewise, VELREF is subordinate to the formalism of WCS Paper III, see 00664 * spcaips(). 00665 * 00666 * Neither wcspih() nor wcsbth() currently recognize the AIPS-convention 00667 * keywords ALTRPIX or ALTRVAL which effectively define an alternative 00668 * representation for a spectral axis. 00669 * 00670 * 6: Depending on what flags have been set in its "relax" argument, 00671 * wcsbth() could return as many as 27027 wcsprm structs: 00672 * 00673 * - Up to 27 unattached representations derived from image header 00674 * keywords. 00675 * 00676 * - Up to 27 structs for each of up to 999 columns containing an image 00677 * arrays. 00678 * 00679 * - Up to 27 structs for a pixel list. 00680 * 00681 * Note that it is considered legitimate for a column to contain an image 00682 * array and also form part of a pixel list, and in particular that 00683 * wcsbth() does not check the TFORM keyword for a pixel list column to 00684 * check that it is scalar. 00685 * 00686 * In practice, of course, a realistic binary table header is unlikely to 00687 * contain more than a handful of images. 00688 * 00689 * In order for wcsbth() to create a wcsprm struct for a particular 00690 * coordinate representation, at least one WCS keyword that defines an 00691 * axis number must be present, either directly or by inheritance if 00692 * WCSHDR_ALLIMG is set. 00693 * 00694 * When the image header keywords for an alternate representation are 00695 * inherited by a binary table image array via WCSHDR_ALLIMG, those 00696 * keywords are considered to be "exhausted" and do not result in a 00697 * separate wcsprm struct. Otherwise they do. 00698 * 00699 * 7: Neither wcspih() nor wcsbth() check for duplicated keywords, in most 00700 * cases they accept the last encountered. 00701 * 00702 * 8: wcspih() and wcsbth() use wcsnpv() and wcsnps() (refer to the prologue 00703 * of wcs.h) to match the size of the pv[] and ps[] arrays in the wcsprm 00704 * structs to the number in the header. Consequently there are no unused 00705 * elements in the pv[] and ps[] arrays, indeed they will often be of 00706 * zero length. 00707 * 00708 * 9: The FITS WCS standard for pixel lists assumes that a pixel list 00709 * defines one and only one image, i.e. that each row of the binary table 00710 * refers to just one event, e.g. the detection of a single photon or 00711 * neutrino. 00712 * 00713 * In the absence of a formal mechanism for identifying the columns 00714 * containing pixel coordinates (as opposed to pixel values or ancillary 00715 * data recorded at the time the photon or neutrino was detected), 00716 * Paper I discusses how the WCS keywords themselves may be used to 00717 * identify them. 00718 * 00719 * In practice, however, pixel lists have been used to store multiple 00720 * images. Besides not specifying how to identify columns, the pixel 00721 * list convention is also silent on the method to be used to associate 00722 * table columns with image axes. 00723 * 00724 * wcsbth() simply collects all WCS keywords for a particular coordinate 00725 * representation (i.e. the "a" value in TCTYna) into one wcsprm struct. 00726 * However, these alternates need not be associated with the same table 00727 * columns and this allows a pixel list to contain up to 27 separate 00728 * images. As usual, if one of these representations happened to contain 00729 * more than two celestial axes, for example, then an error would result 00730 * when wcsset() is invoked on it. In this case the "colsel" argument 00731 * could be used to restrict the columns used to construct the 00732 * representation so that it only contained one pair of celestial axes. 00733 * 00734 * 00735 * wcstab() - Tabular construction routine 00736 * --------------------------------------- 00737 * wcstab() assists in filling in the information in the wcsprm struct relating 00738 * to coordinate lookup tables. 00739 * 00740 * Tabular coordinates ('TAB') present certain difficulties in that the main 00741 * components of the lookup table - the multidimensional coordinate array plus 00742 * an index vector for each dimension - are stored in a FITS binary table 00743 * extension (BINTABLE). Information required to locate these arrays is stored 00744 * in PVi_ma and PSi_ma keywords in the image header. 00745 * 00746 * wcstab() parses the PVi_ma and PSi_ma keywords associated with each 'TAB' 00747 * axis and allocates memory in the wcsprm struct for the required number of 00748 * tabprm structs. It sets as much of the tabprm struct as can be gleaned from 00749 * the image header, and also sets up an array of wtbarr structs (described in 00750 * the prologue of wcs.h) to assist in extracting the required arrays from the 00751 * BINTABLE extension(s). 00752 * 00753 * It is then up to the user to allocate memory for, and copy arrays from the 00754 * BINTABLE extension(s) into the tabprm structs. A CFITSIO routine, 00755 * fits_read_wcstab(), has been provided for this purpose, see getwcstab.h. 00756 * wcsset() will automatically take control of this allocated memory, in 00757 * particular causing it to be free'd by wcsfree(); the user must not attempt 00758 * to free it after wcsset() has been called. 00759 * 00760 * Note that wcspih() and wcsbth() automatically invoke wcstab() on each of the 00761 * wcsprm structs that they return. 00762 * 00763 * Given and returned: 00764 * wcs struct wcsprm* 00765 * Coordinate transformation parameters (see below). 00766 * 00767 * wcstab() sets ntab, tab, nwtb and wtb, allocating 00768 * memory for the tab and wtb arrays. This allocated 00769 * memory will be free'd automatically by wcsfree(). 00770 * 00771 * Function return value: 00772 * int Status return value: 00773 * 0: Success. 00774 * 1: Null wcsprm pointer passed. 00775 * 2: Memory allocation failed. 00776 * 3: Invalid tabular parameters. 00777 * 00778 * For returns > 1, a detailed error message is set in 00779 * wcsprm::err if enabled, see wcserr_enable(). 00780 * 00781 * 00782 * wcsidx() - Index alternate coordinate representations 00783 * ----------------------------------------------------- 00784 * wcsidx() returns an array of 27 indices for the alternate coordinate 00785 * representations in the array of wcsprm structs returned by wcspih(). For 00786 * the array returned by wcsbth() it returns indices for the unattached 00787 * (colnum == 0) representations derived from image header keywords - use 00788 * wcsbdx() for those derived from binary table image arrays or pixel lists 00789 * keywords. 00790 * 00791 * Given: 00792 * nwcs int Number of coordinate representations in the array. 00793 * 00794 * wcs const struct wcsprm** 00795 * Pointer to an array of wcsprm structs returned by 00796 * wcspih() or wcsbth(). 00797 * 00798 * Returned: 00799 * alts int[27] Index of each alternate coordinate representation in 00800 * the array: alts[0] for the primary, alts[1] for 'A', 00801 * etc., set to -1 if not present. 00802 * 00803 * For example, if there was no 'P' representation then 00804 * 00805 = alts['P'-'A'+1] == -1; 00806 * 00807 * Otherwise, the address of its wcsprm struct would be 00808 * 00809 = wcs + alts['P'-'A'+1]; 00810 * 00811 * Function return value: 00812 * int Status return value: 00813 * 0: Success. 00814 * 1: Null wcsprm pointer passed. 00815 * 00816 * 00817 * wcsbdx() - Index alternate coordinate representions 00818 * --------------------------------------------------- 00819 * wcsbdx() returns an array of 999 x 27 indices for the alternate coordinate 00820 * representions for binary table image arrays xor pixel lists in the array of 00821 * wcsprm structs returned by wcsbth(). Use wcsidx() for the unattached 00822 * representations derived from image header keywords. 00823 * 00824 * Given: 00825 * nwcs int Number of coordinate representations in the array. 00826 * 00827 * wcs const struct wcsprm** 00828 * Pointer to an array of wcsprm structs returned by 00829 * wcsbth(). 00830 * 00831 * type int Select the type of coordinate representation: 00832 * 0: binary table image arrays, 00833 * 1: pixel lists. 00834 * 00835 * Returned: 00836 * alts short[1000][28] 00837 * Index of each alternate coordinate represention in the 00838 * array: alts[col][0] for the primary, alts[col][1] for 00839 * 'A', to alts[col][26] for 'Z', where col is the 00840 * 1-relative column number, and col == 0 is used for 00841 * unattached image headers. Set to -1 if not present. 00842 * 00843 * alts[col][27] counts the number of coordinate 00844 * representations of the chosen type for each column. 00845 * 00846 * For example, if there was no 'P' represention for 00847 * column 13 then 00848 * 00849 = alts[13]['P'-'A'+1] == -1; 00850 * 00851 * Otherwise, the address of its wcsprm struct would be 00852 * 00853 = wcs + alts[13]['P'-'A'+1]; 00854 * 00855 * Function return value: 00856 * int Status return value: 00857 * 0: Success. 00858 * 1: Null wcsprm pointer passed. 00859 * 00860 * 00861 * wcsvfree() - Free the array of wcsprm structs 00862 * --------------------------------------------- 00863 * wcsvfree() frees the memory allocated by wcspih() or wcsbth() for the array 00864 * of wcsprm structs, first invoking wcsfree() on each of the array members. 00865 * 00866 * Given and returned: 00867 * nwcs int* Number of coordinate representations found; set to 0 00868 * on return. 00869 * 00870 * wcs struct wcsprm** 00871 * Pointer to the array of wcsprm structs; set to 0 on 00872 * return. 00873 * 00874 * Function return value: 00875 * int Status return value: 00876 * 0: Success. 00877 * 1: Null wcsprm pointer passed. 00878 * 00879 * 00880 * wcshdo() - Write out a wcsprm struct as a FITS header 00881 * ----------------------------------------------------- 00882 * wcshdo() translates a wcsprm struct into a FITS header. If the colnum 00883 * member of the struct is non-zero then a binary table image array header will 00884 * be produced. Otherwise, if the colax[] member of the struct is set non-zero 00885 * then a pixel list header will be produced. Otherwise, a primary image or 00886 * image extension header will be produced. 00887 * 00888 * If the struct was originally constructed from a header, e.g. by wcspih(), 00889 * the output header will almost certainly differ in a number of respects: 00890 * 00891 * - The output header only contains WCS-related keywords. In particular, it 00892 * does not contain syntactically-required keywords such as SIMPLE, NAXIS, 00893 * BITPIX, or END. 00894 * 00895 * - Deprecated (e.g. CROTAn) or non-standard usage will be translated to 00896 * standard (this is partially dependent on whether wcsfix() was applied). 00897 * 00898 * - Quantities will be converted to the units used internally, basically SI 00899 * with the addition of degrees. 00900 * 00901 * - Floating-point quantities may be given to a different decimal precision. 00902 * 00903 * - Elements of the PCi_ja matrix will be written if and only if they differ 00904 * from the unit matrix. Thus, if the matrix is unity then no elements 00905 * will be written. 00906 * 00907 * - Additional keywords such as WCSAXESa, CUNITia, LONPOLEa and LATPOLEa may 00908 * appear. 00909 * 00910 * - The original keycomments will be lost, although wcshdo() tries hard to 00911 * write meaningful comments. 00912 * 00913 * - Keyword order may be changed. 00914 * 00915 * Keywords can be translated between the image array, binary table, and pixel 00916 * lists forms by manipulating the colnum or colax[] members of the wcsprm 00917 * struct. 00918 * 00919 * Given: 00920 * relax int Degree of permissiveness: 00921 * 0: Recognize only FITS keywords defined by the 00922 * published WCS standard. 00923 * -1: Admit all informal extensions of the WCS 00924 * standard. 00925 * Fine-grained control of the degree of permissiveness 00926 * is also possible as explained in the notes below. 00927 * 00928 * Given and returned: 00929 * wcs struct wcsprm* 00930 * Pointer to a wcsprm struct containing coordinate 00931 * transformation parameters. Will be initialized if 00932 * necessary. 00933 * 00934 * Returned: 00935 * nkeyrec int* Number of FITS header keyrecords returned in the 00936 * "header" array. 00937 * 00938 * header char** Pointer to an array of char holding the header. 00939 * Storage for the array is allocated by wcshdo() in 00940 * blocks of 2880 bytes (32 x 80-character keyrecords) 00941 * and must be free'd by the user to avoid memory leaks. 00942 * 00943 * Each keyrecord is 80 characters long and is *NOT* 00944 * null-terminated, so the first keyrecord starts at 00945 * (*header)[0], the second at (*header)[80], etc. 00946 * 00947 * Function return value: 00948 * int Status return value (associated with wcs_errmsg[]): 00949 * 0: Success. 00950 * 1: Null wcsprm pointer passed. 00951 * 2: Memory allocation failed. 00952 * 3: Linear transformation matrix is singular. 00953 * 4: Inconsistent or unrecognized coordinate axis 00954 * types. 00955 * 5: Invalid parameter value. 00956 * 6: Invalid coordinate transformation parameters. 00957 * 7: Ill-conditioned coordinate transformation 00958 * parameters. 00959 * 00960 * For returns > 1, a detailed error message is set in 00961 * wcsprm::err if enabled, see wcserr_enable(). 00962 * 00963 * Notes: 00964 * wcshdo() interprets the "relax" argument as a vector of flag bits to 00965 * provide fine-grained control over what non-standard WCS keywords to write. 00966 * The flag bits are subject to change in future and should be set by using 00967 * the preprocessor macros (see below) for the purpose. 00968 * 00969 * - WCSHDO_none: Don't use any extensions. 00970 * 00971 * - WCSHDO_all: Write all recognized extensions, equivalent to setting each 00972 * flag bit. 00973 * 00974 * - WCSHDO_safe: Write all extensions that are considered to be safe and 00975 * recommended. 00976 * 00977 * - WCSHDO_DOBSn: Write DOBSn, the column-specific analogue of DATE-OBS for 00978 * use in binary tables and pixel lists. WCS Paper III introduced 00979 * DATE-AVG and DAVGn but by an oversight DOBSn (the obvious analogy) 00980 * was never formally defined by the standard. The alternative to 00981 * using DOBSn is to write DATE-OBS which applies to the whole table. 00982 * This usage is considered to be safe and is recommended. 00983 * 00984 * - WCSHDO_TPCn_ka: WCS Paper I defined 00985 * 00986 * - TPn_ka and TCn_ka for pixel lists 00987 * 00988 * but WCS Paper II uses TPCn_ka in one example and subsequently the 00989 * errata for the WCS papers legitimized the use of 00990 * 00991 * - TPCn_ka and TCDn_ka for pixel lists 00992 * 00993 * provided that the keyword does not exceed eight characters. This 00994 * usage is considered to be safe and is recommended because of the 00995 * non-mnemonic terseness of the shorter forms. 00996 * 00997 * - WCSHDO_PVn_ma: WCS Paper I defined 00998 * 00999 * - iVn_ma and iSn_ma for bintables and 01000 * - TVn_ma and TSn_ma for pixel lists 01001 * 01002 * but WCS Paper II uses iPVn_ma and TPVn_ma in the examples and 01003 * subsequently the errata for the WCS papers legitimized the use of 01004 * 01005 * - iPVn_ma and iPSn_ma for bintables and 01006 * - TPVn_ma and TPSn_ma for pixel lists 01007 * 01008 * provided that the keyword does not exceed eight characters. This 01009 * usage is considered to be safe and is recommended because of the 01010 * non-mnemonic terseness of the shorter forms. 01011 * 01012 * - WCSHDO_CRPXna: For historical reasons WCS Paper I defined 01013 * 01014 * - jCRPXn, iCDLTn, iCUNIn, iCTYPn, and iCRVLn for bintables and 01015 * - TCRPXn, TCDLTn, TCUNIn, TCTYPn, and TCRVLn for pixel lists 01016 * 01017 * for use without an alternate version specifier. However, because 01018 * of the eight-character keyword constraint, in order to accommodate 01019 * column numbers greater than 99 WCS Paper I also defined 01020 * 01021 * - jCRPna, iCDEna, iCUNna, iCTYna and iCRVna for bintables and 01022 * - TCRPna, TCDEna, TCUNna, TCTYna and TCRVna for pixel lists 01023 * 01024 * for use with an alternate version specifier (the "a"). Like the 01025 * PC, CD, PV, and PS keywords there is an obvious tendency to 01026 * confuse these two forms for column numbers up to 99. It is very 01027 * unlikely that any parser would reject keywords in the first set 01028 * with a non-blank alternate version specifier so this usage is 01029 * considered to be safe and is recommended. 01030 * 01031 * - WCSHDO_CNAMna: WCS Papers I and III defined 01032 * 01033 * - iCNAna, iCRDna, and iCSYna for bintables and 01034 * - TCNAna, TCRDna, and TCSYna for pixel lists 01035 * 01036 * By analogy with the above, the long forms would be 01037 * 01038 * - iCNAMna, iCRDEna, and iCSYEna for bintables and 01039 * - TCNAMna, TCRDEna, and TCSYEna for pixel lists 01040 * 01041 * Note that these keywords provide auxiliary information only, none 01042 * of them are needed to compute world coordinates. This usage is 01043 * potentially unsafe and is not recommended at this time. 01044 * 01045 * - WCSHDO_WCSNna: In light of wcsbth() note 4, write WCSNna instead of 01046 * TWCSna for pixel lists. While wcsbth() treats WCSNna and TWCSna 01047 * as equivalent, other parsers may not. Consequently, this usage 01048 * is potentially unsafe and is not recommended at this time. 01049 * 01050 * 01051 * Global variable: const char *wcshdr_errmsg[] - Status return messages 01052 * --------------------------------------------------------------------- 01053 * Error messages to match the status value returned from each function. 01054 * Use wcs_errmsg[] for status returns from wcshdo(). 01055 * 01056 *===========================================================================*/ 01057 01058 #ifndef WCSLIB_WCSHDR 01059 #define WCSLIB_WCSHDR 01060 01061 #include "wcs.h" 01062 01063 #ifdef __cplusplus 01064 extern "C" { 01065 #endif 01066 01067 #define WCSHDR_none 0x00000000 01068 #define WCSHDR_all 0x000FFFFF 01069 #define WCSHDR_reject 0x10000000 01070 01071 #define WCSHDR_CROTAia 0x00000001 01072 #define WCSHDR_EPOCHa 0x00000002 01073 #define WCSHDR_VELREFa 0x00000004 01074 #define WCSHDR_CD00i00j 0x00000008 01075 #define WCSHDR_PC00i00j 0x00000010 01076 #define WCSHDR_PROJPn 0x00000020 01077 #define WCSHDR_RADECSYS 0x00000040 01078 #define WCSHDR_VSOURCE 0x00000080 01079 #define WCSHDR_DOBSn 0x00000100 01080 #define WCSHDR_LONGKEY 0x00000200 01081 #define WCSHDR_CNAMn 0x00000400 01082 #define WCSHDR_AUXIMG 0x00000800 01083 #define WCSHDR_ALLIMG 0x00001000 01084 01085 #define WCSHDR_IMGHEAD 0x00010000 01086 #define WCSHDR_BIMGARR 0x00020000 01087 #define WCSHDR_PIXLIST 0x00040000 01088 01089 #define WCSHDO_none 0x00 01090 #define WCSHDO_all 0xFF 01091 #define WCSHDO_safe 0x0F 01092 #define WCSHDO_DOBSn 0x01 01093 #define WCSHDO_TPCn_ka 0x02 01094 #define WCSHDO_PVn_ma 0x04 01095 #define WCSHDO_CRPXna 0x08 01096 #define WCSHDO_CNAMna 0x10 01097 #define WCSHDO_WCSNna 0x20 01098 01099 01100 extern const char *wcshdr_errmsg[]; 01101 01102 enum wcshdr_errmsg_enum { 01103 WCSHDRERR_SUCCESS = 0, /* Success. */ 01104 WCSHDRERR_NULL_POINTER = 1, /* Null wcsprm pointer passed. */ 01105 WCSHDRERR_MEMORY = 2, /* Memory allocation failed. */ 01106 WCSHDRERR_BAD_COLUMN = 3, /* Invalid column selection. */ 01107 WCSHDRERR_PARSER = 4, /* Fatal error returned by Flex 01108 parser. */ 01109 WCSHDRERR_BAD_TABULAR_PARAMS = 5 /* Invalid tabular parameters. */ 01110 }; 01111 01112 int wcspih(char *header, int nkeyrec, int relax, int ctrl, int *nreject, 01113 int *nwcs, struct wcsprm **wcs); 01114 01115 int wcsbth(char *header, int nkeyrec, int relax, int ctrl, int keysel, 01116 int *colsel, int *nreject, int *nwcs, struct wcsprm **wcs); 01117 01118 int wcstab(struct wcsprm *wcs); 01119 01120 int wcsidx(int nwcs, struct wcsprm **wcs, int alts[27]); 01121 01122 int wcsbdx(int nwcs, struct wcsprm **wcs, int type, short alts[1000][28]); 01123 01124 int wcsvfree(int *nwcs, struct wcsprm **wcs); 01125 01126 int wcshdo(int relax, struct wcsprm *wcs, int *nkeyrec, char **header); 01127 01128 01129 #ifdef __cplusplus 01130 } 01131 #endif 01132 01133 #endif /* WCSLIB_WCSHDR */