FunInfoGet (3)

SYNOPSIS

#include <funtools.h>

int FunInfoGet(Fun fun, int type, char *addr, ...)

DESCRIPTION

The FunInfoGet() routine returns information culled from the Funtools structure. The first argument is the Fun handle from which information is to be retrieved. This first required argument is followed by a variable length list of pairs of arguments. Each pair consists of an integer representing the type of information to retrieve and the address where the information is to be stored. The list is terminated by a 0. The routine returns the number of get actions performed.

The full list of available information is described below. Please note that only a few of these will be useful to most application developers. For imaging applications, the most important types are:

It is important to bear in mind that the call to FunImageGet() can change the value of \s-1FUN_SECT_BITPIX\s0 (e.g. if \*(L"bitpix=n\*(R" is passed in the param list). Therefore, a call to FunInfoGet() should be made after the call to FunImageGet(), in order to retrieve the updated bitpix value. See the imblank example code for more details.

It also can be useful to retrieve the World Coordinate System information from the Funtools structure. Funtools uses the the \s-1WCS\s0 Library developed by Doug Mink at \s-1SAO\s0, which is available here. (More information about the WCSTools project in general can be found here.) The FunOpen() routine initializes two \s-1WCS\s0 structures that can be used with this \s-1WCS\s0 Library. Applications can retrieve either of these two \s-1WCS\s0 structures using FunInfoGet():

The structure retrieved by \s-1FUN_WCS\s0 is a \s-1WCS\s0 library handle containing parameters suitable for use with image coordinates, regardless of whether the data are images or tables. For this structure, the \s-1WCS\s0 reference point (\s-1CRPIX\s0) has been converted to image coordinates if the underlying file is a table (and therefore in physical coordinates). You therefore must ensure that the positions being passed to a routine like pix2wcs are in image coordinates. The \s-1FUN_WCS0\s0 structure has not had its \s-1WCS\s0 reference point converted to image coordinates. It therefore is useful when passing processing physical coordinates from a table.

Once a \s-1WCS\s0 structure has been retrieved, it can be used as the first argument to the \s-1WCS\s0 library routines. (If the structure is \s-1NULL\s0, no \s-1WCS\s0 information was contained in the file.) The two important \s-1WCS\s0 routines that Funtools uses are:

which converts sky coordinates to pixel coordinates. Again, please note that the wcs structure returned by \s-1FUN_WCS\s0 assumes that image coordinates are passed to the pix2wcs routine, while \s-1FUN_WCS0\s0 assumes that physical coordinates are passed.

Note that funtools.h file automatically includes wcs.h. An example program that utilizes these \s-1WCS\s0 structure to call \s-1WCS\s0 Library routines is twcs.c.

The following is the complete list of information that can be returned:

Row applications would not normally need any of this information. An example of how these values can be used in more complex programs is the evnext example code. In this program, the time value for each row is changed to be the value of the succeeding row. The program thus reads the time values for a batch of rows, changes the time values to be the value for the succeeding row, and then merges these changed time values back with the other columns to the output file. It then reads the next batch, etc.

This does not work for the last row read in each batch, since there is no succeeding row until the next batch is read. Therefore, the program saves that last row until it has read the next batch, then processes the former before starting on the new batch. In order to merge the last row successfully, the code uses \s-1FUN_RAWBUF\s0 to save and restore the raw input data associated with each batch of rows. Clearly, this requires some information about how funtools works internally. We are happy to help you write such programs as the need arises.