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