1 /*============================================================================ 2 WCSLIB 7.7 - an implementation of the FITS WCS standard. 3 Copyright (C) 1995-2021, 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 7.7 2021/07/12 06:36:49 mcalabre Exp $ 23 *============================================================================= 24 * 25 * WCSLIB 7.7 - 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 a primary image header. 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 1282 extern "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 1332 extern const char *wcshdr_errmsg[]; 1333 1334 enum 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 1344 int wcspih(char *header, int nkeyrec, int relax, int ctrl, int *nreject, 1345 int *nwcs, struct wcsprm **wcs); 1346 1347 int wcsbth(char *header, int nkeyrec, int relax, int ctrl, int keysel, 1348 int *colsel, int *nreject, int *nwcs, struct wcsprm **wcs); 1349 1350 int wcstab(struct wcsprm *wcs); 1351 1352 int wcsidx(int nwcs, struct wcsprm **wcs, int alts[27]); 1353 1354 int wcsbdx(int nwcs, struct wcsprm **wcs, int type, short alts[1000][28]); 1355 1356 int wcsvfree(int *nwcs, struct wcsprm **wcs); 1357 1358 int wcshdo(int ctrl, struct wcsprm *wcs, int *nkeyrec, char **header); 1359 1360 1361 #ifdef __cplusplus 1362 } 1363 #endif 1364 1365 #endif // WCSLIB_WCSHDR 1366