getwcstab.h

Go to the documentation of this file.

/*============================================================================
  WCSLIB 8.4 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2024, 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.
 
  Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
  http://www.atnf.csiro.au/people/Mark.Calabretta
  $Id: getwcstab.h,v 8.4 2024/10/28 13:56:16 mcalabre Exp $
*=============================================================================
*
* WCSLIB 8.4 - 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:
*   1: 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