wcslib (8.2.2)
1 /*============================================================================
2 WCSLIB 8.2 - an implementation of the FITS WCS standard.
3 Copyright (C) 1995-2023, 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 8.2.1.1 2023/11/16 10:05:57 mcalabre Exp mcalabre $
23 *=============================================================================
24 *
25 * WCSLIB 8.2 - 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
Browse
Usage
Versions