getwcstab.h
Go to the documentation of this file.
/*============================================================================
WCSLIB 5.17 - an implementation of the FITS WCS standard.
Copyright (C) 1995-2017, 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.17 2017/09/18 08:44:23 mcalabre Exp $
*=============================================================================
*
* WCSLIB 5.17 - 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 */
wtbarr::kind
int kind
Definition: getwcstab.h:173
wtbarr::i
int i
Definition: getwcstab.h:171
wtbarr::m
int m
Definition: getwcstab.h:172
wtbarr::row
long row
Definition: getwcstab.h:178
wtbarr::arrayp
double ** arrayp
Definition: getwcstab.h:181
fits_read_wcstab
int fits_read_wcstab(fitsfile *fptr, int nwtb, wtbarr *wtb, int *status)
FITS &#39;TAB&#39; table reading routine.
wtbarr
Extraction of coordinate lookup tables from BINTABLE.
Definition: getwcstab.h:170
wtbarr::ndim
int ndim
Definition: getwcstab.h:179
wtbarr::extver
int extver
Definition: getwcstab.h:175
wtbarr::dimlen
int * dimlen
Definition: getwcstab.h:180
wtbarr::extlev
int extlev
Definition: getwcstab.h:176