next up previous contents Back To Software Index
Next: 1's Based Index Up: Basic CFITSIO Conventions Previous: Defined Symbolic Constants

Unsigned Integers

Although FITS does not directly support unsigned integers as one of its basic datatypes, FITS can still be used to efficiently store unsigned integer data values in images and binary tables. The convention used in FITS files is to store the unsigned integers as signed integers with an appropriate offset (as specified by the BZERO or TZEROn keywords). For example, to store unsigned 16-bit integer values in a FITS image, the image would be defined as a signed 16-bit integer (BITPIX keyword = 16) with the keywords BSCALE = 1.0 and BZERO = 32768. Thus the unsigned values of 0, 32768, and 65535 would be physically stored in the FITS image as -32768, 0, and 32767, respectively, and CFITSIO will automatically add the BZERO offset to these values when they are read. In the case of unsigned 32-bit integers, the BITBIX keyword would be equal to 32 and BZERO would be equal to 2147483648 (i.e. 2 raised to the 31st power).

The CFITSIO interface routines will efficiently and transparently apply the appropriate offset in these cases, so in general, application programs do not need to be concerned with how the unsigned values are actually stored in the FITS file. As a convenience for users, CFITSIO has several predefined constants for the value of BITPIX (USHORT_IMG, ULONG_IMG) and for the TFORMn value in the case of binary tables (`U' and `V') which programmers can use when creating FITS files containing unsigned integer values. For example, the following code fragment illustrates how to write a FITS 1-D primary array of unsigned 16-bit integers:

      unsigned short uarray[100];
      int naxis, status;
      long naxes[10], group, firstelem, nelements;
       ...
      status = 0;
      naxis = 1;
      naxes[0] = 100;
      fits_write_imghdr(fptr, USHORT_IMG, naxis, naxes, &status);

      group = 1;
      firstelem = 1;
      nelements = 100;
      fits_write_img_usht(fptr, group, firstelem, nelements,
                          uarray, &status);
       ...
In the above example, the 2nd parameter in the call to `fits_write_imghdr' tells CFITSIO to write the header keywords appropriate for an array of 16-bit unsigned integers (i.e., BITPIX = 16 and BZERO = 32768). Then the fits_write_img_usht routine writes the array of unsigned short integers (uarray) into the primary array of the FITS file. Similarly, a 32-bit unsigned integer image may be created by setting the second parameter in fits_write_imghdr equal to `ULONG_IMG' and by calling the fits_write_img_ulng routine to write the array of unsigned long image pixel values.

An analogous set of routines are available for reading or writing unsigned integer values in a FITS binary table extension. When specifying the TFORMn keyword value which defines the format of a column, CFITSIO recognized 2 additional datatype codes besides those already defined in the FITS standard: `U' meaning a 16-bit unsigned integer column, and `V' for a 32-bit unsigned integer column. It must be stressed that these non-standard datatype codes are not actually written into the FITS file, but instead, are just used internally within CFITSIO. The following code fragment illustrates how to use these features:

      unsigned short uarray[100];
      unsigned long  varray[100];

      int colnum, tfields, status;
      long nrows, firstrow, firstelem, nelements, pcount;

      char extname[] = "Test_table";           /* extension name */

      /* define the name, datatype, and physical units for the 2 columns */
      char *ttype[] = { "Col_1", "Col_2" };
      char *tform[] = { "1U",      "1V"   };  /* special CFITSIO codes */
      char *tunit[] = { " ",        " "   };
       ...

           /* write the header keywords */
      status  = 0;
      nrows   = 1;
      tfields = 2
      pcount  = 0;
      fits_write_btblhdr(fptr, nrows, tfields, ttype, tform, tunit,
                extname, pcount, &status);

           /* write the unsigned shorts to the 1st column */
      colnum    = 1;
      firstrow  = 1;
      firstelem = 1;
      nelements = 100;
      fits_write_col_usht(fptr, colnum, firstrow, firstelem,
              nelements, uarray, &status);

           /* now write the unsigned longs to the 2nd column */
      colnum    = 2;
      fits_write_col_ulng(fptr, colnum, firstrow, firstelem,
              nelements, varray, &status);
       ...
Note that the non-standard tform values for the 2 columns, `U' and `V', tell CFITSIO to write the keywords appropriate for unsigned 16-bit and unsigned 32-bit integers, respectively (i.e., TFORMn = '1I' and TSCALn = 32678 for unsigned 16-bit integers, and TFORMn = '1J' and TSCALn = 2147483648 for unsigned 32-bit integers). The calls to fits_write_col_usht and to fits_write_col_ulng then write the arrays of unsigned integer values to the columns.



next up previous contents Back To Software Index
Next: 1's Based Index Up: Basic CFITSIO Conventions Previous: Defined Symbolic Constants