1 files changed, 237 insertions, 0 deletions
diff --git a/funtools/doc/pod/funimageget.pod b/funtools/doc/pod/funimageget.pod
new file mode 100644
index 0000000..a569bba
--- /dev/null
+++ b/funtools/doc/pod/funimageget.pod
@@ -0,0 +1,237 @@
+=pod
+
+=head1 NAME
+
+
+
+B<FunImageGet - get an image or image section>
+
+
+
+=head1 SYNOPSIS
+
+
+
+
+
+  #include <funtools.h>
+
+  void *FunImageGet(Fun fun, void *buf, char *plist)
+
+
+
+
+
+=head1 DESCRIPTION
+
+
+
+
+The B<FunImageGet()> routine returns an binned image array of the
+specified section of a Funtools data file.  If the input data are
+already of type image, the array is generated by extracting the
+specified image section and then binning it according to the specified
+bin factor.  If the input data are contained in a binary table or raw
+event file, the rows are binned on the columns specified by the
+B<bincols=> keyword (using appropriate default columns as
+necessary), after which the image section and bin factors are
+applied. In both cases, the data is automatically converted from FITS
+to native format, if necessary.
+
+The first argument is the Funtools handle returned by 
+FunOpen().  The second B<buf>
+argument is a pointer to a data buffer to fill. If NULL is specified,
+FunImageGet will allocate a buffer of the appropriate size. Generally
+speaking, you always want Funtools to allocate the buffer because
+the image dimensions will be determined by
+Funtools image sectioning
+on the command line.
+
+The third B<plist> (i.e., parameter list) argument is a string
+containing one or more comma-delimited B<keyword=value>
+parameters.  It can be used to specify the return data type using the
+B<bitpix=> keyword.  If no such keyword is specified in the plist
+string, the data type of the returned image is the same as the data type
+of the original input file, or is of type int for FITS binary tables.
+
+
+If the B<bitpix=> keyword is supplied in the plist string, the data
+type of the returned image will be one of the supported FITS image
+data types:
+
+
+=over 4
+
+
+
+
+=item *
+
+8 unsigned char
+
+
+=item *
+
+16 short
+
+
+=item *
+
+32 int
+
+
+=item *
+
+-32 float
+
+
+=item *
+
+-64 double
+
+
+=back
+
+
+For example:
+
+  void *buf;
+  /* extract data section into an image buffer */
+  if( !(buf = FunImageGet(fun, NULL, NULL)) )
+    gerror(stderr, "could not FunImageGet: %s\n", iname);
+
+will allocate buf and retrieve the image in the file data format. In
+this case, you will have to determine the data type (using the
+FUN_SECT_BITPIX value in the 
+FunInfoGet()
+routine)
+and then use a switch statement to process each data type:
+
+  int bitpix;
+  void *buf;
+  unsigned char *cbuf;
+  short *sbuf;
+  int *ibuf;
+  ...
+  buf = FunImageGet(fun, NULL, NULL);
+  FunInfoGet(fun, FUN_SECT_BITPIX,  &bitpix, 0);
+  /* set appropriate data type buffer to point to image buffer */
+  switch(bitpix){
+  case 8:
+    cbuf = (unsigned char *)buf; break;
+  case 16:
+    sbuf = (short *)buf; break;
+  case 32:
+    ibuf = (int *)buf; break;
+ ...
+
+See the 
+imblank example code
+for more details on how to process an image when the data type is not
+specified beforehand.
+
+
+It often is easier to specify the data type directly:
+
+  double *buf;
+  /* extract data section into a double image buffer */
+  if( !(buf = FunImageGet(fun, NULL, "bitpix=-64")) )
+    gerror(stderr, "could not FunImageGet: %s\n", iname);
+
+will extract the image while converting to type double.
+
+
+On success, a pointer to the image buffer is returned. (This will be
+the same as the second argument, if NULL is not passed to the latter.)
+On error, NULL is returned.
+
+
+In summary, to retrieve image or row data into a binned image, you simply
+call FunOpen() followed by 
+FunImageGet().  Generally, you
+then will want to call
+FunInfoGet()
+to retrieve the
+axis dimensions (and data type) of the section you are processing
+(so as to take account of sectioning and blocking of the original data):
+
+  double *buf;
+  int i, j;
+  int dim1, dim2;
+  ... other declarations, etc.
+
+  /* open the input FITS file */
+  if( !(fun = FunOpen(argv[1], "rc", NULL)) )
+    gerror(stderr, "could not FunOpen input file: %s\n", argv[1]);
+
+  /* extract and bin the data section into a double float image buffer */
+  if( !(buf = FunImageGet(fun, NULL, "bitpix=-64")) )
+    gerror(stderr, "could not FunImageGet: %s\n", argv[1]);
+
+  /* get dimension information from funtools structure */
+  FunInfoGet(fun, 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++){
+    if( buf[i] <= blimit ) buf[i] = bvalue;
+  }
+
+
+
+Another useful plist string value is "mask=all", which returns an
+image populated with regions id values. Image pixels within a region
+will contain the associated region id (region values start at 1), and
+otherwise will contain a 0 value. Thus, the returned image is a
+region mask which can be used to process the image data (which
+presumably is retrieved by a separate call to FunImageGet) pixel by
+pixel.
+
+
+If a FITS binary table or a non-FITS raw event file is being binned
+into an image, it is necessary to specify the two columns that will be
+used in the 2D binning.  This usually is done on the command line
+using the B<bincols=(x,y)> keyword:
+
+  funcnts "foo.ev[EVENTS,bincols=(detx,dety)]"
+
+
+
+The full form of the B<bincols=> specifier is:
+
+  bincols=([xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]]])
+
+where the tlmin, tlmax, and binsiz specifiers determine the image binning
+dimensions:
+
+  dim = (tlmax - tlmin)/binsiz     (floating point data)
+  dim = (tlmax - tlmin)/binsiz + 1 (integer data)
+
+These tlmin, tlmax, and binsiz specifiers can be omitted if TLMIN,
+TLMAX, and TDBIN header parameters (respectively) are present in the
+FITS binary table header for the column in question.  Note that if
+only one parameter is specified, it is assumed to be tlmax, and tlmin
+defaults to 1. If two parameters are specified, they are assumed to be
+tlmin and tlmax.
+
+
+If B<bincols> is not specified on the command line, Funtools tries
+to use appropriate defaults: it looks for the environment variable
+FITS_BINCOLS (or FITS_BINKEY). Then it looks for the Chandra
+parameters CPREF (or PREFX) in the FITS binary table header. Failing
+this, it looks for columns named "X" and "Y" and if these are not
+found, it looks for columns containing the characters "X" and "Y".
+
+See Binning FITS Binary Tables and
+Non-FITS Event Files for more information.
+
+
+
+
+=head1 SEE ALSO
+
+
+
+See funtools(n) for a list of Funtools help pages
+
+
+=cut