diff options
Diffstat (limited to 'vendor/cfitsio/quick.tex')
| -rw-r--r-- | vendor/cfitsio/quick.tex | 2159 |
1 files changed, 2159 insertions, 0 deletions
diff --git a/vendor/cfitsio/quick.tex b/vendor/cfitsio/quick.tex new file mode 100644 index 00000000..109d04e1 --- /dev/null +++ b/vendor/cfitsio/quick.tex @@ -0,0 +1,2159 @@ +\documentclass[11pt]{article} +\input{html.sty} +\htmladdtonavigation + {\begin{rawhtml} + <A HREF="http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html">FITSIO Home</A> + \end{rawhtml}} + +\oddsidemargin=0.20in +\evensidemargin=0.20in +\textwidth=15.5truecm +\textheight=21.5truecm + +\title{CFITSIO Quick Start Guide} +\author{William Pence \thanks{HEASARC, NASA Goddard Space Flight Center, +{\it William.D.Pence@nasa.gov}}} + +\date{January 2003} + +\begin{document} + +\maketitle +\tableofcontents + +% =================================================================== +\section{Introduction} + +This document is intended to help you quickly start writing C programs +to read and write FITS files using the CFITSIO library. It covers the +most important CFITSIO routines that are needed to perform most types +of operations on FITS files. For more complete information about these +and all the other available routines in the library please refer to +the ``CFITSIO User's Reference Guide'', which is available from the +CFITSIO Web site at {\tt http://heasarc.gsfc.nasa.gov/fitsio}. + +For more general information about the FITS data format, refer to the +following web page: +http://heasarc.gsfc.nasa.gov/docs/heasarc/fits.html + +FITS stands for Flexible Image Transport System and is the standard +file format used to store most astronomical data files. There are 2 +basic types of FITS files: images and tables. FITS images often +contain a 2-dimensional array of pixels representing an image of a +piece of the sky, but FITS images can also contain 1-D arrays (i.e, +a spectrum or light curve), or 3-D arrays (a data cube), or +even higher dimensional arrays of data. An image may also have zero +dimensions, in which case it is referred to as a null or empty array. +The supported datatypes for the image arrays are 8, 16, and 32-bit +integers, and 32 and 64-bit floating point real numbers. Both signed +and unsigned integers are supported. + +FITS tables contain rows and columns of data, similar to a +spreadsheet. All the values in a particular column must have the same +datatype. A cell of a column is not restricted to a single number, and +instead can contain an array or vector of numbers. There are actually +2 subtypes of FITS tables: ASCII and binary. As the names imply, ASCII +tables store the data values in an ASCII representation whereas binary +tables store the data values in a more efficient machine-readable +binary format. Binary tables are generally more compact and support +more features (e.g., a wider range of datatypes, and vector columns) +than ASCII tables. + +A single FITS file many contain multiple images or tables. Each table +or image is called a Header-Data Unit, or HDU. The first HDU in a FITS +file must be an image (but it may have zero axes) and is called the +Primary Array. Any additional HDUs in the file (which are also +referred to as `extensions') may contain either an image or a table. + +Every HDU contains a header containing keyword records. Each keyword +record is 80 ASCII characters long and has the following format: + +\begin{verbatim} +KEYWORD = value / comment string +\end{verbatim} + +The keyword name can be up to 8 characters long (all uppercase). The +value can be either an integer or floating point number, a logical +value (T or F), or a character string enclosed in single quotes. Each +header begins with a series of required keywords to describe the +datatype and format of the following data unit, if any. Any number of +other optional keywords can be included in the header to provide other +descriptive information about the data. For the most part, the CFITSIO +routines automatically write the required FITS keywords for each HDU, +so you, the programmer, usually do not need to worry about them. + +% =================================================================== +\section{Installing and Using CFITSIO} + +First, you should download the CFITSIO software and the set of example +FITS utility programs from the web site at +http://heasarc.gsfc.nasa.gov/fitsio. The example programs illustrate +how to perform many common types of operations on FITS files using +CFITSIO. They are also useful when writing a new program because it is +often easier to take a copy of one of these utility programs as a +template and then modify it for your own purposes, rather than writing +the new program completely from scratch. + +To build the CFITSIO library on Unix platforms, `untar' the source code +distribution file and then execute the following commands in the +directory containing the source code: + +\begin{verbatim} +> ./configure [--prefix=/target/installation/path] +> make (or 'make shared') +> make install (this step is optional) +\end{verbatim} + +The optional +'prefix' argument to configure gives the path to the directory where +the CFITSIO library and include files should be installed via the later +'make install' command. For example, + +\begin{verbatim} +> ./configure --prefix=/usr1/local +\end{verbatim} + +will cause the 'make install' command to copy the CFITSIO libcfitsio file +to /usr1/local/lib and the necessary include files to /usr1/local/include +(assuming of course that the process has permission to write to these +directories). + +Pre-compiled versions of the CFITSIO DLL library are available for +PCs. On Macintosh machines, refer to the README.MacOS file for +instructions on building CFITSIO using CodeWarrior. + +Any programs that use CFITSIO must of course be linked with the CFITSIO +library when creating the executable file. The exact procedure for +linking a program depends on your software environment, but on Unix +platforms, the command line to compile and link a program will look +something like this: + +\begin{verbatim} +gcc -o myprog myprog.c -L. -lcfitsio -lm -lnsl -lsocket +\end{verbatim} + +You may not need to include all of the 'm', 'nsl', and 'socket' system +libraries on your particular machine. To find out what libraries are +required on your (Unix) system, type {\tt'make testprog'} and see what +libraries are then included on the resulting link line. + +\newpage +% =================================================================== +\section{Example Programs} + +Before describing the individual CFITSIO routines in detail, it is +instructive to first look at an actual program. The names of the +CFITSIO routines are fairly descriptive (they all begin with {\tt +fits\_}, so it should be reasonably clear what this program does: + +\begin{verbatim} +---------------------------------------------------------------- + #include <string.h> + #include <stdio.h> +1: #include "fitsio.h" + + int main(int argc, char *argv[]) + { +2: fitsfile *fptr; + char card[FLEN_CARD]; +3: int status = 0, nkeys, ii; /* MUST initialize status */ + +4: fits_open_file(&fptr, argv[1], READONLY, &status); + fits_get_hdrspace(fptr, &nkeys, NULL, &status); + + for (ii = 1; ii <= nkeys; ii++) { + fits_read_record(fptr, ii, card, &status); /* read keyword */ + printf("%s\n", card); + } + printf("END\n\n"); /* terminate listing with END */ + fits_close_file(fptr, &status); + + if (status) /* print any error messages */ +5: fits_report_error(stderr, status); + return(status); + } +---------------------------------------------------------------- +\end{verbatim} + +This program opens the specified FITS file and prints +out all the header keywords in the current HDU. +Some other points to notice about the program are: +\begin{enumerate} + +\item +The {\tt fitsio.h} header file must be included to define the +various routines and symbols used in CFITSIO. + +\item + +The {\tt fitsfile} parameter is the first argument in almost every +CFITSIO routine. It is a pointer to a structure (defined in {\tt +fitsio.h}) that stores information about the particular FITS file that +the routine will operate on. Memory for this structure is +automatically allocated when the file is first opened or created, and +is freed when the file is closed. + +\item +Almost every CFITSIO routine has a {\tt status} parameter as the last +argument. The status value is also usually returned as the value of the +function itself. Normally status = 0, and a positive status value +indicates an error of some sort. The status variable must always be +initialized to zero before use, because if status is greater than zero +on input then the CFITSIO routines will simply return without doing +anything. This `inherited status' feature, where each CFITSIO routine +inherits the status from the previous routine, makes it unnecessary to +check the status value after every single CFITSIO routine call. +Generally you should check the status after an especially important or +complicated routine has been called, or after a block of +closely related CFITSIO calls. This example program has taken this +feature to the extreme and only checks the status value at the +very end of the program. + +\item + +In this example program the file name to be opened is given as an +argument on the command line ({\tt arg[1]}). If the file contains more +than 1 HDU or extension, you can specify which particular HDU to be +opened by enclosing the name or number of the HDU in square brackets +following the root name of the file. For example, {\tt file.fts[0]} +opens the primary array, while {\tt file.fts[2]} will move to and open +the 2nd extension in the file, and {\tt file.fit[EVENTS]} will open the +extension that has a {\tt EXTNAME = 'EVENTS'} keyword in the header. +Note that on the Unix command line you must enclose the file name in +single or double quote characters if the name contains special +characters such as `[' or `]'. + +All of the CFITSIO routines which read or write header keywords, +image data, or table data operate only within the currently opened +HDU in the file. To read or write information in a different HDU you must +first explicitly move to that HDU (see the {\tt fits\_movabs\_hdu} and +{\tt fits\_movrel\_hdu} routines in section 4.3). + +\item + +The {\tt fits\_report\_error} routine provides a convenient way to print out +diagnostic messages about any error that may have occurred. + +\end{enumerate} + +A set of example FITS utility programs are available from the CFITSIO +web site at \newline +http://heasarc.gsfc.nasa.gov/docs/software/fitsio/cexamples.html. +These are real working programs which illustrate how to read, write, +and modify FITS files using the CFITSIO library. Most of these +programs are very short, containing only a few 10s of lines of +executable code or less, yet they perform quite useful operations on +FITS files. Running each program without any command line arguments +will produce a short description of how to use the program. +The currently available programs are: +\begin{quote} +fitscopy - copy a file +\newline +listhead - list header keywords +\newline +liststruc - show the structure of a FITS file. +\newline +modhead - write or modify a header keyword +\newline +imarith - add, subtract, multiply, or divide 2 images +\newline +imlist - list pixel values in an image +\newline +imstat - compute mean, min, and max pixel values in an image +\newline +tablist - display the contents of a FITS table +\newline +tabcalc - general table calculator +\end{quote} + +\newpage + +% =================================================================== +\section{CFITSIO Routines} + +This chapter describes the main CFITSIO routines that can be used to +perform the most common types of operations on FITS files. + +% =================================================================== +{\bf \subsection{Error Reporting}} + +\begin{verbatim} +void fits_report_error(FILE *stream, int status) +void fits_get_errstatus(int status, char *err_text) +float fits_get_version(float *version) +\end{verbatim} + +The first routine prints out information about any error that +has occurred. Whenever any CFITSIO routine encounters an error it +usually writes a message describing the nature of the error to an +internal error message stack and then returns with a positive integer +status value. Passing the error status value to this routine will +cause a generic description of the error and all the messages +from the internal CFITSIO error stack to be printed to the specified +stream. The {\tt stream} parameter is usually set equal to +{\tt "stdout"} or {\tt "stderr"}. + +The second routine simply returns a 30-character descriptive +error message corresponding to the input status value. + +The last routine returns the current CFITSIO library version number. + +% =================================================================== +{\bf \subsection{File Open/Close Routines}} + +\begin{verbatim} +int fits_open_file( fitsfile **fptr, char *filename, int mode, int *status) +int fits_open_data( fitsfile **fptr, char *filename, int mode, int *status) +int fits_open_table(fitsfile **fptr, char *filename, int mode, int *status) +int fits_open_image(fitsfile **fptr, char *filename, int mode, int *status) + +int fits_create_file(fitsfile **fptr, char *filename, int *status) +int fits_close_file(fitsfile *fptr, int *status) +\end{verbatim} + +These routines open or close a file. The first {\tt fitsfile} +parameter in these and nearly every other CFITSIO routine is a pointer +to a structure that CFITSIO uses to store relevant parameters about +each opened file. You should never directly read or write any +information in this structure. Memory for this structure is allocated +automatically when the file is opened or created, and is freed when the +file is closed. + +The {\tt mode} parameter in the {\tt fits\_open\_xxxx} set of routines +can be set to either {\tt READONLY} or {\tt READWRITE} to select the +type of file access that will be allowed. These symbolic constants are +defined in {\tt fitsio.h}. + +The {\tt fits\_open\_file} routine opens the file and positions the internal +file pointer to the beginning of the file, or to the specified +extension if an extension name or number is appended to the file name +(see the later section on ``CFITSIO File Names and Filters'' for a +description of the syntax). {\tt fits\_open\_data} behaves similarly except +that it will move to the first HDU containing significant data if a HDU +name or number to open is not explicitly specified as part of the +filename. It will move to the first IMAGE HDU with NAXIS greater than +0, or the first table that does not contain the strings `GTI' (a Good +Time Interval extension) or `OBSTABLE' in the EXTNAME keyword value. +The {\tt fits\_open\_table} and {\tt fits\_open\_image} routines are similar +except that they will move to the first significant table HDU or image +HDU, respectively if a HDU name of number is not specified as part of +the input file name. + +When opening an existing file, the {\tt filename} can include optional +arguments, enclosed in square brackets that specify filtering +operations that should be applied to the input file. For example, +\begin{verbatim} + myfile.fit[EVENTS][counts > 0] +\end{verbatim} +opens the table in the EVENTS extension and creates a virtual table by +selecting only those rows where the COUNTS column value is greater than +0. See section 5 for more examples of these powerful filtering +capabilities. + +In {\tt fits\_create\_file}, the {\tt filename} is simply the root name of +the file to be created. You can overwrite an existing file by +prefixing the name with a `!' character (on the Unix command line this +must be prefixed with a backslash, as in \verb+`\!file.fit'+). +If the file name ends with {\tt .gz} the file will be compressed +using the gzip algorithm. If the +filename is {\tt stdout} or {\tt "-"} (a single dash character) +then the output file will be piped to the stdout stream. You can +chain several tasks together by writing the output from the first task +to {\tt stdout} and then reading the input file in the 2nd task from +{\tt stdin} or {\tt "-"}. + + +% =================================================================== +{\bf \subsection{HDU-level Routines}} + +The routines listed in this section operate on Header-Data Units (HDUs) in a file. + +\begin{verbatim} +_______________________________________________________________ +int fits_get_num_hdus(fitsfile *fptr, int *hdunum, int *status) +int fits_get_hdu_num(fitsfile *fptr, int *hdunum) +\end{verbatim} + +The first routines returns the total number of HDUs in the FITS file, +and the second routine returns the position of the currently opened HDU in +the FITS file (starting with 1, not 0). + +\begin{verbatim} +__________________________________________________________________________ +int fits_movabs_hdu(fitsfile *fptr, int hdunum, int *hdutype, int *status) +int fits_movrel_hdu(fitsfile *fptr, int nmove, int *hdutype, int *status) +int fits_movnam_hdu(fitsfile *fptr, int hdutype, char *extname, + int extver, int *status) +\end{verbatim} + +These routines enable you to move to a different HDU in the file. +Most of the CFITSIO functions which read or write keywords or data +operate only on the currently opened HDU in the file. The first +routine moves to the specified absolute HDU number in the FITS +file (the first HDU = 1), whereas the second routine moves a relative +number of HDUs forward or backward from the currently open HDU. The +{\tt hdutype} parameter returns the type of the newly opened HDU, and will +be equal to one of these symbolic constant values: {\tt IMAGE\_HDU, +ASCII\_TBL, or BINARY\_TBL}. {\tt hdutype} may be set to NULL +if it is not needed. The third routine moves to the (first) HDU +that matches the input extension type, name, and version number, +as given by the {\tt XTENSION, EXTNAME} (or {\tt HDUNAME}) and {\tt EXTVER} keywords. +If the input value of {\tt extver} = 0, then the version number will +be ignored when looking for a matching HDU. + +\begin{verbatim} +_________________________________________________________________ +int fits_get_hdu_type(fitsfile *fptr, int *hdutype, int *status) +\end{verbatim} + +Get the type of the current HDU in the FITS file: {\tt IMAGE\_HDU, +ASCII\_TBL, or BINARY\_TBL}. + +\begin{verbatim} +____________________________________________________________________ +int fits_copy_hdu(fitsfile *infptr, fitsfile *outfptr, int morekeys, + int *status) +int fits_copy_file(fitsfile *infptr, fitsfile *outfptr, int previous, + int current, int following, > int *status) +\end{verbatim} + +The first routine copies the current HDU from the FITS file associated +with infptr and appends it to the end of the FITS file associated with +outfptr. Space may be reserved for {\tt morekeys} additional keywords +in the output header. The second routine copies any HDUs previous +to the current HDU, and/or the current HDU, and/or any HDUs following the +current HDU, depending on the value (True or False) of {\tt previous, +current}, and {\tt following}, respectively. For example, +\begin{verbatim} + fits_copy_file(infptr, outfptr, 0, 1, 1, &status); +\end{verbatim} +will copy the current HDU and any HDUs that follow it from the input +to the output file, but it will not copy any HDUs preceding the +current HDU. + + +\newpage +% =================================================================== +\subsection{Image I/O Routines} + +This section lists the more important CFITSIO routines which operate on +FITS images. + +\begin{verbatim} +_______________________________________________________________ +int fits_get_img_type(fitsfile *fptr, int *bitpix, int *status) +int fits_get_img_dim( fitsfile *fptr, int *naxis, int *status) +int fits_get_img_size(fitsfile *fptr, int maxdim, long *naxes, + int *status) +int fits_get_img_param(fitsfile *fptr, int maxdim, int *bitpix, + int *naxis, long *naxes, int *status) +\end{verbatim} + +Get information about the currently opened image HDU. The first routine +returns the datatype of the image as (defined by the {\tt BITPIX} +keyword), which can have the following symbolic constant values: +\begin{verbatim} + BYTE_IMG = 8 ( 8-bit byte pixels, 0 - 255) + SHORT_IMG = 16 (16 bit integer pixels) + LONG_IMG = 32 (32-bit integer pixels) + FLOAT_IMG = -32 (32-bit floating point pixels) + DOUBLE_IMG = -64 (64-bit floating point pixels) +\end{verbatim} + +The second and third routines return the number of dimensions in the +image (from the {\tt NAXIS} keyword), and the sizes of each dimension +(from the {\tt NAXIS1, NAXIS2}, etc. keywords). The last routine +simply combines the function of the first 3 routines. The input {\tt +maxdim} parameter in this routine gives the maximum number dimensions +that may be returned (i.e., the dimension of the {\tt naxes} +array) + +\begin{verbatim} +__________________________________________________________ +int fits_create_img(fitsfile *fptr, int bitpix, int naxis, + long *naxes, int *status) +\end{verbatim} + +Create an image HDU by writing the required keywords which define the +structure of the image. The 2nd through 4th parameters specified the +datatype, the number of dimensions, and the sizes of the dimensions. +The allowed values of the {\tt bitpix} parameter are listed above in +the description of the {\tt fits\_get\_img\_type} routine. If the FITS +file pointed to by {\tt fptr} is empty (previously created with +{\tt fits\_create\_file}) then this routine creates a primary array in +the file, otherwise a new IMAGE extension is appended to end of the +file following the other HDUs in the file. + +\begin{verbatim} +______________________________________________________________ +int fits_write_pix(fitsfile *fptr, int datatype, long *fpixel, + long nelements, void *array, int *status); + +int fits_write_pixnull(fitsfile *fptr, int datatype, long *fpixel, + long nelements, void *array, void *nulval, int *status); + +int fits_read_pix(fitsfile *fptr, int datatype, long *fpixel, + long nelements, void *nulval, void *array, + int *anynul, int *status) +\end{verbatim} + +Read or write all or part of the FITS image. There are 2 different +'write' pixel routines: The first simply writes the input array of pixels +to the FITS file. The second is similar, except that it substitutes +the appropriate null pixel value in the FITS file for any pixels +which have a value equal to {\tt *nulval} (note that this parameter +gives the address of the null pixel value, not the value itself). +Similarly, when reading an image, CFITSIO will substitute the value +given by {\tt nulval} for any undefined pixels in the image, unless +{\tt nulval = NULL}, in which case no checks will be made for undefined +pixels when reading the FITS image. + +The {\tt fpixel} parameter in these routines is an array which gives +the coordinate in each dimension of the first pixel to be read or +written, and {\tt nelements} is the total number of pixels to read or +write. {\tt array} is the address of an array which either contains +the pixel values to be written, or will hold the values of the pixels +that are read. When reading, {\tt array} must have been allocated +large enough to hold all the returned pixel values. These routines +starts at the {\tt fpixel} location and then read or write the {\tt +nelements} pixels, continuing on successive rows of the image if +necessary. For example, to write an entire 2D image, set {\tt +fpixel[0] = fpixel[1] = 1}, and {\tt nelements = NAXIS1 * NAXIS2}. Or +to read just the 10th row of the image, set {\tt fpixel[0] = 1, +fpixel[1] = 10}, and {\tt nelements = NAXIS1}. The {\tt datatype} +parameter specifies the datatype of the C {\tt array} in the program, +which need not be the same as the datatype of the FITS image itself. +If the datatypes differ then CFITSIO will convert the data as it is +read or written. The following symbolic constants are allowed for the +value of {\tt datatype}: +\begin{verbatim} + TBYTE unsigned char + TSBYTE signed char + TSHORT signed short + TUSHORT unsigned short + TINT signed int + TUINT unsigned int + TLONG signed long + TLONGLONG signed 8-byte integer + TULONG unsigned long + TFLOAT float + TDOUBLE double +\end{verbatim} + + +\begin{verbatim} +_________________________________________________________________ +int fits_write_subset(fitsfile *fptr, int datatype, long *fpixel, + long *lpixel, DTYPE *array, > int *status) + +int fits_read_subset(fitsfile *fptr, int datatype, long *fpixel, + long *lpixel, long *inc, void *nulval, void *array, + int *anynul, int *status) +\end{verbatim} + +Read or write a rectangular section of the FITS image. These are very +similar to {\tt fits\_write\_pix} and {\tt fits\_read\_pix} except that +you specify the last pixel coordinate (the upper right corner of the +section) instead of the number of pixels to be read. The read routine +also has an {\tt inc} parameter which can be used to read only every +{\tt inc-th} pixel along each dimension of the image. Normally {\tt +inc[0] = inc[1] = 1} to read every pixel in a 2D image. To read every +other pixel in the entire 2D image, set +\begin{verbatim} + fpixel[0] = fpixel[1] = 1 + lpixel[0] = {NAXIS1} + lpixel[1] = {NAXIS2} + inc[0] = inc[1] = 2 +\end{verbatim} + +Or, to read the 8th row of a 2D image, set +\begin{verbatim} + fpixel[0] = 1 + fpixel[1] = 8 + lpixel[0] = {NAXIS1} + lpixel[1] = 8 + inc[0] = inc[1] = 1 +\end{verbatim} + +\newpage +% =================================================================== +\subsection{Table I/O Routines} + +This section lists the most important CFITSIO routines which operate on +FITS tables. + +\begin{verbatim} +__________________________________________________________________________ +int fits_create_tbl(fitsfile *fptr, int tbltype, long nrows, int tfields, + char *ttype[],char *tform[], char *tunit[], char *extname, int *status) +\end{verbatim} + +Create a new table extension by writing the required keywords that +define the table structure. The required null primary array +will be created first if the file is initially completely empty. {\tt +tbltype} defines the type of table and can have values of {\tt +ASCII\_TBL or BINARY\_TBL}. Binary tables are generally preferred +because they are more efficient and support a greater range of column +datatypes than ASCII tables. + +The {\tt nrows} parameter gives the initial number of empty rows to be +allocated for the table; this should normally be set to 0. The {\tt tfields} +parameter gives the number of columns in the table (maximum = 999). +The {\tt +ttype, tform}, and {\tt tunit} parameters give the name, datatype, and +physical units of each column, and {\tt extname} gives the name for the +table (the value of the {\tt EXTNAME} keyword). +The FITS Standard recommends that only +letters, digits, and the underscore character be used in column names +with no embedded spaces. It is recommended that all the column names +in a given table be unique within the first 8 characters. + +The following table +shows the TFORM column format values that are allowed in ASCII tables +and in binary tables: +\begin{verbatim} + ASCII Table Column Format Codes + ------------------------------- + (w = column width, d = no. of decimal places to display) + Aw - character string + Iw - integer + Fw.d - fixed floating point + Ew.d - exponential floating point + Dw.d - exponential floating point + + Binary Table Column Format Codes + -------------------------------- + (r = vector length, default = 1) + rA - character string + rAw - array of strings, each of length w + rL - logical + rX - bit + rB - unsigned byte + rS - signed byte ** + rI - signed 16-bit integer + rU - unsigned 16-bit integer ** + rJ - signed 32-bit integer + rV - unsigned 32-bit integer ** + rK - 64-bit integer *** + rE - 32-bit floating point + rD - 64-bit floating point + rC - 32-bit complex pair + rM - 64-bit complex pair + + ** The S, U and V format codes are not actual legal TFORMn values. + CFITSIO substitutes the somewhat more complicated set of + keywords that are used to represent unsigned integers or + signed bytes. + + *** The 64-bit integer format is experimental and is not + officially recognized in the FITS Standard. +\end{verbatim} + +The {\tt tunit} and {\tt extname} parameters are optional and +may be set to NULL +if they are not needed. + +Note that it may be easier to create a new table by copying the +header from another existing table with {\tt fits\_copy\_header} rather +than calling this routine. + +\begin{verbatim} +_______________________________________________________________ +int fits_get_num_rows(fitsfile *fptr, long *nrows, int *status) +int fits_get_num_cols(fitsfile *fptr, int *ncols, int *status) +\end{verbatim} + +Get the number of rows or columns in the current FITS table. The +number of rows is given by the {\tt NAXIS2} keyword and the number of columns +is given by the {\tt TFIELDS} keyword in the header of the table. + +\begin{verbatim} +_______________________________________________________________ +int fits_get_colnum(fitsfile *fptr, int casesen, char *template, + int *colnum, int *status) +int fits_get_colname(fitsfile *fptr, int casesen, char *template, + char *colname, int *colnum, int *status) +\end{verbatim} + +Get the column number (starting with 1, not 0) of the column whose +name matches the specified template name. The only difference in +these 2 routines is that the 2nd one also returns the name of the +column that matched the template string. + +Normally, {\tt casesen} should +be set to {\tt CASEINSEN}, but it may be set to {\tt CASESEN} to force +the name matching to be case-sensitive. + +The input {\tt template} string gives the name of the desired column and +may include wildcard characters: a `*' matches any sequence of +characters (including zero characters), `?' matches any single +character, and `\#' matches any consecutive string of decimal digits +(0-9). If more than one column name in the table matches the template +string, then the first match is returned and the status value will be +set to {\tt COL\_NOT\_UNIQUE} as a warning that a unique match was not +found. To find the next column that matches the template, call this +routine again leaving the input status value equal to {\tt +COL\_NOT\_UNIQUE}. Repeat this process until {\tt status = +COL\_NOT\_FOUND} is returned. + +\begin{verbatim} +_______________________________________________________________ +int fits_get_coltype(fitsfile *fptr, int colnum, int *typecode, + long *repeat, long *width, int *status) + +int fits_get_eqcoltype(fitsfile *fptr, int colnum, int *typecode, + long *repeat, long *width, int *status) +\end{verbatim} + +Return the datatype, vector repeat count, and the width in bytes of a +single column element for column number {\tt colnum}. Allowed values +for the returned datatype in ASCII tables are: {\tt TSTRING, TSHORT, +TLONG, TFLOAT, and TDOUBLE}. Binary tables support these additional +types: {\tt TLOGICAL, TBIT, TBYTE, TINT32BIT, TCOMPLEX and TDBLCOMPLEX}. The +negative of the datatype code value is returned if it is a variable +length array column. + +These 2 routines are similar, except that in the case of scaled +integer columns the 2nd routine, fit\_get\_eqcoltype, returns the +'equivalent' datatype that is needed to store the scaled values, which +is not necessarily the same as the physical datatype of the unscaled values +as stored in the FITS table. For example if a '1I' column in a binary +table has TSCALn = 1 and TZEROn = 32768, then this column effectively +contains unsigned short integer values, and thus the returned value of +typecode will be TUSHORT, not TSHORT. Or, if TSCALn or TZEROn are not +integers, then the equivalent datatype will be returned as TFLOAT or +TDOUBLE, depending on the size of the integer. + +The repeat count is always 1 in ASCII tables. +The 'repeat' parameter returns the vector repeat count on the binary +table TFORMn keyword value. (ASCII table columns always have repeat += 1). The 'width' parameter returns the width in bytes of a single +column element (e.g., a '10D' binary table column will have width = +8, an ASCII table 'F12.2' column will have width = 12, and a binary +table'60A' character string column will have width = 60); Note that +this routine supports the local convention for specifying arrays of +fixed length strings within a binary table character column using +the syntax TFORM = 'rAw' where 'r' is the total number of +characters (= the width of the column) and 'w' is the width of a +unit string within the column. Thus if the column has TFORM = +'60A12' then this means that each row of the table contains +5 12-character substrings within the 60-character field, and thus +in this case this routine will return typecode = TSTRING, repeat = +60, and width = 12. The number of substings in any binary table +character string field can be calculated by (repeat/width). +A null pointer may be given for any of the output parameters that + are not needed. + +\begin{verbatim} +____________________________________________________________________________ +int fits_insert_rows(fitsfile *fptr, long firstrow, long nrows, int *status) +int fits_delete_rows(fitsfile *fptr, long firstrow, long nrows, int *status) +int fits_delete_rowrange(fitsfile *fptr, char *rangelist, int *status) +int fits_delete_rowlist(fitsfile *fptr, long *rowlist, long nrows, int *stat) +\end{verbatim} + +Insert or delete rows in a table. The blank rows are inserted +immediately following row {\tt frow}. Set {\tt frow} = 0 to insert rows +at the beginning of the table. The first 'delete' routine deletes {\tt +nrows} rows beginning with row {\tt firstrow}. The 2nd delete routine +takes an input string listing the rows or row ranges to be deleted +(e.g., '2,4-7, 9-12'). The last delete routine takes an input long +integer array that specifies each individual row to be deleted. The +row lists must be sorted in ascending order. All these routines update +the value of the {\tt NAXIS2} keyword to reflect the new number of rows +in the table. + +\begin{verbatim} +_________________________________________________________________________ +int fits_insert_col(fitsfile *fptr, int colnum, char *ttype, char *tform, + int *status) +int fits_insert_cols(fitsfile *fptr, int colnum, int ncols, char **ttype, + char **tform, int *status) + +int fits_delete_col(fitsfile *fptr, int colnum, int *status) +\end{verbatim} + +Insert or delete columns in a table. {\tt colnum} gives the position +of the column to be inserted or deleted (where the first column of the +table is at position 1). {\tt ttype} and {\tt tform} give the column +name and column format, where the allowed format codes are listed above +in the description of the {\tt fits\_create\_table} routine. The 2nd +'insert' routine inserts multiple columns, where {\tt ncols} is the +number of columns to insert, and {\tt ttype} and {\tt tform} are +arrays of string pointers in this case. + +\begin{verbatim} +____________________________________________________________________ +int fits_copy_col(fitsfile *infptr, fitsfile *outfptr, int incolnum, + int outcolnum, int create_col, int *status); +\end{verbatim} + +Copy a column from one table HDU to another. If {\tt create\_col} = TRUE (i.e., not equal to zero), +then a new column will be inserted in the output table at position +{\tt outcolumn}, otherwise the values in the existing output column will be +overwritten. + +\begin{verbatim} +__________________________________________________________________________ +int fits_write_col(fitsfile *fptr, int datatype, int colnum, long firstrow, + long firstelem, long nelements, void *array, int *status) +int fits_write_colnull(fitsfile *fptr, int datatype, int colnum, + long firstrow, long firstelem, long nelements, + void *array, void *nulval, int *status) +int fits_write_col_null(fitsfile *fptr, int colnum, long firstrow, + long firstelem, long nelements, int *status) + +int fits_read_col(fitsfile *fptr, int datatype, int colnum, long firstrow, + long firstelem, long nelements, void *nulval, void *array, + int *anynul, int *status) + +\end{verbatim} + +Write or read elements in column number {\tt colnum}, starting with row +{\tt firstsrow} and element {\tt firstelem} (if it is a vector +column). {\tt firstelem} is ignored if it is a scalar column. The {\tt +nelements} number of elements are read or written continuing on +successive rows of the table if necessary. {\tt array} is the address +of an array which either contains the values to be written, or will +hold the returned values that are read. When reading, {\tt array} must +have been allocated large enough to hold all the returned values. + +There are 3 different 'write' column routines: The first simply writes +the input array into the column. The second is similar, except that it +substitutes the appropriate null pixel value in the column for any +input array values which are equal to {\tt *nulval} (note that this +parameter gives the address of the null pixel value, not the value +itself). The third write routine sets the specified table elements +to a null value. New rows will be automatical added to the table +if the write operation extends beyond the current size of the table. + +When reading a column, CFITSIO will substitute the value given by {\tt +nulval} for any undefined elements in the FITS column, unless {\tt +nulval} or {\tt *nulval = NULL}, in which case no checks will be made +for undefined values when reading the column. + +{\tt datatype} specifies the datatype of the C {\tt array} in the program, +which need not be the same as the intrinsic datatype of the column in +the FITS table. The following symbolic constants are allowed for the +value of {\tt datatype}: + +\begin{verbatim} + TSTRING array of character string pointers + TBYTE unsigned char + TSHORT signed short + TUSHORT unsigned short + TINT signed int + TUINT unsigned int + TLONG signed long + TLONGLONG signed 8-byte integer + TULONG unsigned long + TFLOAT float + TDOUBLE double +\end{verbatim} + +Note that {\tt TSTRING} corresponds to the C {\tt +char**} datatype, i.e., a pointer to an array of pointers to an array +of characters. + +Any column, regardless of it's intrinsic datatype, may be read as a +{\tt TSTRING} character string. The display format of the returned +strings will be determined by the {\tt TDISPn} keyword, if it exists, +otherwise a default format will be used depending on the datatype of +the column. The {\tt tablist} example utility program (available from +the CFITSIO web site) uses this feature to display all the values in a +FITS table. + +\begin{verbatim} +_____________________________________________________________________ +int fits_select_rows(fitsfile *infptr, fitsfile *outfptr, char *expr, + int *status) +int fits_calculator(fitsfile *infptr, char *expr, fitsfile *outfptr, + char *colname, char *tform, int *status) +\end{verbatim} + +These are 2 of the most powerful routines in the CFITSIO library. (See +the full CFITSIO Reference Guide for a description of several related +routines). These routines can perform complicated transformations on +tables based on an input arithmetic expression which is evaluated for +each row of the table. The first routine will select or copy rows of +the table for which the expression evaluates to TRUE (i.e., not equal +to zero). The second routine writes the value of the expression to a +column in the output table. Rather than supplying the expression +directly to these routines, the expression may also be written to a +text file (continued over multiple lines if necessary) and the name of +the file, prepended with a '@' character, may be supplied as the value +of the 'expr' parameter (e.g. '@filename.txt'). + +The arithmetic expression may be a function of any column or keyword in +the input table as shown in these examples: + +\begin{verbatim} +Row Selection Expressions: + counts > 0 uses COUNTS column value + sqrt( X**2 + Y**2) < 10. uses X and Y column values + (X > 10) || (X < -10) && (Y == 0) used 'or' and 'and' operators + gtifilter() filter on Good Time Intervals + regfilter("myregion.reg") filter using a region file + @select.txt reads expression from a text file +Calculator Expressions: + #row % 10 modulus of the row number + counts/#exposure Fn of COUNTS column and EXPOSURE keyword + dec < 85 ? cos(dec * #deg) : 0 Conditional expression: evaluates to + cos(dec) if dec < 85, else 0 + (count{-1}+count+count{+1})/3. running mean of the count values in the + previous, current, and next rows + max(0, min(X, 1000)) returns a value between 0 - 1000 + @calc.txt reads expression from a text file +\end{verbatim} + +Most standard mathematical operators and functions are supported. If +the expression includes the name of a column, than the value in the +current row of the table will be used when evaluating the expression on +each row. An offset to an adjacent row can be specified by including +the offset value in curly brackets after the column name as shown in +one of the examples. Keyword values can be included in the expression +by preceding the keyword name with a `\#' sign. See Section 5 of this +document for more discussion of the expression syntax. + +{\tt gtifilter} is a special function which tests whether the {\tt +TIME} column value in the input table falls within one or more Good +Time Intervals. By default, this function looks for a 'GTI' extension +in the same file as the input table. The 'GTI' table contains {\tt START} +and {\tt STOP} columns which define the range of +each good time interval. See section 5.4.3 for more details. + +{\tt regfilter} is another special function which selects rows based on +whether the spatial position associated with each row is located within +in a specified region of the sky. By default, the {\tt X} and {\tt Y} +columns in the input table are assumed to give the position of each row. +The spatial region is defined in an ASCII text file whose name is given +as the argument to the {\tt regfilter} function. See section 5.4.4 for +more details. + +The {\tt infptr} and {\tt outfptr} parameters in these routines may +point to the same table or to different tables. In {\tt +fits\_select\_rows}, if the input and output tables are the same then +the rows that do not satisfy the selection expression will be deleted +from the table. Otherwise, if the output table is different from the +input table then the selected rows will be copied from the input table +to the output table. + +The output column in {\tt fits\_calculator} may or may not already +exist. If it exists then the calculated values will be written to that +column, overwriting the existing values. If the column doesn't exist +then the new column will be appended to the output table. The {\tt tform} +parameter can be used to specify the datatype of the new column (e.g., +the {\tt TFORM} keyword value as in {\tt '1E', or '1J'}). If {\tt +tform} = NULL then a default datatype will be used, depending on the +expression. + +\begin{verbatim} +_____________________________________________________________________ +int fits_read_tblbytes(fitsfile *fptr, long firstrow, long firstchar, + long nchars, unsigned char *array, int *status) +int fits_write_tblbytes (fitsfile *fptr, long firstrow, long firstchar, + long nchars, unsigned char *array, int *status) +\end{verbatim} + +These 2 routines provide low-level access to tables and are mainly +useful as an efficient way to copy rows of a table from one file to +another. These routines simply read or write the specified number of +consecutive characters (bytes) in a table, without regard for column +boundaries. For example, to read or write the first row of a table, +set {\tt firstrow = 1, firstchar = 1}, and {\tt nchars = NAXIS1} where +the length of a row is given by the value of the {\tt NAXIS1} header +keyword. When reading a table, {\tt array} must have been declared at +least {\tt nchars} bytes long to hold the returned string of bytes. + +\newpage +% =================================================================== +\subsection{Header Keyword I/O Routines} +\nopagebreak +The following routines read and write header keywords in the current HDU. +\nopagebreak + +\begin{verbatim} +____________________________________________________________________ +int fits_get_hdrspace(fitsfile *fptr, int *keysexist, int *morekeys, + int *status) +\end{verbatim} +\nopagebreak +Return the number of existing keywords (not counting the mandatory END +keyword) and the amount of empty space currently available for more +keywords. The {\tt morekeys} parameter may be set to NULL if it's value is +not needed. + +\begin{verbatim} +___________________________________________________________________________ +int fits_read_record(fitsfile *fptr, int keynum, char *record, int *status) +int fits_read_card(fitsfile *fptr, char *keyname, char *record, int *status) +int fits_read_key(fitsfile *fptr, int datatype, char *keyname, + void *value, char *comment, int *status) + +int fits_find_nextkey(fitsfile *fptr, char **inclist, int ninc, + char **exclist, int nexc, char *card, int *status) + +int fits_read_key_unit(fitsfile *fptr, char *keyname, char *unit, + int *status) +\end{verbatim} + +These routines all read a header record in the current HDU. The first +routine reads keyword number {\tt keynum} (where the first keyword is +at position 1). This routine is most commonly used when sequentially +reading every record in the header from beginning to end. The 2nd and +3rd routines read the named keyword and return either the whole +record, or the keyword value and comment string. In each case any +non-significant trailing blank characters in the strings are truncated. + +Wild card characters (*, ?, and \#) may be used when specifying the name +of the keyword to be read, in which case the first matching keyword is +returned. + +The {\tt datatype} parameter specifies the C datatype of the returned +keyword value and can have one of the following symbolic constant +values: {\tt TSTRING, TLOGICAL} (== int), {\tt TBYTE}, {\tt TSHORT}, +{\tt TUSHORT}, {\tt TINT}, {\tt TUINT}, {\tt TLONG}, {\tt TULONG}, {\tt +TFLOAT}, {\tt TDOUBLE}, {\tt TCOMPLEX}, and {\tt TDBLCOMPLEX}. Data +type conversion will be performed for numeric values if the intrinsic +FITS keyword value does not have the same datatype. The {\tt comment} +parameter may be set equal to NULL if the comment string is not +needed. + +The 4th routine provides an easy way to find all the keywords in the +header that match one of the name templates in {\tt inclist} and do not +match any of the name templates in {\tt exclist}. {\tt ninc} and {\tt +nexc} are the number of template strings in {\tt inclist} and {\tt +exclist}, respectively. Wild cards (*, ?, and \#) may be used in the +templates to match multiple keywords. Each time this routine is called +it returns the next matching 80-byte keyword record. It returns status += {\tt KEY\_NO\_EXIST} if there are no more matches. + +The 5th routine returns the keyword value units string, if any. +The units are recorded at the beginning of the keyword comment field +enclosed in square brackets. +\begin{verbatim} +_______________________________________________________________ +int fits_write_key(fitsfile *fptr, int datatype, char *keyname, + void *value, char *comment, int *status) +int fits_update_key(fitsfile *fptr, int datatype, char *keyname, + void *value, char *comment, int *status) +int fits_write_record(fitsfile *fptr, char *card, int *status) + +int fits_modify_comment(fitsfile *fptr, char *keyname, char *comment, + int *status) +int fits_write_key_unit(fitsfile *fptr, char *keyname, char *unit, + int *status) + +\end{verbatim} + +Write or modify a keyword in the header of the current HDU. The +first routine appends the new keyword to the end of the header, whereas +the second routine will update the value and comment fields of the +keyword if it already exists, otherwise it behaves like the first +routine and appends the new keyword. Note that {\tt value} gives the +address to the value and not the value itself. The {\tt datatype} +parameter specifies the C datatype of the keyword value and may have +any of the values listed in the description of the keyword reading +routines, above. A NULL may be entered for the comment parameter, in +which case the keyword comment field will be unmodified or left +blank. + +The third routine is more primitive and simply writes the 80-character +{\tt card} record to the header. It is the programmer's responsibility +in this case to ensure that the record conforms to all the FITS format +requirements for a header record. + +The fourth routine modifies the comment string in an existing keyword, +and the last routine writes or updates the keyword units string for an +existing keyword. (The units are recorded at the beginning of the +keyword comment field enclosed in square brackets). + +\begin{verbatim} +___________________________________________________________________ +int fits_write_comment(fitsfile *fptr, char *comment, int *status) +int fits_write_history(fitsfile *fptr, char *history, int *status) +int fits_write_date(fitsfile *fptr, int *status) +\end{verbatim} + +Write a {\tt COMMENT, HISTORY}, or {\tt DATE} keyword to the current +header. The {\tt COMMENT} keyword is typically used to write a comment +about the file or the data. The {\tt HISTORY} keyword is typically +used to provide information about the history of the processing +procedures that have been applied to the data. The {\tt comment} or +{\tt history} string will be continued over multiple keywords if it is +more than 70 characters long. + +The {\tt DATE} keyword is used to record the date and time that the +FITS file was created. Note that this file creation date is usually +different from the date of the observation which obtained the data in +the FITS file. The {\tt DATE} keyword value is a character string in +'yyyy-mm-ddThh:mm:ss' format. If a {\tt DATE} keyword already exists in +the header, then this routine will update the value with the current +system date. + +\begin{verbatim} +___________________________________________________________________ +int fits_delete_record(fitsfile *fptr, int keynum, int *status) +int fits_delete_key(fitsfile *fptr, char *keyname, int *status) +\end{verbatim} + +Delete a keyword record. The first routine deletes a keyword at a +specified position (the first keyword is at position 1, not 0), +whereas the second routine deletes the named keyword. + +\begin{verbatim} +_______________________________________________________________________ +int fits_copy_header(fitsfile *infptr, fitsfile *outfptr, int *status) +\end{verbatim} + +Copy all the header keywords from the current HDU associated with +infptr to the current HDU associated with outfptr. If the current +output HDU is not empty, then a new HDU will be appended to the output +file. The output HDU will then have the identical structure as the +input HDU, but will contain no data. + +\newpage +% =================================================================== +\subsection{Utility Routines} + +This section lists the most important CFITSIO general utility routines. + +\begin{verbatim} +___________________________________________________________________ +int fits_write_chksum( fitsfile *fptr, int *status) +int fits_verify_chksum(fitsfile *fptr, int *dataok, int *hduok, int *status) +\end{verbatim} + +These routines compute or validate the checksums for the currenrt +HDU. The {\tt DATASUM} keyword is used to store the numerical value of +the 32-bit, 1's complement checksum for the data unit alone. The {\tt +CHECKSUM} keyword is used to store the ASCII encoded COMPLEMENT of the +checksum for the entire HDU. Storing the complement, rather than the +actual checksum, forces the checksum for the whole HDU to equal zero. +If the file has been modified since the checksums were computed, then +the HDU checksum will usually not equal zero. + +The returned {\tt dataok} and {\tt hduok} parameters will have a value += 1 if the data or HDU is verified correctly, a value = 0 if the +{\tt DATASUM} or {\tt CHECKSUM} keyword is not present, or value = -1 if the +computed checksum is not correct. + + +\begin{verbatim} +___________________________________________________________________ +int fits_parse_value(char *card, char *value, char *comment, int *status) +int fits_get_keytype(char *value, char *dtype, int *status) +int fits_get_keyclass(char *card) +int fits_parse_template(char *template, char *card, int *keytype, int *status) + +\end{verbatim} + +{\tt fits\_parse\_value} parses the input 80-chararacter header keyword record, returning +the value (as a literal character string) and comment strings. If the +keyword has no value (columns 9-10 not equal to '= '), then a null +value string is returned and the comment string is set equal to column +9 - 80 of the input string. + +{\tt fits\_get\_keytype} parses the keyword value string to determine its +datatype. {\tt dtype} returns with a value of 'C', 'L', 'I', 'F' or +'X', for character string, logical, integer, floating point, or +complex, respectively. + +{\tt fits\_get\_keyclass} returns a classification code that indicates +the classification type of the input keyword record (e.g., a required +structural keyword, a TDIM keyword, a WCS keyword, a comment keyword, +etc. See the CFITSIO Reference Guide for a list of the different +classification codes. + +{\tt fits\_parse\_template} takes an input free format keyword template +string and returns a formatted 80*char record that satisfies all the +FITS requirements for a header keyword record. The template should +generally contain 3 tokens: the keyword name, the keyword value, and +the keyword comment string. The returned {\tt keytype} parameter +indicates whether the keyword is a COMMENT keyword or not. See the +CFITSIO Reference Guide for more details. + +\newpage +% =================================================================== +\section{CFITSIO File Names and Filters} + +\subsection{Creating New Files} + +When creating a new output file on magnetic disk with {\tt +fits\_create\_file} the following features are supported. +\begin{itemize} +\item Overwriting, or 'Clobbering' an Existing File + +If the filename is preceded by an exclamation +point (!) then if that file already exists it will be deleted prior to +creating the new FITS file. Otherwise if there is an existing file +with the same name, CFITSIO will not overwrite the existing file and +will return an error status code. Note that the exclamation point is +a special UNIX character, so if it is used on the command line rather +than entered at a task prompt, it must be preceded by a backslash to +force the UNIX shell to pass it verbatim to the application program. + +\item Compressed Output Files + +If the output disk file name ends with the suffix '.gz', then CFITSIO +will compress the file using the gzip compression algorithm before +writing it to disk. This can reduce the amount of disk space used by +the file. Note that this feature requires that the uncompressed file +be constructed in memory before it is compressed and written to disk, +so it can fail if there is insufficient available memory. + +One can also specify that any images written to the output file should +be compressed using the newly developed `tile-compression' algorithm by +appending `[compress]' to the name of the disk file (as in +{\tt myfile.fits[compress]}). Refer to the CFITSIO User's Reference Guide +for more information about this new image compression format. + +\item Using a Template to Create a New FITS File + +The structure of any new FITS file that is to be created may be defined +in an ASCII template file. If the name of the template file is +appended to the name of the FITS file itself, enclosed in parenthesis +(e.g., {\tt 'newfile.fits(template.txt)'}) then CFITSIO will create a +FITS file with that structure before opening it for the application to +use. The template file basically defines the dimensions and data type +of the primary array and any IMAGE extensions, and the names and data +types of the columns in any ASCII or binary table extensions. The +template file can also be used to define any optional keywords that +should be written in any of the HDU headers. The image pixel values +and table entry values are all initialized to zero. The application +program can then write actual data into the HDUs. See the CFITSIO +Reference Guide for for a complete description of the template file +syntax. + +\item Creating a Temporary Scratch File in Memory + +It is sometimes useful to create a temporary output file when testing +an application program. If the name of the file to be created is +specified as {\tt mem:} then CFITSIO will create the file in +memory where it will persist only until the program closes the file. +Use of this {\tt mem:} output file usually enables the program to run +faster, and of course the output file does not use up any disk space. + + +\end{itemize} + +\subsection{Opening Existing Files} + +When opening a file with {\tt fits\_open\_file}, CFITSIO can read a +variety of different input file formats and is not restricted to only +reading FITS format files from magnetic disk. The following types of +input files are all supported: + +\begin{itemize} +\item FITS files compressed with {\tt zip, gzip} or {\tt compress} + +If CFITSIO cannot find the specified file to open it will automatically +look for a file with the same rootname but with a {\tt .gz, .zip}, or +{\tt .Z} extension. If it finds such a compressed file, it will +allocate a block of memory and uncompress the file into that memory +space. The application program will then transparently open this +virtual FITS file in memory. Compressed +files can only be opened with 'readonly', not 'readwrite' file access. + +\item FITS files on the internet, using {\tt ftp} or {\tt http} URLs + +Simply provide the full URL as the name of the file that you want to +open. For example,\linebreak {\tt +ftp://legacy.gsfc.nasa.gov/software/fitsio/c/testprog.std}\linebreak +will open the CFITSIO test FITS file that is located on the {\tt +legacy} machine. These files can only be opened with 'readonly' file +access. + +\item FITS files on {\tt stdin} or {\tt stdout} file streams + +If the name of the file to be opened is {\tt 'stdin'} or {\tt '-'} (a +single dash character) then CFITSIO will read the file from the +standard input stream. Similarly, if the output file name is {\tt +'stdout'} or {\tt '-'}, then the file will be written to the standard +output stream. In addition, if the output filename is {\tt +'stdout.gz'} or {\tt '-.gz'} then it will be gzip compressed before +being written to stdout. This mechanism can be used to pipe FITS files +from one task to another without having to write an intermediary FITS +file on magnetic disk. + +\item FITS files that exist only in memory, or shared memory. + +In some applications, such as real time data acquisition, you may want +to have one process write a FITS file into a certain section of +computer memory, and then be able to open that file in memory with +another process. There is a specialized CFITSIO open routine called +{\tt fits\_open\_memfile} that can be used for this purpose. See the +``CFITSIO User's Reference Guide'' for more details. + +\item IRAF format images (with {\tt .imh} file extensions) + +CFITSIO supports reading IRAF format images by converting them on the +fly into FITS images in memory. The application program then reads +this virtual FITS format image in memory. There is currently no +support for writing IRAF format images, or for reading or writing IRAF +tables. + +\item Image arrays in raw binary format + +If the input file is a raw binary data array, then CFITSIO will convert +it on the fly into a virtual FITS image with the basic set of required +header keywords before it is opened by the application program. In +this case the data type and dimensions of the image must be specified +in square brackets following the filename (e.g. {\tt +rawfile.dat[ib512,512]}). The first character inside the brackets +defines the datatype of the array: + +\begin{verbatim} + b 8-bit unsigned byte + i 16-bit signed integer + u 16-bit unsigned integer + j 32-bit signed integer + r or f 32-bit floating point + d 64-bit floating point +\end{verbatim} +An optional second character specifies the byte order of the array +values: b or B indicates big endian (as in FITS files and the native +format of SUN UNIX workstations and Mac PCs) and l or L indicates +little endian (native format of DEC OSF workstations and IBM PCs). If +this character is omitted then the array is assumed to have the native +byte order of the local machine. These datatype characters are then +followed by a series of one or more integer values separated by commas +which define the size of each dimension of the raw array. Arrays with +up to 5 dimensions are currently supported. + +Finally, a byte offset to the position of the first pixel in the data +file may be specified by separating it with a ':' from the last +dimension value. If omitted, it is assumed that the offset = 0. This +parameter may be used to skip over any header information in the file +that precedes the binary data. Further examples: + +\begin{verbatim} + raw.dat[b10000] 1-dimensional 10000 pixel byte array + raw.dat[rb400,400,12] 3-dimensional floating point big-endian array + img.fits[ib512,512:2880] reads the 512 x 512 short integer array in a + FITS file, skipping over the 2880 byte header +\end{verbatim} + +\end{itemize} +\newpage + +\subsection{Image Filtering} + +\subsubsection{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 {\tt myfile.fits} contains a 512 x 512 pixel 2D +image. + +\begin{verbatim} + 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. +\end{verbatim} + +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 {\tt myfile.fits[1][-*, *]} to read the image in the +first extension in the file. + +\subsubsection{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 {\tt X} and {\tt 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: \newline +{\tt '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 {\tt TLMINn} and {\tt TLMAXn} header keywords which +give the minimum and maximum allowed pixel values in the columns. For +instance if {\tt TLMINn = 1} and {\tt 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 , {\tt '[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 {\tt '[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. {\tt '[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. +\newpage + +\subsection{Table Filtering} + +\subsubsection{Column and Keyword Filtering} + +The column or keyword filtering specifier is used to modify the +column structure and/or the header keywords in the HDU that was +selected with the previous HDU location specifier. It can +be used to perform the following types of operations. + +\begin{itemize} +\item +Append a new column to a table by giving the column name, optionally +followed by the datatype in parentheses, followed by an equals sign and +the arithmetic expression to be used to compute the value. The +datatype is specified using the same syntax that is allowed for the +value of the FITS TFORMn keyword (e.g., 'I', 'J', 'E', 'D', etc. for +binary tables, and 'I8', F12.3', 'E20.12', etc. for ASCII tables). If +the datatype is not specified then a default datatype will be chosen +depending on the expression. + +\item +Create a new header keyword by giving the keyword name, preceded by a +pound sign '\#', followed by an equals sign and an arithmetic +expression for the value of the keyword. The expression may be a +function of other header keyword values. The comment string for the +keyword may be specified in parentheses immediately following the +keyword name. + +\item +Overwrite the values in an existing column or keyword by giving the +name followed by an equals sign and an arithmetic expression. + +\item +Select a set of columns to be included in the filtered file by listing +the column names separated with semi-colons. Wild card characters may +be used in the column names to match multiple columns. Any other +columns in the input table will not appear in the filtered file. + +\item +Delete a column or keyword by listing the name preceded by a minus sign +or an exclamation mark (!) + +\item +Rename an existing column or keyword with the syntax 'NewName == +OldName'. + +\end{itemize} + +The column filtering specifier is enclosed in square brackets and +begins with the string 'col'. Multiple operations can be performed +by separating them with semi-colons. For complex or commonly used +operations, you can write the column filter to a text file, and then +use it by giving the name of the text file, preceded by a '@' +character. + +Some examples: + +\begin{verbatim} + [col PI=PHA * 1.1 + 0.2] - creates new PI column from PHA values + + [col rate = counts/exposure] - creates or overwrites the rate column by + dividing the counts column by the + EXPOSURE keyword value. + + [col TIME; X; Y] - only the listed columns will appear + in the filtered file + + [col Time;*raw] - include the Time column and any other + columns whose name ends with 'raw'. + + [col -TIME; Good == STATUS] - deletes the TIME column and + renames the STATUS column to GOOD + + [col @colfilt.txt] - uses the filtering expression in + the colfilt.txt text file +\end{verbatim} + +The original file is not changed by this filtering operation, and +instead the modifications are made on a temporary copy of the input +FITS file (usually in memory), which includes a copy of all the other +HDUs in the input file. The original input file is closed and the +application program opens the filtered copy of the file. + +\subsubsection{Row Filtering} + +The row filter is used to select a subset of the rows from a table +based on a boolean expression. A temporary new FITS file is created on +the fly (usually in memory) which contains only those rows for which +the row filter expression evaluates to true (i.e., not equal to zero). +The primary array and any other extensions in the input file are also +copied to the temporary file. The original FITS file is closed and the +new temporary file is then opened by the application program. + +The row filter expression is enclosed in square brackets following the +file name and extension name. For example, {\tt +'file.fits[events][GRADE==50]'} selects only those rows in the EVENTS +table where the GRADE column value is equal to 50). + +The row filtering expression can be an arbitrarily complex series of +operations performed on constants, keyword values, and column data +taken from the specified FITS TABLE extension. The expression +also can be written into a text file and then used by giving the +filename preceded by a '@' character, as in +{\tt '[@rowfilt.txt]'}. + +Keyword and column data are referenced by name. Any string of +characters not surrounded by quotes (ie, a constant string) or +followed by an open parentheses (ie, a function name) will be +initially interpreted as a column name and its contents for the +current row inserted into the expression. If no such column exists, +a keyword of that name will be searched for and its value used, if +found. To force the name to be interpreted as a keyword (in case +there is both a column and keyword with the same name), precede the +keyword name with a single pound sign, '\#', as in {\tt \#NAXIS2}. Due to +the generalities of FITS column and keyword names, if the column or +keyword name contains a space or a character which might appear as +an arithmetic term then inclose the name in '\$' characters as in +{\tt \$MAX PHA\$} or {\tt \#\$MAX-PHA\$}. The names are case insensitive. + +To access a table entry in a row other than the current one, follow +the column's name with a row offset within curly braces. For +example, {\tt'PHA\{-3\}'} will evaluate to the value of column PHA, 3 rows +above the row currently being processed. One cannot specify an +absolute row number, only a relative offset. Rows that fall outside +the table will be treated as undefined, or NULLs. + +Boolean operators can be used in the expression in either their +Fortran or C forms. The following boolean operators are available: + +\begin{verbatim} + "equal" .eq. .EQ. == "not equal" .ne. .NE. != + "less than" .lt. .LT. < "less than/equal" .le. .LE. <= =< + "greater than" .gt. .GT. > "greater than/equal" .ge. .GE. >= => + "or" .or. .OR. || "and" .and. .AND. && + "negation" .not. .NOT. ! "approx. equal(1e-7)" ~ +\end{verbatim} + +Note that the exclamation point, '!', is a special UNIX character, so +if it is used on the command line rather than entered at a task +prompt, it must be preceded by a backslash to force the UNIX shell to +ignore it. + +The expression may also include arithmetic operators and functions. +Trigonometric functions use radians, not degrees. The following +arithmetic operators and functions can be used in the expression +(function names are case insensitive): + + +\begin{verbatim} + "addition" + "subtraction" - + "multiplication" * "division" / + "negation" - "exponentiation" ** ^ + "absolute value" abs(x) "cosine" cos(x) + "sine" sin(x) "tangent" tan(x) + "arc cosine" arccos(x) "arc sine" arcsin(x) + "arc tangent" arctan(x) "arc tangent" arctan2(x,y) + "exponential" exp(x) "square root" sqrt(x) + "natural log" log(x) "common log" log10(x) + "modulus" i % j "random # [0.0,1.0)" random() + "minimum" min(x,y) "maximum" max(x,y) + "if-then-else" b?x:y +\end{verbatim} + + +The following type casting operators are available, where the +inclosing parentheses are required and taken from the C language +usage. Also, the integer to real casts values to double precision: + +\begin{verbatim} + "real to integer" (int) x (INT) x + "integer to real" (float) i (FLOAT) i +\end{verbatim} + + +Several constants are built in for use in numerical +expressions: + + +\begin{verbatim} + #pi 3.1415... #e 2.7182... + #deg #pi/180 #row current row number + #null undefined value #snull undefined string +\end{verbatim} + +A string constant must be enclosed in quotes as in 'Crab'. The +"null" constants are useful for conditionally setting table values to +a NULL, or undefined, value (For example, {\tt "col1==-99 ? \#NULL : +col1"}). + +There is also a function for testing if two values are close to +each other, i.e., if they are "near" each other to within a user +specified tolerance. The arguments, {\tt value\_1} and {\tt value\_2} can be +integer or real and represent the two values who's proximity is +being tested to be within the specified tolerance, also an integer +or real: + +\begin{verbatim} + near(value_1, value_2, tolerance) +\end{verbatim} + +When a NULL, or undefined, value is encountered in the FITS table, +the expression will evaluate to NULL unless the undefined value is +not actually required for evaluation, e.g. "TRUE .or. NULL" +evaluates to TRUE. The following two functions allow some NULL +detection and handling: + +\begin{verbatim} + ISNULL(x) + DEFNULL(x,y) +\end{verbatim} + +The former returns a boolean value of TRUE if the argument x is +NULL. The later "defines" a value to be substituted for NULL +values; it returns the value of x if x is not NULL, otherwise it +returns the value of y. + +Bit masks can be used to select out rows from bit columns ({\tt TFORMn = +\#X}) in FITS files. To represent the mask, binary, octal, and hex +formats are allowed: + +\begin{verbatim} + binary: b0110xx1010000101xxxx0001 + octal: o720x1 -> (b111010000xxx001) + hex: h0FxD -> (b00001111xxxx1101) +\end{verbatim} + +In all the representations, an x or X is allowed in the mask as a +wild card. Note that the x represents a different number of wild +card bits in each representation. All representations are case +insensitive. + +To construct the boolean expression using the mask as the boolean +equal operator described above on a bit table column. For example, +if you had a 7 bit column named flags in a FITS table and wanted +all rows having the bit pattern 0010011, the selection expression +would be: + + +\begin{verbatim} + flags == b0010011 + or + flags .eq. b10011 +\end{verbatim} + +It is also possible to test if a range of bits is less than, less +than equal, greater than and greater than equal to a particular +boolean value: + + +\begin{verbatim} + flags <= bxxx010xx + flags .gt. bxxx100xx + flags .le. b1xxxxxxx +\end{verbatim} + +Notice the use of the x bit value to limit the range of bits being +compared. + +It is not necessary to specify the leading (most significant) zero +(0) bits in the mask, as shown in the second expression above. + +Bit wise AND, OR and NOT operations are also possible on two or +more bit fields using the '\&'(AND), '$|$'(OR), and the '!'(NOT) +operators. All of these operators result in a bit field which can +then be used with the equal operator. For example: + + +\begin{verbatim} + (!flags) == b1101100 + (flags & b1000001) == bx000001 +\end{verbatim} + +Bit fields can be appended as well using the '+' operator. Strings +can be concatenated this way, too. + +\subsubsection{Good Time Interval Filtering} + + A common filtering method involves selecting rows which have a time + value which lies within what is called a Good Time Interval or GTI. + The time intervals are defined in a separate FITS table extension + which contains 2 columns giving the start and stop time of each + good interval. The filtering operation accepts only those rows of + the input table which have an associated time which falls within + one of the time intervals defined in the GTI extension. A high + level function, gtifilter(a,b,c,d), is available which evaluates + each row of the input table and returns TRUE or FALSE depending + whether the row is inside or outside the good time interval. The + syntax is + +\begin{verbatim} + gtifilter( [ "gtifile" [, expr [, "STARTCOL", "STOPCOL" ] ] ] ) +\end{verbatim} + where each "[]" demarks optional parameters. Note that the quotes + around the gtifile and START/STOP column are required. Either single + or double quote characters may be used. The gtifile, + if specified, can be blank ("") which will mean to use the first + extension with the name "*GTI*" in the current file, a plain + extension specifier (eg, "+2", "[2]", or "[STDGTI]") which will be + used to select an extension in the current file, or a regular + filename with or without an extension specifier which in the latter + case will mean to use the first extension with an extension name + "*GTI*". Expr can be any arithmetic expression, including simply + the time column name. A vector time expression will produce a + vector boolean result. STARTCOL and STOPCOL are the names of the + START/STOP columns in the GTI extension. If one of them is + specified, they both must be. + + In its simplest form, no parameters need to be provided -- default + values will be used. The expression {\tt "gtifilter()"} is equivalent to + +\begin{verbatim} + gtifilter( "", TIME, "*START*", "*STOP*" ) +\end{verbatim} + This will search the current file for a GTI extension, filter the + TIME column in the current table, using START/STOP times taken from + columns in the GTI extension with names containing the strings + "START" and "STOP". The wildcards ('*') allow slight variations in + naming conventions such as "TSTART" or "STARTTIME". The same + default values apply for unspecified parameters when the first one + or two parameters are specified. The function automatically + searches for TIMEZERO/I/F keywords in the current and GTI + extensions, applying a relative time offset, if necessary. + +\subsubsection{Spatial Region Filtering} + + Another common filtering method selects rows based on whether the + spatial position associated with each row is located within a given + 2-dimensional region. The syntax for this high-level filter is + +\begin{verbatim} + regfilter( "regfilename" [ , Xexpr, Yexpr [ , "wcs cols" ] ] ) +\end{verbatim} + where each "[ ]" demarks optional parameters. The region file name + is required and must be enclosed in quotes. The remaining + parameters are optional. The region file is an ASCII text file + which contains a list of one or more geometric shapes (circle, + ellipse, box, etc.) which defines a region on the celestial sphere + or an area within a particular 2D image. The region file is + typically generated using an image display program such as fv/POW + (distribute by the HEASARC), or ds9 (distributed by the Smithsonian + Astrophysical Observatory). Users should refer to the documentation + provided with these programs for more details on the syntax used in + the region files. + + In its simpliest form, (e.g., {\tt regfilter("region.reg")} ) the + coordinates in the default 'X' and 'Y' columns will be used to + determine if each row is inside or outside the area specified in + the region file. Alternate position column names, or expressions, + may be entered if needed, as in + +\begin{verbatim} + regfilter("region.reg", XPOS, YPOS) +\end{verbatim} + Region filtering can be applied most unambiguously if the positions + in the region file and in the table to be filtered are both give in + terms of absolute celestial coordinate units. In this case the + locations and sizes of the geometric shapes in the region file are + specified in angular units on the sky (e.g., positions given in + R.A. and Dec. and sizes in arcseconds or arcminutes). Similarly, + each row of the filtered table will have a celestial coordinate + associated with it. This association is usually implemented using + a set of so-called 'World Coordinate System' (or WCS) FITS keywords + that define the coordinate transformation that must be applied to + the values in the 'X' and 'Y' columns to calculate the coordinate. + + Alternatively, one can perform spatial filtering using unitless + 'pixel' coordinates for the regions and row positions. In this + case the user must be careful to ensure that the positions in the 2 + files are self-consistent. A typical problem is that the region + file may be generated using a binned image, but the unbinned + coordinates are given in the event table. The ROSAT events files, + for example, have X and Y pixel coordinates that range from 1 - + 15360. These coordinates are typically binned by a factor of 32 to + produce a 480x480 pixel image. If one then uses a region file + generated from this image (in image pixel units) to filter the + ROSAT events file, then the X and Y column values must be converted + to corresponding pixel units as in: + +\begin{verbatim} + regfilter("rosat.reg", X/32.+.5, Y/32.+.5) +\end{verbatim} + Note that this binning conversion is not necessary if the region + file is specified using celestial coordinate units instead of pixel + units because CFITSIO is then able to directly compare the + celestial coordinate of each row in the table with the celestial + coordinates in the region file without having to know anything + about how the image may have been binned. + + The last "wcs cols" parameter should rarely be needed. If supplied, + this string contains the names of the 2 columns (space or comma + separated) which have the associated WCS keywords. If not supplied, + the filter will scan the X and Y expressions for column names. + If only one is found in each expression, those columns will be + used, otherwise an error will be returned. + + These region shapes are supported (names are case insensitive): + +\begin{verbatim} + Point ( X1, Y1 ) <- One pixel square region + Line ( X1, Y1, X2, Y2 ) <- One pixel wide region + Polygon ( X1, Y1, X2, Y2, ... ) <- Rest are interiors with + Rectangle ( X1, Y1, X2, Y2, A ) | boundaries considered + Box ( Xc, Yc, Wdth, Hght, A ) V within the region + Diamond ( Xc, Yc, Wdth, Hght, A ) + Circle ( Xc, Yc, R ) + Annulus ( Xc, Yc, Rin, Rout ) + Ellipse ( Xc, Yc, Rx, Ry, A ) + Elliptannulus ( Xc, Yc, Rinx, Riny, Routx, Routy, Ain, Aout ) + Sector ( Xc, Yc, Amin, Amax ) +\end{verbatim} + where (Xc,Yc) is the coordinate of the shape's center; (X\#,Y\#) are + the coordinates of the shape's edges; Rxxx are the shapes' various + Radii or semimajor/minor axes; and Axxx are the angles of rotation + (or bounding angles for Sector) in degrees. For rotated shapes, the + rotation angle can be left off, indicating no rotation. Common + alternate names for the regions can also be used: rotbox = box; + rotrectangle = rectangle; (rot)rhombus = (rot)diamond; and pie + = sector. When a shape's name is preceded by a minus sign, '-', + the defined region is instead the area *outside* its boundary (ie, + the region is inverted). All the shapes within a single region + file are OR'd together to create the region, and the order is + significant. The overall way of looking at region files is that if + the first region is an excluded region then a dummy included region + of the whole detector is inserted in the front. Then each region + specification as it is processed overrides any selections inside of + that region specified by previous regions. Another way of thinking + about this is that if a previous excluded region is completely + inside of a subsequent included region the excluded region is + ignored. + + The positional coordinates may be given either in pixel units, + decimal degrees or hh:mm:ss.s, dd:mm:ss.s units. The shape sizes + may be given in pixels, degrees, arcminutes, or arcseconds. Look + at examples of region file produced by fv/POW or ds9 for further + details of the region file format. + +\subsubsection{Example Row Filters} + +\begin{verbatim} + [double && mag <= 5.0] - Extract all double stars brighter + than fifth magnitude + + [#row >= 125 && #row <= 175] - Extract row numbers 125 through 175 + + [abs(sin(theta * #deg)) < 0.5] - Extract all rows having the + absolute value of the sine of theta + less than a half where the angles + are tabulated in degrees + + [@rowFilter.txt] - Extract rows using the expression + contained within the text file + rowFilter.txt + + [gtifilter()] - Search the current file for a GTI + extension, filter the TIME + column in the current table, using + START/STOP times taken from + columns in the GTI extension + + [regfilter("pow.reg")] - Extract rows which have a coordinate + (as given in the X and Y columns) + within the spatial region specified + in the pow.reg region file. +\end{verbatim} + +\newpage +\subsection{Combined Filtering Examples} + +The previous sections described all the individual types of filters +that may be applied to the input file. In this section we show +examples which combine several different filters at once. These +examples all use the {\tt fitscopy} program that is distributed with +the CFITSIO code. It simply copies the input file to the output file. + +\begin{verbatim} +fitscopy rosat.fit out.fit +\end{verbatim} + +This trivial example simply makes an identical copy of the input +rosat.fit file without any filtering. + +\begin{verbatim} +fitscopy 'rosat.fit[events][col Time;X;Y][#row < 1000]' out.fit +\end{verbatim} + +The output file contains only the Time, X, and Y columns, and only +the first 999 rows from the 'EVENTS' table extension of the input file. +All the other HDUs in the input file are copied to the output file +without any modification. + +\begin{verbatim} +fitscopy 'rosat.fit[events][PI < 50][bin (Xdet,Ydet) = 16]' image.fit +\end{verbatim} + +This creates an output image by binning the Xdet and Ydet columns of +the events table with a pixel binning factor of 16. Only the rows +which have a PI energy less than 50 are used to construct this image. +The output image file contains a primary array image without any +extensions. + +\begin{verbatim} +fitscopy 'rosat.fit[events][gtifilter() && regfilter("pow.reg")]' out.fit +\end{verbatim} + +The filtering expression in this example uses the {\tt gtifilter} +function to test whether the TIME column value in each row is within +one of the Good Time Intervals defined in the GTI extension in the same +input file, and also uses the {\tt regfilter} function to test if the +position associated with each row (derived by default from the values +in the X and Y columns of the events table) is located within the area +defined in the {\tt pow.reg} text region file (which was previously +created with the {\tt fv/POW} image display program). Only the rows +which satisfy both tests are copied to the output table. + +\begin{verbatim} +fitscopy 'r.fit[evt][PI<50]' stdout | fitscopy stdin[evt][col X,Y] out.fit +\end{verbatim} + +In this somewhat convoluted example, fitscopy is used to first select +the rows from the evt extension which have PI less than 50 and write the +resulting table out to the stdout stream. This is piped to a 2nd +instance of fitscopy (with the Unix `$|$' pipe command) which reads that +filtered FITS file from the stdin stream and copies only the X and Y +columns from the evt table to the output file. + +\begin{verbatim} +fitscopy 'r.fit[evt][col RAD=sqrt((X-#XCEN)**2+(Y-#YCEN)**2)][rad<100]' out.fit +\end{verbatim} + +This example first creates a new column called RAD which gives the +distance between the X,Y coordinate of each event and the coordinate +defined by the XCEN and YCEN keywords in the header. Then, only those +rows which have a distance less than 100 are copied to the output +table. In other words, only the events which are located within 100 +pixel units from the (XCEN, YCEN) coordinate are copied to the output +table. + +\begin{verbatim} +fitscopy 'ftp://heasarc.gsfc.nasa.gov/rosat.fit[events][bin (X,Y)=16]' img.fit +\end{verbatim} + +This example bins the X and Y columns of the hypothetical ROSAT file +at the HEASARC ftp site to create the output image. + +\begin{verbatim} +fitscopy 'raw.fit[i512,512][101:110,51:60]' image.fit +\end{verbatim} + +This example converts the 512 x 512 pixel raw binary 16-bit integer +image to a FITS file and copies a 10 x 10 pixel subimage from it to the +output FITS image. + +\newpage +\section{CFITSIO Error Status Codes} + +The following table lists all the error status codes used by CFITSIO. +Programmers are encouraged to use the symbolic mnemonics (defined in +the file fitsio.h) rather than the actual integer status values to +improve the readability of their code. + +\begin{verbatim} + Symbolic Const Value Meaning + -------------- ----- ----------------------------------------- + 0 OK, no error + SAME_FILE 101 input and output files are the same + TOO_MANY_FILES 103 tried to open too many FITS files at once + FILE_NOT_OPENED 104 could not open the named file + FILE_NOT_CREATED 105 could not create the named file + WRITE_ERROR 106 error writing to FITS file + END_OF_FILE 107 tried to move past end of file + READ_ERROR 108 error reading from FITS file + FILE_NOT_CLOSED 110 could not close the file + ARRAY_TOO_BIG 111 array dimensions exceed internal limit + READONLY_FILE 112 Cannot write to readonly file + MEMORY_ALLOCATION 113 Could not allocate memory + BAD_FILEPTR 114 invalid fitsfile pointer + NULL_INPUT_PTR 115 NULL input pointer to routine + SEEK_ERROR 116 error seeking position in file + + BAD_URL_PREFIX 121 invalid URL prefix on file name + TOO_MANY_DRIVERS 122 tried to register too many IO drivers + DRIVER_INIT_FAILED 123 driver initialization failed + NO_MATCHING_DRIVER 124 matching driver is not registered + URL_PARSE_ERROR 125 failed to parse input file URL + + SHARED_BADARG 151 bad argument in shared memory driver + SHARED_NULPTR 152 null pointer passed as an argument + SHARED_TABFULL 153 no more free shared memory handles + SHARED_NOTINIT 154 shared memory driver is not initialized + SHARED_IPCERR 155 IPC error returned by a system call + SHARED_NOMEM 156 no memory in shared memory driver + SHARED_AGAIN 157 resource deadlock would occur + SHARED_NOFILE 158 attempt to open/create lock file failed + SHARED_NORESIZE 159 shared memory block cannot be resized at the moment + + HEADER_NOT_EMPTY 201 header already contains keywords + KEY_NO_EXIST 202 keyword not found in header + KEY_OUT_BOUNDS 203 keyword record number is out of bounds + VALUE_UNDEFINED 204 keyword value field is blank + NO_QUOTE 205 string is missing the closing quote + BAD_KEYCHAR 207 illegal character in keyword name or card + BAD_ORDER 208 required keywords out of order + NOT_POS_INT 209 keyword value is not a positive integer + NO_END 210 couldn't find END keyword + BAD_BITPIX 211 illegal BITPIX keyword value + BAD_NAXIS 212 illegal NAXIS keyword value + BAD_NAXES 213 illegal NAXISn keyword value + BAD_PCOUNT 214 illegal PCOUNT keyword value + BAD_GCOUNT 215 illegal GCOUNT keyword value + BAD_TFIELDS 216 illegal TFIELDS keyword value + NEG_WIDTH 217 negative table row size + NEG_ROWS 218 negative number of rows in table + COL_NOT_FOUND 219 column with this name not found in table + BAD_SIMPLE 220 illegal value of SIMPLE keyword + NO_SIMPLE 221 Primary array doesn't start with SIMPLE + NO_BITPIX 222 Second keyword not BITPIX + NO_NAXIS 223 Third keyword not NAXIS + NO_NAXES 224 Couldn't find all the NAXISn keywords + NO_XTENSION 225 HDU doesn't start with XTENSION keyword + NOT_ATABLE 226 the CHDU is not an ASCII table extension + NOT_BTABLE 227 the CHDU is not a binary table extension + NO_PCOUNT 228 couldn't find PCOUNT keyword + NO_GCOUNT 229 couldn't find GCOUNT keyword + NO_TFIELDS 230 couldn't find TFIELDS keyword + NO_TBCOL 231 couldn't find TBCOLn keyword + NO_TFORM 232 couldn't find TFORMn keyword + NOT_IMAGE 233 the CHDU is not an IMAGE extension + BAD_TBCOL 234 TBCOLn keyword value < 0 or > rowlength + NOT_TABLE 235 the CHDU is not a table + COL_TOO_WIDE 236 column is too wide to fit in table + COL_NOT_UNIQUE 237 more than 1 column name matches template + BAD_ROW_WIDTH 241 sum of column widths not = NAXIS1 + UNKNOWN_EXT 251 unrecognizable FITS extension type + UNKNOWN_REC 252 unknown record; 1st keyword not SIMPLE or XTENSION + END_JUNK 253 END keyword is not blank + BAD_HEADER_FILL 254 Header fill area contains non-blank chars + BAD_DATA_FILL 255 Illegal data fill bytes (not zero or blank) + BAD_TFORM 261 illegal TFORM format code + BAD_TFORM_DTYPE 262 unrecognizable TFORM datatype code + BAD_TDIM 263 illegal TDIMn keyword value + BAD_HEAP_PTR 264 invalid BINTABLE heap pointer is out of range + + BAD_HDU_NUM 301 HDU number < 1 or > MAXHDU + BAD_COL_NUM 302 column number < 1 or > tfields + NEG_FILE_POS 304 tried to move to negative byte location in file + NEG_BYTES 306 tried to read or write negative number of bytes + BAD_ROW_NUM 307 illegal starting row number in table + BAD_ELEM_NUM 308 illegal starting element number in vector + NOT_ASCII_COL 309 this is not an ASCII string column + NOT_LOGICAL_COL 310 this is not a logical datatype column + BAD_ATABLE_FORMAT 311 ASCII table column has wrong format + BAD_BTABLE_FORMAT 312 Binary table column has wrong format + NO_NULL 314 null value has not been defined + NOT_VARI_LEN 317 this is not a variable length column + BAD_DIMEN 320 illegal number of dimensions in array + BAD_PIX_NUM 321 first pixel number greater than last pixel + ZERO_SCALE 322 illegal BSCALE or TSCALn keyword = 0 + NEG_AXIS 323 illegal axis length < 1 + + NOT_GROUP_TABLE 340 Grouping function error + HDU_ALREADY_MEMBER 341 + MEMBER_NOT_FOUND 342 + GROUP_NOT_FOUND 343 + BAD_GROUP_ID 344 + TOO_MANY_HDUS_TRACKED 345 + HDU_ALREADY_TRACKED 346 + BAD_OPTION 347 + IDENTICAL_POINTERS 348 + BAD_GROUP_ATTACH 349 + BAD_GROUP_DETACH 350 + + NGP_NO_MEMORY 360 malloc failed + NGP_READ_ERR 361 read error from file + NGP_NUL_PTR 362 null pointer passed as an argument. + Passing null pointer as a name of + template file raises this error + NGP_EMPTY_CURLINE 363 line read seems to be empty (used + internally) + NGP_UNREAD_QUEUE_FULL 364 cannot unread more then 1 line (or single + line twice) + NGP_INC_NESTING 365 too deep include file nesting (infinite + loop, template includes itself ?) + NGP_ERR_FOPEN 366 fopen() failed, cannot open template file + NGP_EOF 367 end of file encountered and not expected + NGP_BAD_ARG 368 bad arguments passed. Usually means + internal parser error. Should not happen + NGP_TOKEN_NOT_EXPECT 369 token not expected here + + BAD_I2C 401 bad int to formatted string conversion + BAD_F2C 402 bad float to formatted string conversion + BAD_INTKEY 403 can't interpret keyword value as integer + BAD_LOGICALKEY 404 can't interpret keyword value as logical + BAD_FLOATKEY 405 can't interpret keyword value as float + BAD_DOUBLEKEY 406 can't interpret keyword value as double + BAD_C2I 407 bad formatted string to int conversion + BAD_C2F 408 bad formatted string to float conversion + BAD_C2D 409 bad formatted string to double conversion + BAD_DATATYPE 410 illegal datatype code value + BAD_DECIM 411 bad number of decimal places specified + NUM_OVERFLOW 412 overflow during datatype conversion + DATA_COMPRESSION_ERR 413 error compressing image + DATA_DECOMPRESSION_ERR 414 error uncompressing image + + BAD_DATE 420 error in date or time conversion + + PARSE_SYNTAX_ERR 431 syntax error in parser expression + PARSE_BAD_TYPE 432 expression did not evaluate to desired type + PARSE_LRG_VECTOR 433 vector result too large to return in array + PARSE_NO_OUTPUT 434 data parser failed not sent an out column + PARSE_BAD_COL 435 bad data encounter while parsing column + PARSE_BAD_OUTPUT 436 Output file not of proper type + + ANGLE_TOO_BIG 501 celestial angle too large for projection + BAD_WCS_VAL 502 bad celestial coordinate or pixel value + WCS_ERROR 503 error in celestial coordinate calculation + BAD_WCS_PROJ 504 unsupported type of celestial projection + NO_WCS_KEY 505 celestial coordinate keywords not found + APPROX_WCS_KEY 506 approximate wcs keyword values were returned +\end{verbatim} + +\end{document} |