- Main Page
- Related Pages
- Data Structures
- Files

# wcshdr.h

Go to the documentation of this file.

    00001 /*============================================================================
    00002
    00003   WCSLIB 4.13 - an implementation of the FITS WCS standard.
    00004   Copyright (C) 1995-2012, 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.13.1.1 2012/03/14 07:40:37 cal103 Exp cal103 $
    00032 *=============================================================================
    00033 *
    00034 * WCSLIB 4.13 - 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 */