CFITSIO's Extended Filename Syntax
These examples illustrate the various types of input file names that are
supported by CFITSIO. The filters, enclosed in square brackets, can be
use to modify the raw file in various ways before it is opened and read
by the application program. A complete description of the syntax can
be found in the
User's Guides in the Extended File Name Syntax chapter.
'myfile.fits': the simplest case of a FITS file on disk in the current
'myfile.imh': converts the IRAF format image file
into a temporary FITS format image in memory which is then opened
and passed to the application program.
'rawfile.dat[i512,512]': reads raw binary data array (a 512x512 short
integer array in this case) and converts it on the fly into a temporary
FITS image in memory which is then opened by the application program.
'outfile.fits.gz': if this is the name of an output FITS file
then the `.gz' suffix will cause it to be compressed
in gzip format when CFITSIO closes the file and writes it to disk.
'outfile.fits[compress]': if this is the name of an output FITS file
then the [compress] qualifier indicates that any images written to
the file (in the primary array or IMAGE extensions) should be written
in the tile-compressed format, using the default compression parameters
(compressed row by row, using the Rice compression algorithm).
'infile.fits.gz[events, 2]': opens and uncompresses the gzipped input file
infile.fits then moves to the extension that has the keywords EXTNAME
= 'EVENTS' and EXTVER = 2.
'-': a dash (minus sign) signifies that the input file is to be read
from the stdin file stream, or that the output file is to be written to
the stdout stream.
'ftp://legacy.gsfc.nasa.gov/test/vela.fits': FITS files in any ftp
archive site on the internet may be opened with read-only
access. Files with HTTP addresses may be opened in the same way.
'myimage.fits[1:40:2, 1:60:2]': reads and opens a subsection of an
image (select every other pixel in this case, resulting in a 20x30 pixel
image that gets opened by the application program).
'myimage.fits[-*,*]': opens the whole 2D image, reversing the order
of the pixels along the first (horizontal) axis.
'mem://': creates a scratch output file in computer memory. The
resulting 'file' is deleted when the program exits, so this
is mainly useful for testing purposes when one does not want a
permanent copy of the output file.
'myfile.fits[EVENTS][col Rad = sqrt(X**2 + Y**2)]': creates and opens
a temporary file (in memory or on disk) that is identical to
myfile.fits except it contains a new column in the EVENTS
extension called 'Rad' whose value is computed using the indicated
expresson which is a function of the values in the X and Y columns.
'myfile.fits[EVENTS][PHA > 5]': creates and opens a temporary FITS
files that is identical to 'myfile.fits' except that the EVENTS table
will only contain the rows that have values of the PHA column greater
than 5. In general, any arbitrary boolean expression using a C or
Fortran-like syntax, which may combine AND and OR operators,
may be used to select rows from a table. GTI and regions files may
also be use to select rows from the table.
'myfile.fits[EVENTS][bin (X,Y)=1,2048,4]': creates a temporary FITS
primary array image by binning (i.e,
computing the 2-dimensional histogram) of the values in the X and Y
columns of the EVENTS extension.
In this case the X and Y coordinates
range from 1 to 2048 and the image pixel size is 4 units in both
dimensions, so the resulting image is 512 x 512 pixels in size.
The column creation, row selection, and column histogramming filters
may all be combined into more complex cases.
Return to the FITSIO
FITSIO is maintained by:
Dr. William D. Pence,
(email: pence 'at' milkyway.gsfc.nasa.gov)