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