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 |
161 | extern "C" { |
162 | #endif |
163 | |
164 | #include <fitsio.h> |
165 | |
166 | typedef 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 | |
182 | int 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 | |