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.