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:

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.

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 rowfilter help file.

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.

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:

SEE ALSO

filenames, pixfilter, colfilter, rowfilter, binfilter. calc_express.