[fitsbits] Funtools 1.0.0 is available
eric at head-cfa.harvard.edu
eric at head-cfa.harvard.edu
Tue Jul 31 10:19:38 EDT 2001
******************************************************************************
Funtools: FITS Users Need Tools
Public Release 1.0
31 July 2001
from the folks at the SAO/HEAD R&D Group
http://hea-www.harvard.edu/RD
Summary
-------
We are pleased to announce the availability of the first public
release (version 1.0) of Funtools, a "minimal buy-in" FITS library and
utility package from the SAO/HEAD R&D group. The Funtools library
provides simplified access to FITS images and binary tables, as well
as to raw array and binary event lists. The Funtools utilities provide
high-level support for processing astronomical data. More information
about Funtools is available at our Web site:
http://hea-www.harvard.edu/RD/funtools
Description
-----------
The main goal of the Funtools project has been to develop a minimal buy-in
FITS library for researchers who are occasional (but serious) coders. In
this case, "minimal buy-in" means "easy to learn, easy to use, and easy to
re-learn next month". We have tried to achieve this goal by emphasizing two
essential capabilities. The first is the ability to develop FITS programs
without knowing much about FITS, i.e., without having to deal with the
arcane rules for generating a properly formatted FITS file. The second is
to support the use of already-familiar C/Unix facilities, especially C
structs and Unix stdio. Taken together, these two capabilities should allow
researchers to leverage their existing programming expertise while
minimizing the need to learn new and complex coding rules.
Our basic design approach is to minimize the number of public subroutines in
the Funtools library. This approach is based on the hypothesis that a few
carefully crafted routines would be easy to learn, easy to remember, and
easy to use by occasional coders. In other words, we have sought to make it
easier to "see the forest for the trees" by minimizing the number of trees.
Our implementation strategy is centered on perfecting the code needed by a
few essential image and table processing algorithms. For example, in X-ray
astronomy, the canonical X-ray analysis task processes rows of photon events
in FITS binary tables: for each X-ray event (row in a binary table), read
selected input columns into user space, modify the value of one or more of
these columns, and output the results by merging the new value(s) with the
original input columns. The Funtools library implements this standard X-ray
event-processing algorithm in a simple and straightforward manner:
Fun ifun, ofun;
typedef struct eventrec{
int pha, energy;
} *Ev, EvRec;
ifun = FunOpen("in.fits[EV+,pha=5:9||pha==pi]", "rc", NULL);
ofun = FunOpen("out.fits", "w", ifun);
FunColumnSelect(ifun, sizeof(EvRec), "merge=update",
"pha", "J", "r", FUN_OFFSET(Ev, pha),
"energy", "J", "rw", FUN_OFFSET(Ev, energy), NULL);
while( (ebuf=(Ev)FunTableRowGet(ifun, NULL, MAXEV, NULL, &nev)) ){
for(i=0; i<nev; i++){
ev = ebuf + i;
/* process this event */
if( ev->pha == XXX ) ev->energy = NewPHA(ev->pha);
}
FunTableRowPut(ofun, ebuf, nev, 0, NULL); free(ebuf);
}
FunClose(ofun); FunClose(ifun);
A similar set of routines supports FITS image and raw array processing:
Fun ifun, ofun;
ifun = FunOpen("in.fits", "rc", NULL);
ofun = FunOpen("out.fits", "w", ifun);
buf = FunImageGet(fun, NULL, "bitpix=-32");
FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0);
for(j=0; j<dim2; j++){
for(i=0; i<dim1; i++){
/* process pixel i,j */
if ( buf[(j*dim1)+i] < BVAL ) buf[(j*dim1)+i] = 0;
}
}
FunImagePut(ofun, buf, 0, 0, 0, NULL);
FunClose(ofun); FunClose(ifun);
In both case, much of the complexity of dealing with FITS is hidden. FITS
headers and extension padding are written automatically as needed. Output
files easily inherit input parameters and other information. Copy of input
extensions is specified easily on the command line.
Filtering Capabilities
----------------------
With the Funtools library, events in FITS Binary tables and raw event files
can be filtered or selected based on a flexible set of user-specified
criteria that allows column values to be compared with numeric values,
header parameters, functions, or other column values.
To filter events and spatial regions, the filter specification is added to
the FITS filename using bracket notation:
foo.fits[pha==1&&pi==2&&circle(512,512,10)]
The filter specification comes after the extension and image sections and
optionally may be enclosed in its own set of brackets. Thus:
foo.fits[EVENTS,400:599,400:599,pha==1&&pi==2&&circle(512,512,10)]
and
foo.fits[BKGD][400:599,400:599][circle(512,512,10)]
specify filters on an image section of size 200x200 defined on the FITS
EVENTS (binary table) and BKGD (image) extensions.
In addition to filtering columns of binary tables, the Funtools library also
can filter both events and images using spatial region specifiers. Spatial
region filtering allows a program to select regions of an image or event
list to process using simple geometric shapes and boolean combinations of
shapes. When an image is filtered, only pixels found within these shapes
are processed. When an event list is filtered, only events found within
these shapes are processed.
Analysis Tools
--------------
The following analysis programs have been developed as part of the
Funtools package:
funcalc - Funtools calculator (for binary tables)
funcnts - count photons in specified regions, with bkgd subtraction
fundisp - display data in a Funtools data file
funhead - display a header in a Funtools file
funhist - create a 1D histogram (from a FITS binary table or image)
funimage - create a FITS image from a Funtools data file
funmerge - merge one or more Funtools table files
funtable - copy selected rows from a Funtools file to a FITS binary table
Of these, the most scientifically interesting task is funcnts, which counts
the number of photons in user-specified regions. Using funcnts with annular
regions, for example, generates a radial profile, with optional background
subtraction (from a region in the same file or a different file) and/or
exposure correction:
funcnts foo.fits "annulus 504 512 0 10 n=5" "ann 504 512 10 20"
Compatibility with DS9
----------------------
SAOImage/DS9 is an astronomical imaging and data visualization application
used by astronomers around the world. DS9 can display standard astronomical
FITS images and binary tables, but also has support for displaying raw array
files, shared memory files, and data files automatically retrieved via FTP
and HTTP. Standard functional capabilities include multiple frame buffers,
colormap and region manipulation, and many data scaling algorithms. DS9's
advanced features include TrueColor visuals, deep frame buffers, true
PostScript printing, and display of image mosaics. More information about
DS9 can be found at our Web site: http://hea-www.harvard.edu/RD/ds9.
Funtools is designed to be fully compatible with DS9. In particular,
the Funtools region syntax is the default region syntax for DS9. Thus,
regions generated interactively in DS9 can be used as spatial filters
in Funtools programs.
In addition, Funtools programs can be integrated directly into the DS9 GUI
and executed directly from the DS9 Analysis menu. The Funtools source tar
file comes with a DS9 set-up file called funtools.ds9 that will
automatically load useful Funtools applications into DS9. These include:
counts in regions, radial profile, X-ray light curve and energy spectrum,
and 1D histogram. The ability to execute radial profile plots directly from
DS9 has proven to be a great boon to users. We will be developing this
capability further in the months ahead.
Availability
------------
Funtools has been ported to Sun Solaris, Linux, SGI, DEC Alpha, and Windows
95/98/NT/2000/ME (requires Cygwin). The Funtools source code is available
for download (as a gzip'ed tar file) from our Web site:
http://hea-www.harvard.edu/RD/funtools
More information about Funtools also is available at our Web site.
Alternatively, Funtools can be retrieved directly via anonymous ftp from
sao-ftp.harvard.edu in the pub/rd/funtools-1.0 directory.
Acknowledgments
----------------
Work on Funtools was performed under a grant from NASA's Applied Information
System Research Program (NAG5-9484), with support from the Chandra High
Resolution Camera (NAS8-38248), the Chandra X-ray Science Center (NAS8-39073),
and the CXO Telescope Scientist (NAG8-1607).
SAOtng Mailing List
-------------------
An saord mailing list (saord-announce) have been set up using Brent
Chapman's "Majordomo" mailing list manager. Subscribers to this list will
receive periodic status reports, release notices, and other useful
information concerning SAORD software such as Funtools. If you wish to
become a subscriber, please send an e-mail message to:
majordomo at head-cfa.harvard.edu
The mail should contain the following command in the body of the
message:
subscribe saord-announce
If either you or your mailer add a signature to your mail message, please
add the following command after the "subscribe" command(s):
end
For more information (or to complain or encourage!)
---------------------------------------------------
Please send mail to: saord at cfa.harvard.edu. We respond to questions, bug
reports, suggestions, gripes, and encouragement ...
Eric Mandel
eric at cfa.harvard.edu
*******************************************************************************
More information about the fitsbits
mailing list