6.6 FITS Primary Array or IMAGE Extension I/O Subroutines

These subroutines put or get data values in the primary data array (i.e., the first HDU in the FITS file) or an IMAGE extension. The data array is represented as a single one-dimensional array of pixels regardless of the actual dimensionality of the array, and the FPIXEL parameter gives the position within this 1-D array of the first pixel to read or write. Automatic data type conversion is performed for numeric data (except for complex data types) if the data type of the primary array (defined by the BITPIX keyword) differs from the data type of the array in the calling subroutine. The data values are also scaled by the BSCALE and BZERO header values as they are being written or read from the FITS array. The ftpscl subroutine MUST be called to define the scaling parameters when writing data to the FITS array or to override the default scaling value given in the header when reading the FITS array.

Two sets of subroutines are provided to read the data array which differ in the way undefined pixels are handled. The first set of routines (FTGPVx) simply return an array of data elements in which undefined pixels are set equal to a value specified by the user in the 'nullval' parameter. An additional feature of these subroutines is that if the user sets nullval = 0, then no checks for undefined pixels will be performed, thus increasing the speed of the program. The second set of routines (FTGPFx) returns the data element array and, in addition, a logical array which defines whether the corresponding data pixel is undefined. The latter set of subroutines may be more convenient to use in some circumstances, however, it requires an additional array of logical values which can be unwieldy when working with large data arrays. Also for programmer convenience, sets of subroutines to directly read or write 2 and 3 dimensional arrays have been provided, as well as a set of subroutines to read or write any contiguous rectangular subset of pixels within the n-dimensional array.

1: Get the data type of the image (= BITPIX value). Possible returned values are: 8, 16, 32, 64, -32, or -64 corresponding to unsigned byte, signed 2-byte integer, signed 4-byte integer, signed 8-byte integer, real, and double.
The second subroutine is similar to FTGIDT, except that if the image pixel values are scaled, with non-default values for the BZERO and BSCALE keywords, then this 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 floating point, and -32 will be returned. There are 2 special cases: if the image contains unsigned 2-byte integer values, with BITPIX = 16, BSCALE = 1, and BZERO = 32768, then this routine will return a non-standard value of 20 for the bitpix value. Similarly if the image contains unsigned 4-byte integers, then bitpix will be returned with a value of 40.

        FTGIDT(unit, > bitpix,status)
        FTGIET(unit, > bitpix,status)

2: Get the dimension (number of axes = NAXIS) of the image

        FTGIDM(unit, > naxis,status)

3: Get the size of all the dimensions of the image. The FTGISZLL routine returns an array of 64-bit integers instead of 32-bit integers.

        FTGISZ(unit, maxdim, > naxes,status)
        FTGISZLL(unit, maxdim, > naxesll,status)

4: Get the parameters that define the type and size of the image. This routine simply combines calls to the above 3 routines. The FTGIPRLL routine returns an array of 64-bit integers instead of 32-bit integers.

        FTGIPR(unit, maxdim, > bitpix, naxis, naxes, int *status)
        FTGIPRLL(unit, maxdim, > bitpix, naxis, naxesll, int *status)

5: Put elements into the data array. The FTPPR[]LL routines accept 64-bit integers for fpixel and nelements.

        FTPPR[BIJKED](unit,group,fpixel,nelements,values, > status)
        FTPPR[BIJKED]LL(unit,group,fpixelll,nelementsll,values, > status)

6: Put elements into the data array, substituting the appropriate FITS null value for all elements which are equal to the value of NULLVAL. For integer FITS arrays, the null value defined by the previous call to FTPNUL will be substituted; for floating point FITS arrays (BITPIX = -32 or -64) then the special IEEE NaN (Not-a-Number) value will be substituted. The FTPPN[]LL routines accept 64-bit integers for fpixel and nelements.

        FTPPN[BIJKED](unit,group,fpixel,nelements,values,nullval > status)
        FTPPN[BIJKED]LL(unit,group,fpixelll,nelementsll,values,nullval > status)

7: Set data array elements as undefined. FTPPRULL accepts 64-bit integers for fpixel and nelements.

        FTPPRU(unit,group,fpixel,nelements, > status)
        FTPPRULL(unit,group,fpixelll,nelementsll, > status)

8: Get elements from the data array. Undefined array elements will be returned with a value = nullval, unless nullval = 0 in which case no checks for undefined pixels will be performed. FTGPV[]LL accepts 64-bit integers for fpixel and nelements.

        FTGPV[BIJKED](unit,group,fpixel,nelements,nullval, > values,anyf,status)
        FTGPV[BIJKED]LL(unit,group,fpixelll,nelementsll,nullval, > values,anyf,status)

9: Get elements and nullflags from data array. Any undefined array elements will have the corresponding flagvals element set equal to .TRUE.

        FTGPF[BIJKED](unit,group,fpixel,nelements, > values,flagvals,anyf,status)

10: Put values into group parameters

        FTPGP[BIJKED](unit,group,fparm,nparm,values, > status)

11: Get values from group parameters

        FTGGP[BIJKED](unit,group,fparm,nparm, > values,status)

The following 4 subroutines transfer FITS images with 2 or 3 dimensions to or from a data array which has been declared in the calling program. The dimensionality of the FITS image is passed by the naxis1, naxis2, and naxis3 parameters and the declared dimensions of the program array are passed in the dim1 and dim2 parameters. Note that the program array does not have to have the same dimensions as the FITS array, but must be at least as big. For example if a FITS image with NAXIS1 = NAXIS2 = 400 is read into a program array which is dimensioned as 512 x 512 pixels, then the image will just fill the lower left corner of the array with pixels in the range 1 - 400 in the X an Y directions. This has the effect of taking a contiguous set of pixel value in the FITS array and writing them to a non-contiguous array in program memory (i.e., there are now some blank pixels around the edge of the image in the program array).

11: Put 2-D image into the data array

        FTP2D[BIJKED](unit,group,dim1,naxis1,naxis2,image, > status)

12: Put 3-D cube into the data array

        FTP3D[BIJKED](unit,group,dim1,dim2,naxis1,naxis2,naxis3,cube, > status)

13: Get 2-D image from the data array. Undefined pixels in the array will be set equal to the value of 'nullval', unless nullval=0 in which case no testing for undefined pixels will be performed.

        FTG2D[BIJKED](unit,group,nullval,dim1,naxis1,naxis2, > image,anyf,status)

14: Get 3-D cube from the data array. Undefined pixels in the array will be set equal to the value of 'nullval', unless nullval=0 in which case no testing for undefined pixels will be performed.

        FTG3D[BIJKED](unit,group,nullval,dim1,dim2,naxis1,naxis2,naxis3, >
                     cube,anyf,status)

The following subroutines transfer a rectangular subset of the pixels in a FITS N-dimensional image to or from an array which has been declared in the calling program. The fpixels and lpixels parameters are integer arrays which specify the starting and ending pixels in each dimension of the FITS image that are to be read or written. (Note that these are the starting and ending pixels in the FITS image, not in the declared array). The array parameter is treated simply as a large one-dimensional array of the appropriate datatype containing the pixel values; The pixel values in the FITS array are read/written from/to this program array in strict sequence without any gaps; it is up to the calling routine to correctly interpret the dimensionality of this array. The two families of FITS reading routines (FTGSVx and FTGSFx subroutines) also have an 'incs' parameter which defines the data sampling interval in each dimension of the FITS array. For example, if incs(1)=2 and incs(2)=3 when reading a 2-dimensional FITS image, then only every other pixel in the first dimension and every 3rd pixel in the second dimension will be returned in the 'array' parameter. [Note: the FTGSSx family of routines which were present in previous versions of FITSIO have been superseded by the more general FTGSVx family of routines.]

15: Put an arbitrary data subsection into the data array.

        FTPSS[BIJKED](unit,group,naxis,naxes,fpixels,lpixels,array, > status)

16: Get an arbitrary data subsection from the data array. Undefined pixels in the array will be set equal to the value of 'nullval', unless nullval=0 in which case no testing for undefined pixels will be performed.

        FTGSV[BIJKED](unit,group,naxis,naxes,fpixels,lpixels,incs,nullval, >
                     array,anyf,status)

17: Get an arbitrary data subsection from the data array. Any Undefined pixels in the array will have the corresponding 'flagvals' element set equal to .TRUE.

        FTGSF[BIJKED](unit,group,naxis,naxes,fpixels,lpixels,incs, >
                     array,flagvals,anyf,status)