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