getwcstab.h

Go to the documentation of this file.

/*============================================================================

  WCSLIB 5.15 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2016, Mark Calabretta

  This file is part of WCSLIB.

  WCSLIB is free software: you can redistribute it and/or modify it under the
  terms of the GNU Lesser General Public License as published by the Free
  Software Foundation, either version 3 of the License, or (at your option)
  any later version.

  WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
  more details.

  You should have received a copy of the GNU Lesser General Public License
  along with WCSLIB.  If not, see http://www.gnu.org/licenses.

  Direct correspondence concerning WCSLIB to mark@calabretta.id.au

  Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
  http://www.atnf.csiro.au/people/Mark.Calabretta
  $Id: getwcstab.h,v 5.15 2016/04/05 12:55:10 mcalabre Exp $
*=============================================================================
*
* WCSLIB 5.15 - C routines that implement the FITS World Coordinate System
* (WCS) standard.  Refer to the README file provided with WCSLIB for an
* overview of the library.
*
* Summary of the getwcstab routines
* ---------------------------------
* fits_read_wcstab(), an implementation of a FITS table reading routine for
* 'TAB' coordinates, is provided for CFITSIO programmers.  It has been
* incorporated into CFITSIO as of v3.006 with the definitions in this file,
* getwcstab.h, moved into fitsio.h.
*
* fits_read_wcstab() is not included in the WCSLIB object library but the
* source code is presented here as it may be useful for programmers using an
* older version of CFITSIO than 3.006, or as a programming template for
* non-CFITSIO programmers.
*
*
* fits_read_wcstab() - FITS 'TAB' table reading routine
* ----------------------------------------------------
* fits_read_wcstab() extracts arrays from a binary table required in
* constructing 'TAB' coordinates.
*
* Given:
*   fptr      fitsfile *
*                       Pointer to the file handle returned, for example, by
*                       the fits_open_file() routine in CFITSIO.
*
*   nwtb      int       Number of arrays to be read from the binary table(s).
*
* Given and returned:
*   wtb       wtbarr *  Address of the first element of an array of wtbarr
*                       typedefs.  This wtbarr typedef is defined to match the
*                       wtbarr struct defined in WCSLIB.  An array of such
*                       structs returned by the WCSLIB function wcstab() as
*                       discussed in the notes below.
*
* Returned:
*   status    int *     CFITSIO status value.
*
* Function return value:
*             int       CFITSIO status value.
*
* Notes:
*   In order to maintain WCSLIB and CFITSIO as independent libraries it is not
*   permissible for any CFITSIO library code to include WCSLIB header files,
*   or vice versa.  However, the CFITSIO function fits_read_wcstab() accepts
*   an array of wtbarr structs defined in wcs.h within WCSLIB.
*
*   The problem therefore is to define the wtbarr struct within fitsio.h
*   without including wcs.h, especially noting that wcs.h will often (but not
*   always) be included together with fitsio.h in an applications program that
*   uses fits_read_wcstab().
*
*   The solution adopted is for WCSLIB to define "struct wtbarr" while
*   fitsio.h defines "typedef wtbarr" as an untagged struct with identical
*   members.  This allows both wcs.h and fitsio.h to define a wtbarr data type
*   without conflict by virtue of the fact that structure tags and typedef
*   names share different name spaces in C; Appendix A, Sect. A11.1 (p227) of
*   the K&R ANSI edition states that:
*
*     Identifiers fall into several name spaces that do not interfere with one
*     another; the same identifier may be used for different purposes, even in
*     the same scope, if the uses are in different name spaces.  These classes
*     are: objects, functions, typedef names, and enum constants; labels; tags
*     of structures, unions, and enumerations; and members of each structure
*     or union individually.
*
*   Therefore, declarations within WCSLIB look like
*
=     struct wtbarr *w;
*
*   while within CFITSIO they are simply
*
=     wtbarr *w;
*
*   As suggested by the commonality of the names, these are really the same
*   aggregate data type.  However, in passing a (struct wtbarr *) to
*   fits_read_wcstab() a cast to (wtbarr *) is formally required.
*
*   When using WCSLIB and CFITSIO together in C++ the situation is complicated
*   by the fact that typedefs and structs share the same namespace; C++
*   Annotated Reference Manual, Sect. 7.1.3 (p105).  In that case the wtbarr
*   struct in wcs.h is renamed by preprocessor macro substitution to wtbarr_s
*   to distinguish it from the typedef defined in fitsio.h.  However, the
*   scope of this macro substitution is limited to wcs.h itself and CFITSIO
*   programmer code, whether in C++ or C, should always use the wtbarr
*   typedef.
*
*
* wtbarr typedef
* --------------
* The wtbarr typedef is defined as a struct containing the following members:
*
*   int i
*     Image axis number.
*
*   int m
*     Array axis number for index vectors.
*
*   int kind
*     Character identifying the array type:
*       - c: coordinate array,
*       - i: index vector.
*
*   char extnam[72]
*     EXTNAME identifying the binary table extension.
*
*   int extver
*     EXTVER identifying the binary table extension.
*
*   int extlev
*     EXTLEV identifying the binary table extension.
*
*   char ttype[72]
*     TTYPEn identifying the column of the binary table that contains the
*     array.
*
*   long row
*     Table row number.
*
*   int ndim
*     Expected dimensionality of the array.
*
*   int *dimlen
*     Address of the first element of an array of int of length ndim into
*     which the array axis lengths are to be written.
*
*   double **arrayp
*     Pointer to an array of double which is to be allocated by the user
*     and into which the array is to be written.
*
*===========================================================================*/

#ifndef WCSLIB_GETWCSTAB
#define WCSLIB_GETWCSTAB

#ifdef __cplusplus
extern "C" {
#endif

#include <fitsio.h>

typedef struct {
  int  i;                       /* Image axis number.                       */
  int  m;                       /* Array axis number for index vectors.     */
  int  kind;                    /* Array type, 'c' (coord) or 'i' (index).  */
  char extnam[72];              /* EXTNAME of binary table extension.       */
  int  extver;                  /* EXTVER  of binary table extension.       */
  int  extlev;                  /* EXTLEV  of binary table extension.       */
  char ttype[72];               /* TTYPEn of column containing the array.   */
  long row;                     /* Table row number.                        */
  int  ndim;                    /* Expected array dimensionality.           */
  int  *dimlen;                 /* Where to write the array axis lengths.   */
  double **arrayp;              /* Where to write the address of the array  */
                                /* allocated to store the array.            */
} wtbarr;


int fits_read_wcstab(fitsfile *fptr, int nwtb, wtbarr *wtb, int *status);


#ifdef __cplusplus
}
#endif

#endif /* WCSLIB_GETWCSTAB */