5.3 Image Filtering

5.3.1 Extracting a subsection of an image

When specifying the name of an image to be opened, you can select a rectangular subsection of the image to be extracted and opened by the application program. The application program then opens a virtual image that only contains the pixels within the specified subsection. To do this, specify the the range of pixels (start:end) along each axis to be extracted from the original image enclosed in square brackets. You can also specify an optional pixel increment (start:end:step) for each axis of the input image. A pixel step = 1 will be assumed if it is not specified. If the starting pixel is larger then the end pixel, then the image will be flipped (producing a mirror image) along that dimension. An asterisk, '*', may be used to specify the entire range of an axis, and '-*' will flip the entire axis. In the following examples, assume that myfile.fits contains a 512 x 512 pixel 2D image.

  myfile.fits[201:210, 251:260] - opens a 10 x 10 pixel subimage.

  myfile.fits[*, 512:257] - opens a 512 x 256 image consisting of
	      all the columns in the input image, but only rows 257
	      through 512.  The image will be flipped along the Y axis
	      since the starting row is greater than the ending
	      row.

  myfile.fits[*:2, 512:257:2] - creates a 256 x 128 pixel image.
	      Similar to the previous example, but only every other row
	      and column is read from the input image.

  myfile.fits[-*, *] - creates an image containing all the rows and
	      columns in the input image, but flips it along the X
	      axis.

If the array to be opened is in an Image extension, and not in the primary array of the file, then you need to specify the extension name or number in square brackets before giving the subsection range, as in myfile.fits[1][-*, *] to read the image in the first extension in the file.

5.3.2 Create an Image by Binning Table Columns

You can also create and open a virtual image by binning the values in a pair of columns of a FITS table (in other words, create a 2-D histogram of the values in the 2 columns). This technique is often used in X-ray astronomy where each detected X-ray photon during an observation is recorded in a FITS table. There are typically 2 columns in the table called X and Y which record the pixel location of that event in a virtual 2D image. To create an image from this table, one just scans the X and Y columns and counts up how many photons were recorded in each pixel of the image. When table binning is specified, CFITSIO creates a temporary FITS primary array in memory by computing the histogram of the values in the specified columns. After the histogram is computed the original FITS file containing the table is closed and the temporary FITS primary array is opened and passed to the application program. Thus, the application program never sees the original FITS table and only sees the image in the new temporary file (which has no extensions).

The table binning specifier is enclosed in square brackets following the root filename and table extension name or number and begins with the keyword 'bin', as in:
'myfile.fits[events][bin (X,Y)]'. In this case, the X and Y columns in the 'events' table extension are binned up to create the image. The size of the image is usually determined by the TLMINn and TLMAXn header keywords which give the minimum and maximum allowed pixel values in the columns. For instance if TLMINn = 1 and TLMAXn = 4096 for both columns, this would generate a 4096 x 4096 pixel image by default. This is rather large, so you can also specify a pixel binning factor to reduce the image size. For example specifying , '[bin (X,Y) = 16]' will use a binning factor of 16, which will produce a 256 x 256 pixel image in the previous example.

If the TLMIN and TLMAX keywords don't exist, or you want to override their values, you can specify the image range and binning factor directly, as in '[bin X = 1:4096:16, Y=1:4096:16]'. You can also specify the datatype of the created image by appending a b, i, j, r, or d (for 8-bit byte, 16-bit integers, 32-bit integer, 32-bit floating points, or 64-bit double precision floating point, respectively) to the 'bin' keyword (e.g. '[binr (X,Y)]' creates a floating point image). If the datatype is not specified then a 32-bit integer image will be created by default.

If the column name is not specified, then CFITSIO will first try to use the 'preferred column' as specified by the CPREF keyword if it exists (e.g., 'CPREF = 'DETX,DETY'), otherwise column names 'X', 'Y' will be assumed for the 2 axes.

Note that this binning specifier is not restricted to only 2D images and can be used to create 1D, 3D, or 4D images as well. It is also possible to specify a weighting factor that is applied during the binning. Please refer to the “CFITSIO User's Reference Guide” for more details on these advanced features.