funlib(3)

1funlib(3)                     SAORD Documentation                    funlib(3)
2
3
4

NAME

6       FunLib: the Funtools Programming Interface
7

SYNOPSIS

9       A description of the Funtools library.
10

DESCRIPTION

12       Introduction to the Funtools Programming Interface
13
14       To create a Funtools application, you need to include the funtools.h
15       definitions file in your code:
16
17         #include <funtools.h>
18
19       You then call Funtools subroutines and functions to access Funtools
20       data.  The most important routines are:
21
22       ·   FunOpen: open a Funtools file
23
24       ·   FunInfoGet: get info about an image or table
25
26       ·   FunImageGet: retrieve image data
27
28       ·   FunImageRowGet: retrieve image data by row
29
30       ·   FunImagePut: output image data
31
32       ·   FunImageRowPut: output image data by row
33
34       ·   FunColumnSelect: select columns in a table for access
35
36       ·   FunTableRowGet: retrieve rows from a table
37
38       ·   FunTableRowPut: output rows to a table
39
40       ·   FunClose: close a Funtools file
41
42       Your program must be linked against the libfuntools.a library, along
43       with the math library. The following libraries also might be required
44       on your system:
45
46       ·   -lsocket -lnsl for socket support
47
48       ·   -ldl           for dynamic loading
49
50       For example, on a Solaris system using gcc, use the following link
51       line:
52
53         gcc -o foo foo.c -lfuntools -lsocket -lnsl -ldl -lm
54
55       On a Solaris system using Solaris cc, use the following link line:
56
57         gcc -o foo foo.c -lfuntools -lsocket -lnsl -lm
58
59       On a Linux system using gcc, use the following link line:
60
61         gcc -o foo foo.c -lfuntools -ldl -lm
62
63       Once configure has built a Makefile on your platform, the required
64       "extra" libraries (aside from -lm, which always is required) are speci‐
65       fied in that file's EXTRA_LIBS variable. For example, under Linux you
66       will find:
67
68         grep EXTRA_LIBS Makefile
69         EXTRA_LIBS      =  -ldl
70         ...
71
72       The Funtools library contains both the zlib library
73       (http://www.gzip.org/zlib/) and Doug Mink's WCS library
74       (http://tdc-www.harvard.edu/software/wcstools/).  It is not necessary
75       to put these libraries on a Funtools link line. Include files necessary
76       for using these libraries are installed in the Funtools include direc‐
77       tory.
78
79       Funtools Programming Tutorial
80
81       The FunOpen() function is used to open a FITS file, an array, or a raw
82       event file:
83
84         /* open the input FITS file for reading */
85         ifun = FunOpen(iname, "r", NULL);
86         /* open the output FITS file for writing, and connect it to the input file */
87         ofun = FunOpen(iname, "w", ifun);
88
89       A new output file can inherit header parameters automatically from
90       existing input file by passing the input Funtools handle as the last
91       argument to the new file's FunOpen() call as shown above.
92
93       For image data, you then can call FunImageGet() to read an image into
94       memory.
95
96         float buf=NULL;
97         /* extract and bin the data section into an image buffer */
98         buf = FunImageGet(fun, NULL, "bitpix=-32");
99
100       If the (second) buf argument to this call is NULL, buffer space is
101       allocated automatically. The (third) plist argument can be used to
102       specify the return data type of the array.  If NULL is specified, the
103       data type of the input file is used.
104
105       To process an image buffer, you would generally make a call to FunInfo‐
106       Get() to determine the dimensions of the image (which may have been
107       changed from the original file dimensions due to Funtools image sec‐
108       tioning on the command line). In a FITS image, the index along the dim1
109       axis varies most rapidly, followed by the dim2 axis, etc.  Thus, to
110       access each pixel in an 2D image, use a double loop such as:
111
112         buf = FunImageGet(fun, NULL, "bitpix=-32");
113         FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0);
114         for(i=1; i<=dim2; i++){
115           for(j=1; j<=dim1; j++){
116             ... process buf[((i-1)*dim1)+(j-1)] ...
117           }
118         }
119
120       or:
121
122         buf = FunImageGet(fun, NULL, "bitpix=-32");
123         FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0);
124         for(i=0; i<(dim1*dim2); i++){
125           ... process buf[i] ...
126         }
127
128       Finally, you can write the resulting image to disk using FunImagePut():
129
130         FunImagePut(fun2, buf, dim1, dim2, -32, NULL);
131
132       Note that Funtools automatically takes care of book-keeping tasks such
133       as reading and writing FITS headers (although you can, of course, write
134       your own header or add your own parameters to a header).
135
136       For binary tables and raw event files, a call to FunOpen() will be fol‐
137       lowed by a call to the FunColumnSelect() routine to select columns to
138       be read from the input file and/or written to the output file:
139
140         typedef struct evstruct{
141           double time;
142           int time2;
143         } *Ev, EvRec;
144         FunColumnSelect(fun, sizeof(EvRec), NULL,
145                         "time",      "D",     "rw",  FUN_OFFSET(Ev, time),
146                         "time2",     "J",     "w",   FUN_OFFSET(Ev, time2),
147                         NULL);
148
149       Columns whose (third) mode argument contains an "r" are "readable",
150       i.e., columns will be read from the input file and converted into the
151       data type specified in the call's second argument. These columns values
152       then are stored in the specified offset of the user record structure.
153       Columns whose mode argument contains a "w" are "writable", i.e., these
154       values will be written to the output file.  The FunColumnSelect() rou‐
155       tine also offers the option of automatically merging user columns with
156       the original input columns when writing the output rows.
157
158       Once a set of columns has been specified, you can retrieve rows using
159       FunTableRowGet(), and write the rows using FunTableRowPut():
160
161         Ev ebuf, ev;
162         /* get rows -- let routine allocate the array */
163         while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){
164           /* process all rows */
165           for(i=0; i<got; i++){
166             /* point to the i'th row */
167             ev = ebuf+i;
168             /* time2 is generated here */
169             ev->time2 = (int)(ev->time+.5);
170             /* change the input time as well */
171             ev->time = -(ev->time/10.0);
172           }
173           /* write out this batch of rows with the new column */
174           FunTableRowPut(fun2, (char *)ebuf, got, 0, NULL);
175           /* free row data */
176           if( ebuf ) free(ebuf);
177         }
178
179       The input rows are retrieved into an array of user structs, which can
180       be accessed serially as shown above. Once again, Funtools automatically
181       takes care of book-keeping tasks such as reading and writing FITS head‐
182       ers (although you can, of course, write your own header or add your own
183       parameters to a header).
184
185       When all processing is done, you can call FunClose() to close the
186       file(s):
187
188         FunClose(fun2);
189         FunClose(fun);
190
191       These are the basics of processing FITS files (and arrays or raw event
192       data) using Funtools. The routines in these examples are described in
193       more detail below, along with a few other routines that support parame‐
194       ter access, data flushing, etc.
195
196       Compiling and Linking
197
198       To create a Funtools application, a software developer will include the
199       funtools.h definitions file in Funtools code:
200
201         #include <funtools.h>
202
203       The program is linked against the libfuntools.a library, along with the
204       math library (and the dynamic load library, if the latter is available
205       on your system):
206
207         gcc -o foo foo.c -lfuntools -ldl -lm
208
209       If gcc is used, Funtools filtering can be performed using dynamically
210       loaded shared objects that are built at run-time. Otherwise, filtering
211       is performed using a slave process.
212
213       Funtools has been built on the following systems:
214
215       ·   Sun/Solaris 5.X
216
217       ·   Linux/RedHat Linux 5.X,6.X,7.X
218
219       ·   Dec Alpha/OSF1 V4.X
220
221       ·   WindowsNT/Cygwin 1.0
222
223       ·   SGI/IRIX64 6.5
224
225       A Short Digression on Subroutine Order
226
227       There is a natural order for all I/O access libraries. You would not
228       think of reading a file without first opening it, or writing a file
229       after closing it. A large part of the experiment in funtools is to use
230       the idea of "natural order" as a means of making programming easier. We
231       do this by maintaining the state of processing for a given funtools
232       file, so that we can do things like write headers and flush extension
233       padding at the right time, without you having to do it.
234
235       For example, if you open a new funtools file for writing using
236       FunOpen(), then generate an array of image data and call FunImagePut(),
237       funtools knows to write the image header automatically.  There is no
238       need to think about writing a standard header.  Of course, you can add
239       parameters to the file first by calling one of the FunParamPut() rou‐
240       tines, and these parameters will automatically be added to the header
241       when it is written out.  There still is no need to write the header
242       explicitly.
243
244       Maintaining state in this way means that there are certain rules of
245       order which should be maintained in any funtools program. In particu‐
246       lar, we strongly recommend the following ordering rules be adhered to:
247
248       ·   When specifying that input extensions be copied to an output file
249           via a reference handle, open the output file before reading the
250           input file. (Otherwise the initial copy will not occur).
251
252       ·   Always write parameters to an output file using one of the Fun‐
253           ParamPut() calls before writing any data. (This is a good idea for
254           all FITS libraries, to avoid having to recopy data is the FITS
255           header needs to be extended by adding a single parameter.)
256
257       ·   If you retrieve an image, and need to know the data type, use the
258           FUN_SECT_BITPIX option of FunInfoGet(), after calling FunIm‐
259           ageGet(), since it is possible to change the value of BITPIX from
260           the latter.
261
262       ·   When specifying that input extensions be copied to an output file
263           via a reference handle, close the output file before closing input
264           file, or else use FunFlush() explicitly on the output file before
265           closing the input file. (Otherwise the final copy will not occur).
266
267       We believe that these are the natural rules that are implied in most
268       FITS programming tasks. However, we recognize that making explicit use
269       of "natural order" to decide what automatic action to take on behalf of
270       the programmer is experimental.  Therefore, if you find that your needs
271       are not compatible with our preferred order, please let us know -- it
272       will be most illuminating for us as we evaluate this experiment.
273
274       Funtools Programming Examples
275
276       The following complete coding examples are provided to illustrate the
277       simplicity of Funtools applications.  They can be found in the funtest
278       subdirectory of the Funtools distribution.  In many cases, you should
279       be able to modify one of these programs to generate your own Funtools
280       program:
281
282       ·   evread.c: read and write binary tables
283
284       ·   evcols.c: add column and rows to binary tables
285
286       ·   evmerge.c: merge new columns with existing columns
287
288       ·   evnext.c: manipulate raw data pointers
289
290       ·   imblank.c: blank out image values below a threshold
291
292       ·   asc2fits.c: convert a specific ASCII table to FITS binary table
293
294       The Funtools Programming Reference Manual
295
296       #include <funtools.h>
297
298       Fun FunOpen(char *name, char *mode, Fun ref)
299
300       void *FunImageGet(Fun fun, void *buf, char *plist)
301
302       int FunImagePut(Fun fun, void *buf, int dim1, int dim2, int bitpix,
303       char *plist)
304
305       void * FunImageRowGet(Fun fun, void *buf, int rstart, int rstop, char
306       *plist)
307
308       void * FunImageRowPut(Fun fun, void *buf, int rstart, int rstop, int
309       dim1, int dim2, int bitpix, char *plist)
310
311       int FunColumnSelect(Fun fun, int size, char *plist, ...)
312
313       void FunColumnActivate(Fun fun, char *s, char *plist)
314
315       int FunColumnLookup(Fun fun, char *s, int which, char **name, int
316       *type, int *mode, int *offset, int *n, int *width)
317
318       void *FunTableRowGet(Fun fun, void *rows, int maxrow, char *plist, int
319       *nrow)
320
321       int FunTableRowPut(Fun fun, void *rows, int nev, int idx, char *plist)
322
323       int FunParamGetb(Fun fun, char *name, int n, int defval, int *got)
324
325       int FunParamGeti(Fun fun, char *name, int n, int defval, int *got)
326
327       double FunParamGetd(Fun fun, char *name, int n, double defval, int
328       *got)
329
330       char *FunParamGets(Fun fun, char *name, int n, char *defval, int *got)
331
332       int FunParamPutb(Fun fun, char *name, int n, int value, char *comm, int
333       append)
334
335       int FunParamPuti(Fun fun, char *name, int n, int value, char *comm, int
336       append)
337
338       int FunParamPutd(Fun fun, char *name, int n, double value, int prec,
339       char *comm, int append)
340
341       int FunParamPuts(Fun fun, char *name, int n, char *value, char *comm,
342       int append)
343
344       int FunInfoGet(Fun fun, int type, ...)
345
346       int FunInfoPut(Fun fun, int type, ...)
347
348       void FunFlush(Fun fun, char *plist)
349
350       void FunClose(Fun fun)
351

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO