NAME¶
FunImageGet - get an image or image section
SYNOPSIS¶
#include <funtools.h>
void *FunImageGet(Fun fun, void *buf, char *plist)
DESCRIPTION¶
The
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
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
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
plist (i.e., parameter list) argument is a string containing
one or more comma-delimited
keyword=value parameters. It can be used to
specify the return data type using the
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
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:
- •
- 8 unsigned char
- •
- 16 short
- •
- 32 int
- •
- \-32 float
- •
- \-64 double
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
bincols=(x,y) keyword:
funcnts "foo.ev[EVENTS,bincols=(detx,dety)]"
The full form of the
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
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.
SEE ALSO¶
See
funtools(7) for a list of Funtools help pages