WCSLIB 4.17: getwcstab.h Source File

- Main Page
- Related Pages
- Data Structures
- Files

# getwcstab.h

Go to the documentation of this file.

    00001 /*============================================================================
    00002
    00003   WCSLIB 4.17 - an implementation of the FITS WCS standard.
    00004   Copyright (C) 1995-2013, 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   Direct correspondence concerning WCSLIB to mark@calabretta.id.au
    00022
    00023   Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
    00024   http://www.atnf.csiro.au/people/Mark.Calabretta
    00025   $Id: getwcstab.h,v 4.17 2013/01/29 05:29:20 cal103 Exp $
    00026 *=============================================================================
    00027 *
    00028 * Summary of the getwcstab routines
    00029 * ---------------------------------
    00030 * fits_read_wcstab(), an implementation of a FITS table reading routine for
    00031 * 'TAB' coordinates, is provided for CFITSIO programmers.  It has been
    00032 * incorporated into CFITSIO as of v3.006 with the definitions in this file,
    00033 * getwcstab.h, moved into fitsio.h.
    00034 *
    00035 * fits_read_wcstab() is not included in the WCSLIB object library but the
    00036 * source code is presented here as it may be useful for programmers using an
    00037 * older version of CFITSIO than 3.006, or as a programming template for
    00038 * non-CFITSIO programmers.
    00039 *
    00040 *
    00041 * fits_read_wcstab() - FITS 'TAB' table reading routine
    00042 * ----------------------------------------------------
    00043 * fits_read_wcstab() extracts arrays from a binary table required in
    00044 * constructing 'TAB' coordinates.
    00045 *
    00046 * Given:
    00047 *   fptr      fitsfile *
    00048 *                       Pointer to the file handle returned, for example, by
    00049 *                       the fits_open_file() routine in CFITSIO.
    00050 *
    00051 *   nwtb      int       Number of arrays to be read from the binary table(s).
    00052 *
    00053 * Given and returned:
    00054 *   wtb       wtbarr *  Address of the first element of an array of wtbarr
    00055 *                       typedefs.  This wtbarr typedef is defined to match the
    00056 *                       wtbarr struct defined in WCSLIB.  An array of such
    00057 *                       structs returned by the WCSLIB function wcstab() as
    00058 *                       discussed in the notes below.
    00059 *
    00060 * Returned:
    00061 *   status    int *     CFITSIO status value.
    00062 *
    00063 * Function return value:
    00064 *             int       CFITSIO status value.
    00065 *
    00066 * Notes:
    00067 *   In order to maintain WCSLIB and CFITSIO as independent libraries it is not
    00068 *   permissible for any CFITSIO library code to include WCSLIB header files,
    00069 *   or vice versa.  However, the CFITSIO function fits_read_wcstab() accepts
    00070 *   an array of wtbarr structs defined in wcs.h within WCSLIB.
    00071 *
    00072 *   The problem therefore is to define the wtbarr struct within fitsio.h
    00073 *   without including wcs.h, especially noting that wcs.h will often (but not
    00074 *   always) be included together with fitsio.h in an applications program that
    00075 *   uses fits_read_wcstab().
    00076 *
    00077 *   The solution adopted is for WCSLIB to define "struct wtbarr" while
    00078 *   fitsio.h defines "typedef wtbarr" as an untagged struct with identical
    00079 *   members.  This allows both wcs.h and fitsio.h to define a wtbarr data type
    00080 *   without conflict by virtue of the fact that structure tags and typedef
    00081 *   names share different name spaces in C; Appendix A, Sect. A11.1 (p227) of
    00082 *   the K&R ANSI edition states that:
    00083 *
    00084 *     Identifiers fall into several name spaces that do not interfere with one
    00085 *     another; the same identifier may be used for different purposes, even in
    00086 *     the same scope, if the uses are in different name spaces.  These classes
    00087 *     are: objects, functions, typedef names, and enum constants; labels; tags
    00088 *     of structures, unions, and enumerations; and members of each structure
    00089 *     or union individually.
    00090 *
    00091 *   Therefore, declarations within WCSLIB look like
    00092 *
    00093 =     struct wtbarr *w;
    00094 *
    00095 *   while within CFITSIO they are simply
    00096 *
    00097 =     wtbarr *w;
    00098 *
    00099 *   As suggested by the commonality of the names, these are really the same
    00100 *   aggregate data type.  However, in passing a (struct wtbarr *) to
    00101 *   fits_read_wcstab() a cast to (wtbarr *) is formally required.
    00102 *
    00103 *   When using WCSLIB and CFITSIO together in C++ the situation is complicated
    00104 *   by the fact that typedefs and structs share the same namespace; C++
    00105 *   Annotated Reference Manual, Sect. 7.1.3 (p105).  In that case the wtbarr
    00106 *   struct in wcs.h is renamed by preprocessor macro substitution to wtbarr_s
    00107 *   to distinguish it from the typedef defined in fitsio.h.  However, the
    00108 *   scope of this macro substitution is limited to wcs.h itself and CFITSIO
    00109 *   programmer code, whether in C++ or C, should always use the wtbarr
    00110 *   typedef.
    00111 *
    00112 *
    00113 * wtbarr typedef
    00114 * --------------
    00115 * The wtbarr typedef is defined as a struct containing the following members:
    00116 *
    00117 *   int i
    00118 *     Image axis number.
    00119 *
    00120 *   int m
    00121 *     Array axis number for index vectors.
    00122 *
    00123 *   int kind
    00124 *     Character identifying the array type:
    00125 *       - c: coordinate array,
    00126 *       - i: index vector.
    00127 *
    00128 *   char extnam[72]
    00129 *     EXTNAME identifying the binary table extension.
    00130 *
    00131 *   int extver
    00132 *     EXTVER identifying the binary table extension.
    00133 *
    00134 *   int extlev
    00135 *     EXTLEV identifying the binary table extension.
    00136 *
    00137 *   char ttype[72]
    00138 *     TTYPEn identifying the column of the binary table that contains the
    00139 *     array.
    00140 *
    00141 *   long row
    00142 *     Table row number.
    00143 *
    00144 *   int ndim
    00145 *     Expected dimensionality of the array.
    00146 *
    00147 *   int *dimlen
    00148 *     Address of the first element of an array of int of length ndim into
    00149 *     which the array axis lengths are to be written.
    00150 *
    00151 *   double **arrayp
    00152 *     Pointer to an array of double which is to be allocated by the user
    00153 *     and into which the array is to be written.
    00154 *
    00155 *===========================================================================*/
    00156
    00157 #ifndef WCSLIB_GETWCSTAB
    00158 #define WCSLIB_GETWCSTAB
    00159
    00160 #ifdef __cplusplus
    00161 extern "C" {
    00162 #endif
    00163
    00164 #include <fitsio.h>
    00165
    00166 typedef struct {
    00167   int  i;                       /* Image axis number.                       */
    00168   int  m;                       /* Array axis number for index vectors.     */
    00169   int  kind;                    /* Array type, 'c' (coord) or 'i' (index).  */
    00170   char extnam[72];              /* EXTNAME of binary table extension.       */
    00171   int  extver;                  /* EXTVER  of binary table extension.       */
    00172   int  extlev;                  /* EXTLEV  of binary table extension.       */
    00173   char ttype[72];               /* TTYPEn of column containing the array.   */
    00174   long row;                     /* Table row number.                        */
    00175   int  ndim;                    /* Expected array dimensionality.           */
    00176   int  *dimlen;                 /* Where to write the array axis lengths.   */
    00177   double **arrayp;              /* Where to write the address of the array  */
    00178                                 /* allocated to store the array.            */
    00179 } wtbarr;
    00180
    00181
    00182 int fits_read_wcstab(fitsfile *fptr, int nwtb, wtbarr *wtb, int *status);
    00183
    00184
    00185 #ifdef __cplusplus
    00186 }
    00187 #endif
    00188
    00189 #endif /* WCSLIB_GETWCSTAB */