diff options
Diffstat (limited to 'funtools/doc/pod/funlib.pod')
| -rw-r--r-- | funtools/doc/pod/funlib.pod | 542 |
1 files changed, 0 insertions, 542 deletions
diff --git a/funtools/doc/pod/funlib.pod b/funtools/doc/pod/funlib.pod deleted file mode 100644 index 354e217..0000000 --- a/funtools/doc/pod/funlib.pod +++ /dev/null @@ -1,542 +0,0 @@ -=pod - -=head1 NAME - - - -B<FunLib: the Funtools Programming Interface> - - - -=head1 SYNOPSIS - - - - -A description of the Funtools library. - - - -=head1 DESCRIPTION - - - -B<Introduction to the Funtools Programming Interface> - -To create a Funtools application, you need to include -the funtools.h definitions file in your code: - - #include <funtools.h> - - -You then call Funtools subroutines and functions to access Funtools data. -The most important routines are: - - -=over 4 - - - - - - -=item * - -FunOpen: open a Funtools file - - -=item * - -FunInfoGet: get info about an image or table - - -=item * - -FunImageGet: retrieve image data - - -=item * - -FunImageRowGet: retrieve image data by row - - -=item * - -FunImagePut: output image data - - -=item * - -FunImageRowPut: output image data by row - - -=item * - -FunColumnSelect: select columns in a table for access - - -=item * - -FunTableRowGet: retrieve rows from a table - - -=item * - -FunTableRowPut: output rows to a table - - -=item * - -FunClose: close a Funtools file - - -=back - - - -Your program must be linked against the libfuntools.a library, -along with the math library. The following libraries also might be required -on your system: - - -=over 4 - - - - -=item * - --lsocket -lnsl for socket support - - -=item * - --ldl for dynamic loading - - -=back - - - -For example, on a Solaris system using gcc, use the following link line: - - gcc -o foo foo.c -lfuntools -lsocket -lnsl -ldl -lm - -On a Solaris system using Solaris cc, use the following link line: - - gcc -o foo foo.c -lfuntools -lsocket -lnsl -lm - -On a Linux system using gcc, use the following link line: - - gcc -o foo foo.c -lfuntools -ldl -lm - -Once configure has built a Makefile on your platform, the required -"extra" libraries (aside from -lm, which always is required) are -specified in that file's EXTRA_LIBS variable. For example, under -Linux you will find: - - grep EXTRA_LIBS Makefile - EXTRA_LIBS = -ldl - ... - - - -The Funtools library contains both the zlib library -(http://www.gzip.org/zlib/) and Doug Mink's WCS library -(http://tdc-www.harvard.edu/software/wcstools/). It is not necessary -to put these libraries on a Funtools link line. Include files -necessary for using these libraries are installed in the Funtools -include directory. - -B<Funtools Programming Tutorial> - -The -FunOpen() -function is used to open a FITS file, an array, or a raw event file: - - /* open the input FITS file for reading */ - ifun = FunOpen(iname, "r", NULL); - /* open the output FITS file for writing, and connect it to the input file */ - ofun = FunOpen(iname, "w", ifun); - -A new output file can inherit header parameters automatically from -existing input file by passing the input Funtools handle as the last -argument to the new file's -FunOpen() -call as shown above. - - -For image data, you then can call -FunImageGet() -to read an image into memory. - - float buf=NULL; - /* extract and bin the data section into an image buffer */ - buf = FunImageGet(fun, NULL, "bitpix=-32"); - -If the (second) buf argument to this call is NULL, buffer space is allocated -automatically. The (third) plist argument can be used to specify the -return data type of the array. If NULL is specified, the data type of -the input file is used. - - -To process an image buffer, you would generally make a call to -FunInfoGet() to determine the -dimensions of the image (which may have been changed from the original -file dimensions due to Funtools image -sectioning on the command line). In a FITS image, the index along -the dim1 axis varies most rapidly, followed by the dim2 axis, etc. -Thus, to access each pixel in an 2D image, use a double loop such as: - - buf = FunImageGet(fun, NULL, "bitpix=-32"); - FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0); - for(i=1; i<=dim2; i++){ - for(j=1; j<=dim1; j++){ - ... process buf[((i-1)*dim1)+(j-1)] ... - } - } - -or: - - buf = FunImageGet(fun, NULL, "bitpix=-32"); - FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0); - for(i=0; i<(dim1*dim2); i++){ - ... process buf[i] ... - } - -Finally, you can write the resulting image to disk using -FunImagePut(): - - FunImagePut(fun2, buf, dim1, dim2, -32, NULL); - -Note that Funtools automatically takes care of book-keeping tasks such as -reading and writing FITS headers (although you can, of course, write -your own header or add your own parameters to a header). - - -For binary tables and raw event files, a call to -FunOpen() -will be followed by a call to the -FunColumnSelect() -routine to select columns to be read from the input file and/or -written to the output file: - - - typedef struct evstruct{ - double time; - int time2; - } *Ev, EvRec; - FunColumnSelect(fun, sizeof(EvRec), NULL, - "time", "D", "rw", FUN_OFFSET(Ev, time), - "time2", "J", "w", FUN_OFFSET(Ev, time2), - NULL); - -Columns whose (third) mode argument contains an "r" are "readable", -i.e., columns will be read from the input file and converted into the -data type specified in the call's second argument. These columns -values then are stored in the specified offset of the user record -structure. Columns whose mode argument contains a "w" are -"writable", i.e., these values will be written to the output file. -The -FunColumnSelect() -routine also offers the option of automatically merging user -columns with the original input columns when writing the output -rows. - - -Once a set of columns has been specified, you can retrieve rows using -FunTableRowGet(), -and write the rows using -FunTableRowPut(): - - Ev ebuf, ev; - /* get rows -- let routine allocate the array */ - while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ - /* process all rows */ - for(i=0; i<got; i++){ - /* point to the i'th row */ - ev = ebuf+i; - /* time2 is generated here */ - ev->time2 = (int)(ev->time+.5); - /* change the input time as well */ - ev->time = -(ev->time/10.0); - } - /* write out this batch of rows with the new column */ - FunTableRowPut(fun2, (char *)ebuf, got, 0, NULL); - /* free row data */ - if( ebuf ) free(ebuf); - } - -The input rows are retrieved into an array of user structs, which -can be accessed serially as shown above. Once again, Funtools -automatically takes care of book-keeping tasks such as reading and writing -FITS headers (although you can, of course, write your own header or -add your own parameters to a header). - - -When all processing is done, you can call -FunClose() -to close the file(s): - - FunClose(fun2); - FunClose(fun); - - - -These are the basics of processing FITS files (and arrays or raw event -data) using Funtools. The routines in these examples are described in -more detail below, along with a few other routines that support -parameter access, data flushing, etc. - -B<Compiling and Linking> - -To create a Funtools application, a software developer will include -the funtools.h definitions file in Funtools code: - - #include <funtools.h> - -The program is linked against the libfuntools.a library, along with the -math library (and the dynamic load library, if the latter is available -on your system): - - gcc -o foo foo.c -lfuntools -ldl -lm - - -If gcc is used, Funtools filtering can be performed using dynamically -loaded shared objects that are built at run-time. Otherwise, filtering -is performed using a slave process. - -Funtools has been built on the following systems: - - -=over 4 - - - - -=item * - -Sun/Solaris 5.X - - -=item * - -Linux/RedHat Linux 5.X,6.X,7.X - - -=item * - -Dec Alpha/OSF1 V4.X - - -=item * - -WindowsNT/Cygwin 1.0 - - -=item * - -SGI/IRIX64 6.5 - - -=back - - - -B<A Short Digression on Subroutine Order> - -There is a natural order for all I/O access libraries. You would not -think of reading a file without first opening it, or writing a file -after closing it. A large part of the experiment in funtools is to use -the idea of "natural order" as a means of making programming -easier. We do this by maintaining the state of processing for a given -funtools file, so that we can do things like write headers and flush -extension padding at the right time, without you having to do it. - - -For example, if you open a new funtools file for writing using -FunOpen(), -then generate an array of image data and call -FunImagePut(), -funtools knows to write the image header automatically. -There is no need to think about writing a standard header. -Of course, you can add parameters to the file first by -calling one of the -FunParamPut() -routines, and these parameters will automatically be added -to the header when it is written out. There still is no -need to write the header explicitly. - - -Maintaining state in this way means that there are certain rules of -order which should be maintained in any funtools program. In particular, -we strongly recommend the following ordering rules be adhered to: - - - -=over 4 - - - - -=item * - -When specifying that input extensions be copied to an output file -via a reference handle, open the output file B<before> reading the -input file. (Otherwise the initial copy will not occur). - - - -=item * - -Always write parameters to an output file using one of the -FunParamPut() calls -B<before> writing any data. (This is a good idea for all FITS -libraries, to avoid having to recopy data is the FITS header needs -to be extended by adding a single parameter.) - - - -=item * - -If you retrieve an image, and need to know the data -type, use the FUN_SECT_BITPIX option of -FunInfoGet(), -B<after> calling -FunImageGet(), since -it is possible to change the value of BITPIX from the latter. - - - -=item * - -When specifying that input extensions be copied to an output file -via a reference handle, close the output file B<before> closing -input file, or else use -FunFlush() -explicitly on the output file -B<before> closing the input file. (Otherwise the final copy will -not occur). - - -=back - - - - -We believe that these are the natural rules that are implied in most -FITS programming tasks. However, we recognize that making explicit use -of "natural order" to decide what automatic action to take on behalf -of the programmer is experimental. Therefore, if you find that your -needs are not compatible with our preferred order, please let us know --- it will be most illuminating for us as we evaluate this experiment. - -B<Funtools Programming Examples> - -The following complete coding examples are provided to illustrate the -simplicity of Funtools applications. They can be found in the funtest -subdirectory of the Funtools distribution. In many cases, you should -be able to modify one of these programs to generate your own Funtools -program: - - -=over 4 - - - - -=item * - -evread.c: read and write binary tables - - -=item * - -evcols.c: add column and rows to binary tables - - -=item * - -evmerge.c: merge new columns with existing columns - - -=item * - -evnext.c: manipulate raw data pointers - - -=item * - -imblank.c: blank out image values below a threshold - - -=item * - -asc2fits.c: convert a specific ASCII table to FITS binary table - - -=back - - - -B<The Funtools Programming Reference Manual> - - -#include <funtools.h> - -Fun FunOpen(char *name, char *mode, Fun ref) - -void *FunImageGet(Fun fun, void *buf, char *plist) - -int FunImagePut(Fun fun, void *buf, int dim1, int dim2, int bitpix, char *plist) - -void * FunImageRowGet(Fun fun, void *buf, int rstart, int rstop, char *plist) - -void * FunImageRowPut(Fun fun, void *buf, int rstart, int rstop, int dim1, int dim2, int bitpix, char *plist) - -int FunColumnSelect(Fun fun, int size, char *plist, ...) - -void FunColumnActivate(Fun fun, char *s, char *plist) - -int FunColumnLookup(Fun fun, char *s, int which, char **name, int *type, int *mode, int *offset, int *n, int *width) - -void *FunTableRowGet(Fun fun, void *rows, int maxrow, char *plist, int *nrow) - -int FunTableRowPut(Fun fun, void *rows, int nev, int idx, char *plist) - -int FunParamGetb(Fun fun, char *name, int n, int defval, int *got) - -int FunParamGeti(Fun fun, char *name, int n, int defval, int *got) - -double FunParamGetd(Fun fun, char *name, int n, double defval, int *got) - -char *FunParamGets(Fun fun, char *name, int n, char *defval, int *got) - -int FunParamPutb(Fun fun, char *name, int n, int value, char *comm, int append) - -int FunParamPuti(Fun fun, char *name, int n, int value, char *comm, int append) - -int FunParamPutd(Fun fun, char *name, int n, double value, int prec, char *comm, int append) - -int FunParamPuts(Fun fun, char *name, int n, char *value, char *comm, int append) - -int FunInfoGet(Fun fun, int type, ...) - -int FunInfoPut(Fun fun, int type, ...) - -void FunFlush(Fun fun, char *plist) - -void FunClose(Fun fun) - - - - - -=head1 SEE ALSO - - - -See funtools(n) for a list of Funtools help pages - - -=cut |