1funinfoget(3) SAORD Documentation funinfoget(3)
2
6 FunInfoGet - get information from Funtools struct
7
9 #include <funtools.h>
10 int FunInfoGet(Fun fun, int type, char *addr, ...)
12
14 The FunInfoGet() routine returns information culled from the Funtools
15 structure. The first argument is the Fun handle from which information
16 is to be retrieved. This first required argument is followed by a
17 variable length list of pairs of arguments. Each pair consists of an
18 integer representing the type of information to retrieve and the
19 address where the information is to be stored. The list is terminated
20 by a 0. The routine returns the number of get actions performed.
21 The full list of available information is described below. Please note
23 that only a few of these will be useful to most application developers.
24 For imaging applications, the most important types are:
25 FUN_SECT_DIM1 int /* dim1 for section */
27 FUN_SECT_DIM2 int /* dim2 for section */
28 FUN_SECT_BITPIX int /* bitpix for section */
29 These would be used to determine the dimensions and data type of image
31 data retrieved using the FunImageGet() routine. For example:
32 /* extract and bin the data section into an image buffer */
34 buf = FunImageGet(fun, NULL, NULL);
35 /* get required information from funtools structure.
36 this should come after the FunImageGet() call, in case the call
37 changed sect_bitpix */
38 FunInfoGet(fun,
39 FUN_SECT_BITPIX, &bitpix,
40 FUN_SECT_DIM1, &dim1,
41 FUN_SECT_DIM2, &dim2,
42 0);
43 /* loop through pixels and reset values below limit to value */
44 for(i=0; i<dim1*dim2; i++){
45 switch(bitpix){
46 case 8:
47 if( cbuf[i] <= blimit ) cbuf[i] = bvalue;
48 ...
49 }
50 It is important to bear in mind that the call to FunImageGet() can
52 change the value of FUN_SECT_BITPIX (e.g. if "bitpix=n" is passed in
53 the param list). Therefore, a call to FunInfoGet() should be made
54 after the call to FunImageGet(), in order to retrieve the updated bit‐
55 pix value. See the imblank example code for more details.
56 It also can be useful to retrieve the World Coordinate System informa‐
58 tion from the Funtools structure. Funtools uses the the WCS Library
59 developed by Doug Mink at SAO, which is available here. (More informa‐
60 tion about the WCSTools project in general can be found here.) The
61 FunOpen() routine initializes two WCS structures that can be used with
62 this WCS Library. Applications can retrieve either of these two WCS
63 structures using FunInfoGet():
64 FUN_WCS struct WorldCoor * /* wcs structure, for image coordinates*/
66 FUN_WCS0 struct WorldCoor * /* wcs structure, for physical coordinates */
67 The structure retrieved by FUN_WCS is a WCS library handle containing
69 parameters suitable for use with image coordinates, regardless of
70 whether the data are images or tables. For this structure, the WCS ref‐
71 erence point (CRPIX) has been converted to image coordinates if the
72 underlying file is a table (and therefore in physical coordinates). You
73 therefore must ensure that the positions being passed to a routine like
74 pix2wcs are in image coordinates. The FUN_WCS0 structure has not had
75 its WCS reference point converted to image coordinates. It therefore is
76 useful when passing processing physical coordinates from a table.
77 Once a WCS structure has been retrieved, it can be used as the first
79 argument to the WCS library routines. (If the structure is NULL, no WCS
80 information was contained in the file.) The two important WCS routines
81 that Funtools uses are:
82 #include <wcs.h>
84 void pix2wcs (wcs,xpix,ypix,xpos,ypos)
85 struct WorldCoor *wcs; /* World coordinate system structure */
86 double xpix,ypix; /* x and y coordinates in pixels */
87 double *xpos,*ypos; /* RA and Dec in degrees (returned) */
88 which converts pixel coordinates to sky coordinates, and:
90 void wcs2pix (wcs, xpos, ypos, xpix, ypix, offscl)
92 struct WorldCoor *wcs; /* World coordinate system structure */
93 double xpos,ypos; /* World coordinates in degrees */
94 double *xpix,*ypix; /* coordinates in pixels */
95 int *offscl; /* 0 if within bounds, else off scale */
96 which converts sky coordinates to pixel coordinates. Again, please note
98 that the wcs structure returned by FUN_WCS assumes that image coordi‐
99 nates are passed to the pix2wcs routine, while FUN_WCS0 assumes that
100 physical coordinates are passed.
101 Note that funtools.h file automatically includes wcs.h. An example
103 program that utilizes these WCS structure to call WCS Library routines
104 is twcs.c.
105 The following is the complete list of information that can be returned:
107 name type comment
109 --------- -------- ---------------------------------------------
110 FUN_FNAME char * /* file name */
111 FUN_GIO GIO /* gio handle */
112 FUN_HEADER FITSHead /* fitsy header struct */
113 FUN_TYPE int /* TY_TABLE,TY_IMAGE,TY_EVENTS,TY_ARRAY */
114 FUN_BITPIX int /* bits/pixel in file */
115 FUN_MIN1 int /* tlmin of axis1 -- tables */
116 FUN_MAX1 int /* tlmax of axis1 -- tables */
117 FUN_MIN2 int /* tlmin of axis2 -- tables */
118 FUN_MAX2 int /* tlmax of axis2 -- tables */
119 FUN_DIM1 int /* dimension of axis1 */
120 FUN_DIM2 int /* dimension of axis2 */
121 FUN_ENDIAN int /* 0=little, 1=big endian */
122 FUN_FILTER char * /* supplied filter */
123 FUN_IFUN FITSHead /* pointer to reference header */
124 FUN_IFUN0 FITSHead /* same as above, but no reset performed */
125 /* image information */
126 FUN_DTYPE int /* data type for images */
127 FUN_DLEN int /* length of image in bytes */
128 FUN_DPAD int /* padding to end of extension */
129 FUN_DOBLANK int /* was blank keyword defined? */
130 FUN_BLANK int /* value for blank */
131 FUN_SCALED int /* was bscale/bzero defined? */
132 FUN_BSCALE double /* bscale value */
133 FUN_BZERO double /* bzero value */
134 /* table information */
135 FUN_NROWS int /* number of rows in file (naxis2) */
136 FUN_ROWSIZE int /* size of user row struct */
137 FUN_BINCOLS char * /* specified binning columns */
138 FUN_OVERFLOW int /* overflow detected during binning? */
139 /* array information */
140 FUN_SKIP int /* bytes to skip in array header */
141 /* section information */
142 FUN_SECT_X0 int /* low dim1 value of section */
143 FUN_SECT_X1 int /* hi dim1 value of section */
144 FUN_SECT_Y0 int /* low dim2 value of section */
145 FUN_SECT_Y1 int /* hi dim2 value of section */
146 FUN_SECT_BLOCK int /* section block factor */
147 FUN_SECT_BTYPE int /* 's' (sum), 'a' (average) for binning */
148 FUN_SECT_DIM1 int /* dim1 for section */
149 FUN_SECT_DIM2 int /* dim2 for section */
150 FUN_SECT_BITPIX int /* bitpix for section */
151 FUN_SECT_DTYPE int /* data type for section */
152 FUN_RAWBUF char * /* pointer to raw row buffer */
153 FUN_RAWSIZE int /* byte size of raw row records */
154 /* column information */
155 FUN_NCOL int /* number of row columns defined */
156 FUN_COLS FunCol /* array of row columns */
157 /* WCS information */
158 FUN_WCS struct WorldCoor * /* wcs structure, converted for images*/
159 FUN_WCS0 struct WorldCoor * /* wcs structure, not converted */
160 Row applications would not normally need any of this information. An
162 example of how these values can be used in more complex programs is the
163 evnext example code. In this program, the time value for each row is
164 changed to be the value of the succeeding row. The program thus reads
165 the time values for a batch of rows, changes the time values to be the
166 value for the succeeding row, and then merges these changed time values
167 back with the other columns to the output file. It then reads the next
168 batch, etc.
169 This does not work for the last row read in each batch, since there is
171 no succeeding row until the next batch is read. Therefore, the program
172 saves that last row until it has read the next batch, then processes
173 the former before starting on the new batch. In order to merge the last
174 row successfully, the code uses FUN_RAWBUF to save and restore the raw
175 input data associated with each batch of rows. Clearly, this requires
176 some information about how funtools works internally. We are happy to
177 help you write such programs as the need arises.
178
180 See funtools(n) for a list of Funtools help pages
181version 1.4.0 August 15, 2007 funinfoget(3)