WCSLIB: getwcstab.h Source File

WCSLIB 4.25.1

- Main Page
- Related Pages
- Data Structures
- Files

- File List
- Globals

getwcstab.h
Go to the documentation of this file.
1 /*============================================================================
2
3 WCSLIB 4.25 - an implementation of the FITS WCS standard.
4 Copyright (C) 1995-2015, 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.25.1.2 2015/01/06 01:01:06 mcalabre Exp mcalabre $
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 */
wtbarr::kind
int kind
Definition: getwcstab.h:169
wtbarr::i
int i
Definition: getwcstab.h:167
wtbarr::m
int m
Definition: getwcstab.h:168
wtbarr::row
long row
Definition: getwcstab.h:174
wtbarr::arrayp
double ** arrayp
Definition: getwcstab.h:177
fits_read_wcstab
int fits_read_wcstab(fitsfile *fptr, int nwtb, wtbarr *wtb, int *status)
FITS 'TAB' table reading routine.
wtbarr
Extraction of coordinate lookup tables from BINTABLE.
Definition: getwcstab.h:166
wtbarr::ndim
int ndim
Definition: getwcstab.h:175
wtbarr::extver
int extver
Definition: getwcstab.h:171
wtbarr::dimlen
int * dimlen
Definition: getwcstab.h:176
wtbarr::extlev
int extlev
Definition: getwcstab.h:172