1/*============================================================================
2
3 WCSLIB 4.23 - an implementation of the FITS WCS standard.
4 Copyright (C) 1995-2014, Mark Calabretta
5
6 This file is part of WCSLIB.
7
8 WCSLIB is free software: you can redistribute it and/or modify it under the
9 terms of the GNU Lesser General Public License as published by the Free
10 Software Foundation, either version 3 of the License, or (at your option)
11 any later version.
12
13 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
14 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
16 more details.
17
18 You should have received a copy of the GNU Lesser General Public License
19 along with WCSLIB. If not, see http://www.gnu.org/licenses.
20
21 Direct correspondence concerning WCSLIB to mark@calabretta.id.au
22
23 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
24 http://www.atnf.csiro.au/people/Mark.Calabretta
25 $Id: getwcstab.h,v 4.23 2014/05/13 05:50:51 mcalabre Exp $
26*=============================================================================
27*
28* Summary of the getwcstab routines
29* ---------------------------------
30* fits_read_wcstab(), an implementation of a FITS table reading routine for
31* 'TAB' coordinates, is provided for CFITSIO programmers. It has been
32* incorporated into CFITSIO as of v3.006 with the definitions in this file,
33* getwcstab.h, moved into fitsio.h.
34*
35* fits_read_wcstab() is not included in the WCSLIB object library but the
36* source code is presented here as it may be useful for programmers using an
37* older version of CFITSIO than 3.006, or as a programming template for
38* non-CFITSIO programmers.
39*
40*
41* fits_read_wcstab() - FITS 'TAB' table reading routine
42* ----------------------------------------------------
43* fits_read_wcstab() extracts arrays from a binary table required in
44* constructing 'TAB' coordinates.
45*
46* Given:
47* fptr fitsfile *
48* Pointer to the file handle returned, for example, by
49* the fits_open_file() routine in CFITSIO.
50*
51* nwtb int Number of arrays to be read from the binary table(s).
52*
53* Given and returned:
54* wtb wtbarr * Address of the first element of an array of wtbarr
55* typedefs. This wtbarr typedef is defined to match the
56* wtbarr struct defined in WCSLIB. An array of such
57* structs returned by the WCSLIB function wcstab() as
58* discussed in the notes below.
59*
60* Returned:
61* status int * CFITSIO status value.
62*
63* Function return value:
64* int CFITSIO status value.
65*
66* Notes:
67* In order to maintain WCSLIB and CFITSIO as independent libraries it is not
68* permissible for any CFITSIO library code to include WCSLIB header files,
69* or vice versa. However, the CFITSIO function fits_read_wcstab() accepts
70* an array of wtbarr structs defined in wcs.h within WCSLIB.
71*
72* The problem therefore is to define the wtbarr struct within fitsio.h
73* without including wcs.h, especially noting that wcs.h will often (but not
74* always) be included together with fitsio.h in an applications program that
75* uses fits_read_wcstab().
76*
77* The solution adopted is for WCSLIB to define "struct wtbarr" while
78* fitsio.h defines "typedef wtbarr" as an untagged struct with identical
79* members. This allows both wcs.h and fitsio.h to define a wtbarr data type
80* without conflict by virtue of the fact that structure tags and typedef
81* names share different name spaces in C; Appendix A, Sect. A11.1 (p227) of
82* the K&R ANSI edition states that:
83*
84* Identifiers fall into several name spaces that do not interfere with one
85* another; the same identifier may be used for different purposes, even in
86* the same scope, if the uses are in different name spaces. These classes
87* are: objects, functions, typedef names, and enum constants; labels; tags
88* of structures, unions, and enumerations; and members of each structure
89* or union individually.
90*
91* Therefore, declarations within WCSLIB look like
92*
93= struct wtbarr *w;
94*
95* while within CFITSIO they are simply
96*
97= wtbarr *w;
98*
99* As suggested by the commonality of the names, these are really the same
100* aggregate data type. However, in passing a (struct wtbarr *) to
101* fits_read_wcstab() a cast to (wtbarr *) is formally required.
102*
103* When using WCSLIB and CFITSIO together in C++ the situation is complicated
104* by the fact that typedefs and structs share the same namespace; C++
105* Annotated Reference Manual, Sect. 7.1.3 (p105). In that case the wtbarr
106* struct in wcs.h is renamed by preprocessor macro substitution to wtbarr_s
107* to distinguish it from the typedef defined in fitsio.h. However, the
108* scope of this macro substitution is limited to wcs.h itself and CFITSIO
109* programmer code, whether in C++ or C, should always use the wtbarr
110* typedef.
111*
112*
113* wtbarr typedef
114* --------------
115* The wtbarr typedef is defined as a struct containing the following members:
116*
117* int i
118* Image axis number.
119*
120* int m
121* Array axis number for index vectors.
122*
123* int kind
124* Character identifying the array type:
125* - c: coordinate array,
126* - i: index vector.
127*
128* char extnam[72]
129* EXTNAME identifying the binary table extension.
130*
131* int extver
132* EXTVER identifying the binary table extension.
133*
134* int extlev
135* EXTLEV identifying the binary table extension.
136*
137* char ttype[72]
138* TTYPEn identifying the column of the binary table that contains the
139* array.
140*
141* long row
142* Table row number.
143*
144* int ndim
145* Expected dimensionality of the array.
146*
147* int *dimlen
148* Address of the first element of an array of int of length ndim into
149* which the array axis lengths are to be written.
150*
151* double **arrayp
152* Pointer to an array of double which is to be allocated by the user
153* and into which the array is to be written.
154*
155*===========================================================================*/
156
157#ifndef WCSLIB_GETWCSTAB
158#define WCSLIB_GETWCSTAB
159
160#ifdef __cplusplus
161extern "C" {
162#endif
163
164#include <fitsio.h>
165
166typedef struct {
167 int i; /* Image axis number. */
168 int m; /* Array axis number for index vectors. */
169 int kind; /* Array type, 'c' (coord) or 'i' (index). */
170 char extnam[72]; /* EXTNAME of binary table extension. */
171 int extver; /* EXTVER of binary table extension. */
172 int extlev; /* EXTLEV of binary table extension. */
173 char ttype[72]; /* TTYPEn of column containing the array. */
174 long row; /* Table row number. */
175 int ndim; /* Expected array dimensionality. */
176 int *dimlen; /* Where to write the array axis lengths. */
177 double **arrayp; /* Where to write the address of the array */
178 /* allocated to store the array. */
179} wtbarr;
180
181
182int fits_read_wcstab(fitsfile *fptr, int nwtb, wtbarr *wtb, int *status);
183
184
185#ifdef __cplusplus
186}
187#endif
188
189#endif /* WCSLIB_GETWCSTAB */
190