- Main Page
- Related Pages
- Data Structures
- Files

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