00001 /*============================================================================ 00002 00003 WCSLIB 4.15 - an implementation of the FITS WCS standard. 00004 Copyright (C) 1995-2012, Mark Calabretta 00005 00006 This file is part of WCSLIB. 00007 00008 WCSLIB is free software: you can redistribute it and/or modify it under the 00009 terms of the GNU Lesser General Public License as published by the Free 00010 Software Foundation, either version 3 of the License, or (at your option) 00011 any later version. 00012 00013 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY 00014 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00015 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for 00016 more details. 00017 00018 You should have received a copy of the GNU Lesser General Public License 00019 along with WCSLIB. If not, see http://www.gnu.org/licenses. 00020 00021 Direct correspondence concerning WCSLIB to mark@calabretta.id.au 00022 00023 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO. 00024 http://www.atnf.csiro.au/people/Mark.Calabretta 00025 $Id: getwcstab.h,v 4.15 2012/09/26 14:26:05 cal103 Exp $ 00026 *============================================================================= 00027 * 00028 * Summary of the getwcstab routines 00029 * --------------------------------- 00030 * fits_read_wcstab(), an implementation of a FITS table reading routine for 00031 * 'TAB' coordinates, is provided for CFITSIO programmers. It has been 00032 * incorporated into CFITSIO as of v3.006 with the definitions in this file, 00033 * getwcstab.h, moved into fitsio.h. 00034 * 00035 * fits_read_wcstab() is not included in the WCSLIB object library but the 00036 * source code is presented here as it may be useful for programmers using an 00037 * older version of CFITSIO than 3.006, or as a programming template for 00038 * non-CFITSIO programmers. 00039 * 00040 * 00041 * fits_read_wcstab() - FITS 'TAB' table reading routine 00042 * ---------------------------------------------------- 00043 * fits_read_wcstab() extracts arrays from a binary table required in 00044 * constructing 'TAB' coordinates. 00045 * 00046 * Given: 00047 * fptr fitsfile * 00048 * Pointer to the file handle returned, for example, by 00049 * the fits_open_file() routine in CFITSIO. 00050 * 00051 * nwtb int Number of arrays to be read from the binary table(s). 00052 * 00053 * Given and returned: 00054 * wtb wtbarr * Address of the first element of an array of wtbarr 00055 * typedefs. This wtbarr typedef is defined to match the 00056 * wtbarr struct defined in WCSLIB. An array of such 00057 * structs returned by the WCSLIB function wcstab() as 00058 * discussed in the notes below. 00059 * 00060 * Returned: 00061 * status int * CFITSIO status value. 00062 * 00063 * Function return value: 00064 * int CFITSIO status value. 00065 * 00066 * Notes: 00067 * In order to maintain WCSLIB and CFITSIO as independent libraries it is not 00068 * permissible for any CFITSIO library code to include WCSLIB header files, 00069 * or vice versa. However, the CFITSIO function fits_read_wcstab() accepts 00070 * an array of wtbarr structs defined in wcs.h within WCSLIB. 00071 * 00072 * The problem therefore is to define the wtbarr struct within fitsio.h 00073 * without including wcs.h, especially noting that wcs.h will often (but not 00074 * always) be included together with fitsio.h in an applications program that 00075 * uses fits_read_wcstab(). 00076 * 00077 * The solution adopted is for WCSLIB to define "struct wtbarr" while 00078 * fitsio.h defines "typedef wtbarr" as an untagged struct with identical 00079 * members. This allows both wcs.h and fitsio.h to define a wtbarr data type 00080 * without conflict by virtue of the fact that structure tags and typedef 00081 * names share different name spaces in C; Appendix A, Sect. A11.1 (p227) of 00082 * the K&R ANSI edition states that: 00083 * 00084 * Identifiers fall into several name spaces that do not interfere with one 00085 * another; the same identifier may be used for different purposes, even in 00086 * the same scope, if the uses are in different name spaces. These classes 00087 * are: objects, functions, typedef names, and enum constants; labels; tags 00088 * of structures, unions, and enumerations; and members of each structure 00089 * or union individually. 00090 * 00091 * Therefore, declarations within WCSLIB look like 00092 * 00093 = struct wtbarr *w; 00094 * 00095 * while within CFITSIO they are simply 00096 * 00097 = wtbarr *w; 00098 * 00099 * As suggested by the commonality of the names, these are really the same 00100 * aggregate data type. However, in passing a (struct wtbarr *) to 00101 * fits_read_wcstab() a cast to (wtbarr *) is formally required. 00102 * 00103 * When using WCSLIB and CFITSIO together in C++ the situation is complicated 00104 * by the fact that typedefs and structs share the same namespace; C++ 00105 * Annotated Reference Manual, Sect. 7.1.3 (p105). In that case the wtbarr 00106 * struct in wcs.h is renamed by preprocessor macro substitution to wtbarr_s 00107 * to distinguish it from the typedef defined in fitsio.h. However, the 00108 * scope of this macro substitution is limited to wcs.h itself and CFITSIO 00109 * programmer code, whether in C++ or C, should always use the wtbarr 00110 * typedef. 00111 * 00112 * 00113 * wtbarr typedef 00114 * -------------- 00115 * The wtbarr typedef is defined as a struct containing the following members: 00116 * 00117 * int i 00118 * Image axis number. 00119 * 00120 * int m 00121 * Array axis number for index vectors. 00122 * 00123 * int kind 00124 * Character identifying the array type: 00125 * - c: coordinate array, 00126 * - i: index vector. 00127 * 00128 * char extnam[72] 00129 * EXTNAME identifying the binary table extension. 00130 * 00131 * int extver 00132 * EXTVER identifying the binary table extension. 00133 * 00134 * int extlev 00135 * EXTLEV identifying the binary table extension. 00136 * 00137 * char ttype[72] 00138 * TTYPEn identifying the column of the binary table that contains the 00139 * array. 00140 * 00141 * long row 00142 * Table row number. 00143 * 00144 * int ndim 00145 * Expected dimensionality of the array. 00146 * 00147 * int *dimlen 00148 * Address of the first element of an array of int of length ndim into 00149 * which the array axis lengths are to be written. 00150 * 00151 * double **arrayp 00152 * Pointer to an array of double which is to be allocated by the user 00153 * and into which the array is to be written. 00154 * 00155 *===========================================================================*/ 00156 00157 #ifndef WCSLIB_GETWCSTAB 00158 #define WCSLIB_GETWCSTAB 00159 00160 #ifdef __cplusplus 00161 extern "C" { 00162 #endif 00163 00164 #include <fitsio.h> 00165 00166 typedef struct { 00167 int i; /* Image axis number. */ 00168 int m; /* Array axis number for index vectors. */ 00169 int kind; /* Array type, 'c' (coord) or 'i' (index). */ 00170 char extnam[72]; /* EXTNAME of binary table extension. */ 00171 int extver; /* EXTVER of binary table extension. */ 00172 int extlev; /* EXTLEV of binary table extension. */ 00173 char ttype[72]; /* TTYPEn of column containing the array. */ 00174 long row; /* Table row number. */ 00175 int ndim; /* Expected array dimensionality. */ 00176 int *dimlen; /* Where to write the array axis lengths. */ 00177 double **arrayp; /* Where to write the address of the array */ 00178 /* allocated to store the array. */ 00179 } wtbarr; 00180 00181 00182 int fits_read_wcstab(fitsfile *fptr, int nwtb, wtbarr *wtb, int *status); 00183 00184 00185 #ifdef __cplusplus 00186 } 00187 #endif 00188 00189 #endif /* WCSLIB_GETWCSTAB */