FITSIO Home
Next: 5.6 Image Compression
Up: 5. Basic CFITSIO Interface
Previous: 5.4.2 Keyword Writing Routines
These routines read or write data values in the primary data array (i.e.,
the first HDU in a FITS file) or an IMAGE extension. There are also
routines to get information about the data type and size of the image.
Users should also read the following chapter on the CFITSIO iterator
function which provides a more `object oriented' method of reading and
writing images. The iterator function is a little more complicated to
use, but the advantages are that it usually takes less code to perform
the same operation, and the resulting program oftens runs faster because
the FITS files are read and written using the most efficient block size.
C programmers should note that the ordering of arrays in FITS files, and
hence in all the CFITSIO calls, is more similar to the dimensionality
of arrays in Fortran rather than C. For instance if a FITS image has
NAXIS1 = 100 and NAXIS2 = 50, then a 2-D array just large enough to hold
the image should be declared as array[50][100] and not as array[100][50].
The `datatype' parameter specifies the data type of the `nulval' and
`array' pointers and can have one of the following values: TBYTE,
TSBYTE, TSHORT, TUSHORT, TINT, TUINT, TLONG, TLONGLONG, TULONG, TFLOAT,
TDOUBLE. Automatic data type conversion is performed if the data type
of the FITS array (as defined by the BITPIX keyword) differs from that
specified by 'datatype'. The data values are also automatically scaled
by the BSCALE and BZERO keyword values as they are being read or written
in the FITS array.
- 1
- Get the data type or equivalent data type of the image. The
first routine returns the physical data type of the FITS image, as
given by the BITPIX keyword, with allowed values of BYTE_IMG (8),
SHORT_IMG (16), LONG_IMG (32), FLOAT_IMG (-32), and DOUBLE_IMG
(-64). The second routine is similar, except that if the image pixel
values are scaled, with non-default values for the BZERO and BSCALE
keywords, then the routine will return the 'equivalent' data type
that is needed to store the scaled values. For example, if BITPIX
= 16 and BSCALE = 0.1 then the equivalent data type is FLOAT_IMG.
Similarly if BITPIX = 16, BSCALE = 1, and BZERO = 32768, then the
the pixel values span the range of an unsigned short integer and
the returned data type will be USHORT_IMG.
int fits_get_img_type / ffgidt
(fitsfile *fptr, > int *bitpix, int *status)
int fits_get_img_equivtype / ffgiet
(fitsfile *fptr, > int *bitpix, int *status)
- 2
- Get the number of dimensions, and/or the size of
each dimension in the image . The number of axes in the image is
given by naxis, and the size of each dimension is given by the
naxes array (a maximum of maxdim dimensions will be returned).
int fits_get_img_dim / ffgidm
(fitsfile *fptr, > int *naxis, int *status)
int fits_get_img_size / ffgisz
(fitsfile *fptr, int maxdim, > long *naxes, int *status)
int fits_get_img_param / ffgipr
(fitsfile *fptr, int maxdim, > int *bitpix, int *naxis, long *naxes,
int *status)
- 3
- Create a new primary array or IMAGE extension with a specified
data type and size. If the FITS file is currently empty then a
primary array is created, otherwise a new IMAGE extension is
appended to the file.
int fits_create_img / ffcrim
( fitsfile *fptr, int bitpix, int naxis, long *naxes, > int *status)
- 4
- Write a rectangular subimage (or the whole image) to the FITS data
array. The fpixel and lpixel arrays give the coordinates of the
first (lower left corner) and last (upper right corner) pixels in
FITS image to be written to.
int fits_write_subset / ffpss
(fitsfile *fptr, int datatype, long *fpixel, long *lpixel,
DTYPE *array, > int *status)
- 5
- Write pixels into the FITS data array. 'fpixel' is an array of
length NAXIS which gives the coordinate of the starting pixel to be
written to, such that fpixel[0] is in the range 1 to NAXIS1,
fpixel[1] is in the range 1 to NAXIS2, etc. The first routine
simply writes the array of pixels to the FITS file (doing data type
conversion if necessary) whereas the second routine will substitute
the appropriate FITS null value for any elements which are equal to
the input value of nulval (note that this parameter gives the
address of the null value, not the null value itself). For integer
FITS arrays, the FITS null value is defined by the BLANK keyword (an
error is returned if the BLANK keyword doesn't exist). For floating
point FITS arrays the special IEEE NaN (Not-a-Number) value will be
written into the FITS file. If a null pointer is entered for
nulval, then the null value is ignored and this routine behaves
the same as fits_write_pix.
int fits_write_pix / ffppx
(fitsfile *fptr, int datatype, long *fpixel, long nelements,
DTYPE *array, int *status);
int fits_write_pixnull / ffppxn
(fitsfile *fptr, int datatype, long *fpixel, long nelements,
DTYPE *array, DTYPE *nulval, > int *status);
- 6
- Set FITS data array elements equal to the appropriate null pixel
value. For integer FITS arrays, the FITS null value is defined by
the BLANK keyword (an error is returned if the BLANK keyword
doesn't exist). For floating point FITS arrays the special IEEE NaN
(Not-a-Number) value will be written into the FITS file. Note that
'firstelem' is a scalar giving the offset to the first pixel to be
written in the equivalent 1-dimensional array of image pixels.
int fits_write_null_img / ffpprn
(fitsfile *fptr, long firstelem, long nelements, > int *status)
- 7
- Read a rectangular subimage (or the whole image) from the FITS
data array. The fpixel and lpixel arrays give the coordinates of
the first (lower left corner) and last (upper right corner) pixels
to be read from the FITS image. Undefined FITS array elements will
be returned with a value = *nullval, (note that this parameter
gives the address of the null value, not the null value itself)
unless nulval = 0 or *nulval = 0, in which case no checks for
undefined pixels will be performed.
int fits_read_subset / ffgsv
(fitsfile *fptr, int datatype, long *fpixel, long *lpixel, long *inc,
DTYPE *nulval, > DTYPE *array, int *anynul, int *status)
- 8
- Read pixels from the FITS data array. 'fpixel' is the starting
pixel location and is an array of length NAXIS such that fpixel[0]
is in the range 1 to NAXIS1, fpixel[1] is in the range 1 to NAXIS2,
etc. The nelements parameter specifies the number of pixels to
read. If fpixel is set to the first pixel, and nelements is set
equal to the NAXIS1 value, then this routine would read the first
row of the image. Alternatively, if nelements is set equal to
NAXIS1 * NAXIS2 then it would read an entire 2D image, or the first
plane of a 3-D datacube.
The first routine will return any undefined pixels in the FITS array
equal to the value of *nullval (note that this parameter gives the
address of the null value, not the null value itself) unless nulval
= 0 or *nulval = 0, in which case no checks for undefined pixels
will be performed. The second routine is similar except that any
undefined pixels will have the corresponding nullarray element set
equal to TRUE (= 1).
int fits_read_pix / ffgpxv
(fitsfile *fptr, int datatype, long *fpixel, long nelements,
DTYPE *nulval, > DTYPE *array, int *anynul, int *status)
int fits_read_pixnull / ffgpxf
(fitsfile *fptr, int datatype, long *fpixel, long nelements,
> DTYPE *array, char *nullarray, int *anynul, int *status)
FITSIO Home
Next: 5.6 Image Compression
Up: 5. Basic CFITSIO Interface
Previous: 5.4.2 Keyword Writing Routines