=pod

=head1 NAME



B<FunImageRowGet - get row(s) of an image>



=head1 SYNOPSIS





  #include <funtools.h>

  void *FunImageRowGet(Fun fun, void *buf, int rstart, int rstop,
                       char *plist)





=head1 DESCRIPTION




The B<FunImageRowGet()> routine returns one or more image rows
from the specified section of a Funtools data file.  If the input data
are of type image, the array is generated by extracting the specified
image rows and then binning them 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 needed),
after which the image section and bin factors are applied.


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.


The third and fourth arguments specify the first and last row to
retrieve.  Rows are counted starting from 1, up to the value of
FUN_YMAX(fun).  The final 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 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=>value 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:

  double *drow;
  Fun fun;
  ... open files ...
  /* get section dimensions */
  FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0);
  /* allocate one line's worth */
  drow = malloc(dim1*sizeof(double));
  /* retrieve and process each input row (starting at 1) */
  for(i=1; i <= dim2; i++){
    if( !FunImageRowGet(fun, drow, i, i, "bitpix=-64") )
      gerror(stderr, "can't FunImageRowGet: %d %s\n", i, iname);
      /* reverse the line */
      for(j=1; j<=dim1; j++){
        ... process drow[j-1] ...
      }
  }
  ...



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.  Note that the considerations described
above for specifying binning columns in 
FunImageGet() also apply to
B<FunImageRowGet()>.




=head1 SEE ALSO



See funtools(n) for a list of Funtools help pages


=cut