WCSLIB: getwcstab.h Source File

WCSLIB 7.12

getwcstab.h
Go to the documentation of this file.
1/*============================================================================
2 WCSLIB 7.12 - an implementation of the FITS WCS standard.
3 Copyright (C) 1995-2022, 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.12 2022/09/09 04:57:58 mcalabre Exp $
23*=============================================================================
24*
25* WCSLIB 7.12 - 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
162extern "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
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:167
wtbarr::extlev
int extlev
Definition: getwcstab.h:173
wtbarr::m
int m
Definition: getwcstab.h:169
wtbarr::extver
int extver
Definition: getwcstab.h:172
wtbarr::row
long row
Definition: getwcstab.h:175
wtbarr::arrayp
double ** arrayp
Definition: getwcstab.h:178
wtbarr::i
int i
Definition: getwcstab.h:168
wtbarr::dimlen
int * dimlen
Definition: getwcstab.h:177
wtbarr::ndim
int ndim
Definition: getwcstab.h:176
wtbarr::kind
int kind
Definition: getwcstab.h:170