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 directory.

• '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://heasarc.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 home page.