Image Filtering Syntax
All of the ftools and HEADAS tasks support CFITSIO's extended file name
syntax when specifying the names of input or output data files. This
document describes the types of filters that can be applied to FITS images,
i.e., to 1-D, 2-D, 3-D, or higher dimensional arrays of data stored in
the FITS Primary Array or an IMAGE extension.
1. Extracting a Subsection Out of a Larger Image
When entering the file name of a FITS image that is to be opened by an
application program, a subsection filter may be appended to the root
name of the file, enclosed in square brackets. The subsection filter
defines the pixel boundaries, and optional pixel increment, of the
subimage that is to be extracted from the larger input FITS image.
CFITSIO creates a new virtual image (usually in memory) that contains
only these extracted pixels. The application program then opens and
reads this virtual image.
When constructing the virtual subimage, CFITSIO automatically modifies
the values of the World Coordinate System (WCS) keywords, if they
exist, so that the coordinates (i.e., the RA and DEC) that are derived
for the subimage pixels are the same as in the original image. CFITSIO
also copies any other FITS extensions (also called HDUs) that are
present in the input file to the virtual file. Note that CFITSIO will
only allow the virtual file to be opened with readonly access because
the file only exists temporarily in memory and any modifications by the
application program would be lost when the file is closed.
The general syntax for the subsection filter is:
[start:end:incr, start:end:incr, ... ]
where 'start' gives
the number of the first pixel (counting from 1, not 0) and 'end' gives
the number of the last pixel to be included in the subsection. The
'incr' argument is optional and specifies the pixel increment between
the extracted pixels; a value of 1 is assumed if it is not specified.
This set of integers must be repeated for each axis of the image,
separated by a comma.
If the starting pixel number is larger than the ending pixel number
then the virtual image will be reversed along that axis (thus creating
a mirror image of the actual input image). The '*' symbol
also may be substituted instead of the start and end pixel numbers to
indicate that the entire range of pixels along that image axis should
be extracted to the virtual image, and '-*' indicates that the
entire range of pixels should reversed to create a mirror image.
Note that if the image that is to be opened is not located in the
primary array of the input file, but is instead in an IMAGE extension,
then it may be necessary to specify the extension name or number within
square brackets before the subset filter. This is not always necessary
however because most HEADAS application programs are designed to
automatically move to and open the first non-null image in the input
file if an explicit extension is not specified.
Example subsection filters
Note that the subsection filter must be enclosed in single or
double quotes when it is entered on the Unix command line.
This extracts a 10 x 10 pixel subimage from the input image.
Extracts the first 500 pixels from a 1-D array.
Opens the image contained in the 3rd extension following the
primary array and extracts only the odd numbered pixels from 1 to 99
in both dimensions.
Extract the first 500 pixels in each dimension, reversing the order
of the pixels along the first axis (X axis).
Extracts the odd numbered pixels from the entire 2D image.
Creates a mirror image of the input image by reversing the order of the
pixels along the X axis.
2. Extracting a Vector Table Element as an Image
FITS images are most commonly stored in the primary array or in an
IMAGE extension, but images can also be stored as a vector in a single
cell of a binary table (i.e. each row of the vector column contains a
different image). In this case the TDIMn keyword is used to give the
size of the dimensions of the image. Such an image can be opened with
CFITSIO by specifying the desired column name and the row number after
the binary table HDU specifier as shown in the following examples. The
column name is separated from the HDU specifier by a semicolon, and the
row number is enclosed in parentheses. CFITSIO copies the vector from
the table cell into a temporary virtual FITS primary array constructed
in memory. The virtual file that the application program opens
only contains this primary array image, without any extensions.
The particular row to be opened may be specified either by giving an
absolute integer row number (starting with 1 for the first row), or by
specifying a boolean expression that evaluates to TRUE for the desired
row. The first row that satisfies the expression will be used. The
row selection expression has the same syntax as described in the
Examples of table element images:
Note that the filter must be enclosed in single or
double quotes when it is entered on the Unix command line.
opens the image in row 17 of the 'images' column in the binary table
that is contained in the 3rd extension of the file.
- myfile.fits[3; images(exposure > 100)]
as above, but opens the image
in the first row that has an 'exposure' column value
greater than 100.
3. Creating a Virtual Histogram Image by Binning Table Columns
A virtual FITS image can be constructed by binning the values in one or
more table columns. In X-ray data analysis this is most commonly done
to bin the 'X' and 'Y' columns in an event table to generate a 2D image
of the X-ray sources on the sky. Refer to the binfilter help file for more details of the binning filter syntax. A few examples are shown below:
myfile.fits[events][bin (X,Y) = 16]
generates a 2D image by binning the X and Y columns in the 'EVENTS' table
extension, using a bin size of 16 pixels in both dimensions.
myfile.fits[events][bin time = 16000:20000:1]
generates a 1D light curve by binning the TIME column over the range of TIME = 16000 to TIME = 20000, using 1 second bins.