1 files changed, 542 insertions, 0 deletions
diff --git a/funtools/doc/pod/funlib.pod b/funtools/doc/pod/funlib.pod
new file mode 100644
index 0000000..354e217
--- /dev/null
+++ b/funtools/doc/pod/funlib.pod
@@ -0,0 +1,542 @@
+=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