1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
|
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.\"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "funinfoget 3"
.TH funinfoget 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation"
.SH "NAME"
FunInfoGet \- get information from Funtools struct
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <funtools.h>
.Ve
.PP
.Vb 1
\& int FunInfoGet(Fun fun, int type, char *addr, ...)
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fB\f(BIFunInfoGet()\fB\fR routine returns information culled from the
Funtools structure. The first argument is the Fun handle from which
information is to be retrieved. This first required argument is followed
by a variable length list of pairs of arguments. Each pair consists
of an integer representing the type of information to retrieve and the
address where the information is to be stored. The list is terminated by a 0.
The routine returns the number of get actions performed.
.PP
The full list of available information is described below. Please note
that only a few of these will be useful to most application developers.
For imaging applications, the most important types are:
.PP
.Vb 3
\& FUN_SECT_DIM1 int /* dim1 for section */
\& FUN_SECT_DIM2 int /* dim2 for section */
\& FUN_SECT_BITPIX int /* bitpix for section */
.Ve
.PP
These would be used to determine the dimensions and data type of image
data retrieved using the
\&\fIFunImageGet()\fR routine. For
example:
.PP
.Vb 17
\& /* extract and bin the data section into an image buffer */
\& buf = FunImageGet(fun, NULL, NULL);
\& /* get required information from funtools structure.
\& this should come after the FunImageGet() call, in case the call
\& changed sect_bitpix */
\& FunInfoGet(fun,
\& FUN_SECT_BITPIX, &bitpix,
\& FUN_SECT_DIM1, &dim1,
\& FUN_SECT_DIM2, &dim2,
\& 0);
\& /* loop through pixels and reset values below limit to value */
\& for(i=0; i<dim1*dim2; i++){
\& switch(bitpix){
\& case 8:
\& if( cbuf[i] <= blimit ) cbuf[i] = bvalue;
\& ...
\& }
.Ve
.PP
It is important to bear in mind that the call to
\&\fIFunImageGet()\fR
can change the value of \s-1FUN_SECT_BITPIX\s0 (e.g. if \*(L"bitpix=n\*(R" is passed
in the param list). Therefore, a call to
\&\fIFunInfoGet()\fR
should be made \fBafter\fR the call to
\&\fIFunImageGet()\fR,
in order to retrieve the updated bitpix value.
See the imblank example code for more
details.
.PP
It also can be useful to retrieve the World Coordinate System
information from the Funtools structure. Funtools uses the the \s-1WCS\s0
Library developed by Doug Mink at \s-1SAO\s0, which is available
here.
(More information about the WCSTools project in general can be found
here.)
The \fIFunOpen()\fR routine initializes
two \s-1WCS\s0 structures that can be used with this \s-1WCS\s0 Library.
Applications can retrieve either of these two \s-1WCS\s0 structures using
\&\fB\f(BIFunInfoGet()\fB\fR:
.PP
.Vb 2
\& FUN_WCS struct WorldCoor * /* wcs structure, for image coordinates*/
\& FUN_WCS0 struct WorldCoor * /* wcs structure, for physical coordinates */
.Ve
.PP
The structure retrieved by \s-1FUN_WCS\s0 is a \s-1WCS\s0 library handle containing
parameters suitable for use with image coordinates, regardless of whether the
data are images or tables. For this structure, the \s-1WCS\s0 reference point
(\s-1CRPIX\s0) has been converted to image coordinates if the underlying file
is a table (and therefore in physical coordinates). You therefore must
ensure that the positions being passed to a routine like pix2wcs are in
image coordinates. The \s-1FUN_WCS0\s0 structure has not had its \s-1WCS\s0
reference point converted to image coordinates. It therefore is useful
when passing processing physical coordinates from a table.
.PP
Once a \s-1WCS\s0 structure has been retrieved, it can be used as the first
argument to the \s-1WCS\s0 library routines. (If the structure is \s-1NULL\s0, no
\&\s-1WCS\s0 information was contained in the file.) The two important \s-1WCS\s0 routines
that Funtools uses are:
.PP
.Vb 5
\& #include <wcs.h>
\& void pix2wcs (wcs,xpix,ypix,xpos,ypos)
\& struct WorldCoor *wcs; /* World coordinate system structure */
\& double xpix,ypix; /* x and y coordinates in pixels */
\& double *xpos,*ypos; /* RA and Dec in degrees (returned) */
.Ve
.PP
which converts pixel coordinates to sky coordinates, and:
.PP
.Vb 5
\& void wcs2pix (wcs, xpos, ypos, xpix, ypix, offscl)
\& struct WorldCoor *wcs; /* World coordinate system structure */
\& double xpos,ypos; /* World coordinates in degrees */
\& double *xpix,*ypix; /* coordinates in pixels */
\& int *offscl; /* 0 if within bounds, else off scale */
.Ve
.PP
which converts sky coordinates to pixel coordinates. Again, please note
that the wcs structure returned by \s-1FUN_WCS\s0 assumes that image coordinates
are passed to the pix2wcs routine, while \s-1FUN_WCS0\s0 assumes that physical
coordinates are passed.
.PP
Note that funtools.h file automatically includes wcs.h. An example
program that utilizes these \s-1WCS\s0 structure to call \s-1WCS\s0 Library routines
is twcs.c.
.PP
The following is the complete list of information that can be returned:
.PP
.Vb 52
\& name type comment
\& --------- -------- ---------------------------------------------
\& FUN_FNAME char * /* file name */
\& FUN_GIO GIO /* gio handle */
\& FUN_HEADER FITSHead /* fitsy header struct */
\& FUN_TYPE int /* TY_TABLE,TY_IMAGE,TY_EVENTS,TY_ARRAY */
\& FUN_BITPIX int /* bits/pixel in file */
\& FUN_MIN1 int /* tlmin of axis1 -- tables */
\& FUN_MAX1 int /* tlmax of axis1 -- tables */
\& FUN_MIN2 int /* tlmin of axis2 -- tables */
\& FUN_MAX2 int /* tlmax of axis2 -- tables */
\& FUN_DIM1 int /* dimension of axis1 */
\& FUN_DIM2 int /* dimension of axis2 */
\& FUN_ENDIAN int /* 0=little, 1=big endian */
\& FUN_FILTER char * /* supplied filter */
\& FUN_IFUN FITSHead /* pointer to reference header */
\& FUN_IFUN0 FITSHead /* same as above, but no reset performed */
\& /* image information */
\& FUN_DTYPE int /* data type for images */
\& FUN_DLEN int /* length of image in bytes */
\& FUN_DPAD int /* padding to end of extension */
\& FUN_DOBLANK int /* was blank keyword defined? */
\& FUN_BLANK int /* value for blank */
\& FUN_SCALED int /* was bscale/bzero defined? */
\& FUN_BSCALE double /* bscale value */
\& FUN_BZERO double /* bzero value */
\& /* table information */
\& FUN_NROWS int /* number of rows in file (naxis2) */
\& FUN_ROWSIZE int /* size of user row struct */
\& FUN_BINCOLS char * /* specified binning columns */
\& FUN_OVERFLOW int /* overflow detected during binning? */
\& /* array information */
\& FUN_SKIP int /* bytes to skip in array header */
\& /* section information */
\& FUN_SECT_X0 int /* low dim1 value of section */
\& FUN_SECT_X1 int /* hi dim1 value of section */
\& FUN_SECT_Y0 int /* low dim2 value of section */
\& FUN_SECT_Y1 int /* hi dim2 value of section */
\& FUN_SECT_BLOCK int /* section block factor */
\& FUN_SECT_BTYPE int /* 's' (sum), 'a' (average) for binning */
\& FUN_SECT_DIM1 int /* dim1 for section */
\& FUN_SECT_DIM2 int /* dim2 for section */
\& FUN_SECT_BITPIX int /* bitpix for section */
\& FUN_SECT_DTYPE int /* data type for section */
\& FUN_RAWBUF char * /* pointer to raw row buffer */
\& FUN_RAWSIZE int /* byte size of raw row records */
\& /* column information */
\& FUN_NCOL int /* number of row columns defined */
\& FUN_COLS FunCol /* array of row columns */
\& /* WCS information */
\& FUN_WCS struct WorldCoor * /* wcs structure, converted for images*/
\& FUN_WCS0 struct WorldCoor * /* wcs structure, not converted */
.Ve
.PP
Row applications would not normally need any of this information.
An example of how these values can be used in more complex programs is
the evnext example code. In this program, the
time value for each row is changed to be the value of the succeeding
row. The program thus reads the time values for a batch of rows,
changes the time values to be the value for the succeeding row, and
then merges these changed time values back with the other columns to
the output file. It then reads the next batch, etc.
.PP
This does not work for the last row read in each batch, since there
is no succeeding row until the next batch is read. Therefore, the
program saves that last row until it has read the next batch, then
processes the former before starting on the new batch. In order to
merge the last row successfully, the code uses \s-1FUN_RAWBUF\s0 to save
and restore the raw input data associated with each batch of
rows. Clearly, this requires some information about how funtools
works internally. We are happy to help you write such programs as the
need arises.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See funtools(7) for a list of Funtools help pages
|