Austin Duncan (a5duncan@yahoo.com)

Summary of cfitsio routines that could be used to read fits data files

The fits reading routines that are in the cfitsio library are vey similar to the file reading routines in C.  The general steps are opening a file handle, reading the header, then the image, and closing the file handle.

To read a fits file:

  // The variables that are going to be used
  fitsfile *fptr;
  int status, nkeys, keypos, hdutype, ii, jj;
  char *filename = "/home/aduncan/dat/fits/hsi_filedb_200302.fits";
  char card[FLEN_CARD];
  float vers;


1)  Open a file handle with the following command:

    fits_open_file(&fptr, filename, READONLY, &status);

    Now the fitsfile pointer, fptr, is pointing to the beginning of the data file.

    The third parameter sets the access permissions on the file.  The readonly access
    set by a 0.  Read/write access is set by a 1.

    The fourth parameter in the function is for returning information to the user about
    whether or not the function was completed.

2)  Now the header has to be read.  The following commands read in the header and print
    out the information:

  if ( fits_open_file(&fptr, filename, READONLY, &status) )
    fprintf(stderr, "error");

  // Moves fptr until at the end of the header
  for (ii = 1; !(fits_movabs_hdu(fptr, ii, &hdutype, &status) ); ii++) {

    if (fits_get_hdrpos(fptr, &nkeys, &keypos, &status) )
      fprintf(stderr, "error");

    // Reads the parameter
    for (jj = 1; jj <= nkeys; jj++)  {

      if ( fits_read_record(fptr, jj, card, &status) )
        fprintf(stderr, "error");

      printf("%s\n", card); /* print the keyword card */

    }

    printf("END\n\n");  /* terminate listing with END */

  }

  // Closes the file access
  if ( fits_close_file(fptr, &status) )
    fprintf(stderr, "error");

3)  Now the image has to be read.  The following commands will search the header for the
    size of the data and then read in the data:

    fitsfile *fptr;       /* pointer to the FITS file, defined in fitsio.h */
    int status,  nfound, anynull;
    long naxes[2], fpixel, nbuffer, npixels, ii;

    #define buffsize 1000
    float datamin, datamax, nullval, buffer[buffsize];
    char filename[]  = "atestfil.fit";     /* name of existing FITS file   */

    status = 0;

    if ( fits_open_file(&fptr, filename, READONLY, &status) )
         printerror( status );

    // Searches the header for the data size information
    if ( fits_read_keys_lng(fptr, "NAXIS", 1, 2, naxes, &nfound, &status) )
         printerror( status );

    npixels  = naxes[0] * naxes[1];         /* number of pixels in the image */
    fpixel   = 1;
    nullval  = 0;                /* don't check for null values in the image */
    datamin  = 1.0E30;
    datamax  = -1.0E30;

    while (npixels > 0)
    {
      nbuffer = npixels;
      if (npixels > buffsize)
        nbuffer = buffsize;     /* read as many pixels as will fit in buffer */

      /* Note that even though the FITS images contains unsigned integer */
      /* pixel values (or more accurately, signed integer pixels with    */
      /* a bias of 32768),  this routine is reading the values into a    */
      /* float array.   Cfitsio automatically performs the datatype      */
      /* conversion in cases like this.                                  */


      if ( fits_read_img(fptr, TFLOAT, fpixel, nbuffer, &nullval,
                  buffer, &anynull, &status) )
           printerror( status );

      for (ii = 0; ii < nbuffer; ii++)  {
        if ( buffer[ii] < datamin )
            datamin = buffer[ii];

        if ( buffer[ii] > datamax )
            datamax = buffer[ii];
      }
      npixels -= nbuffer;    /* increment remaining number of pixels */
      fpixel  += nbuffer;    /* next pixel to be read in image */
    }

    printf("\nMin and max image pixels =  %.0f, %.0f\n", datamin, datamax);

    if ( fits_close_file(fptr, &status) )
         printerror( status );


    /******************************************
    NOTE: The fits_read_keys_lng is a very useful function because it searches the
    header for a parameter name.
   
    fits_read_keys_lng(fptr, "NAXIS", 1, 2, naxes, &nfound, &status)
     ******************************************/