NAME

fimgcreate -- Create a FITS primary array image from an ASCII template file.


USAGE

        fimgcreate bitpix naxes datafile outfile        

DESCRIPTION

This task creates a new FITS primary array image from the data values in the input ASCII template file. If the ascii datafile is given none/NONE, then the task creates an empty image file with pixel value 0.0


PARAMETERS

bitpix = "" [integer]
The value for the FITS BITPIX keyword which defines the datatype of the image. The following values are allowed:

                      8 - unsigned (8-bit) byte
                     16 - short (16-bit) signed integer
                     32 - long (32-bit) signed integer
                    -32 - single precision floating point
                    -64 - double precision floating point

naxes = "" [character string]
List giving the size of each axis in the image. The numbers must be separated by commas with no white space.

datafile = "" [file name]
The name of the input ASCII formatted data file containing the list of pixel values for the image. Each line of the file may be up to 30000 characters in length and contains less than 3000 pixel values. This task will continue reading through the data file until it has read the required number of pixel values, as determined by the product of the axis sizes. The data format of the pixel values does not need to match the data format implied by BITPIX since the formats will automatically be converted if necessary.

Case when datafile=none, the task creates an image file with pixel values=0.0. When datafile=-, the data is read from stdin.

Note that FITS images follow the convention of fortran arrays where pixels are stored such that the first array index varies most rapidly. For example, for a 2 dimensional N x M array, the pixels are stored in order of (1,1), (2,1), (3,1), ..., (N,1), (1,2), (2,2), ..., (N,2), ..., (N,M).

In the case of integer datatypes (BITPIX = 8, 16, or 32) one may choose any legal integer value (i.e., within the range of the data type) to represent undefined pixels. The `BLANK' FITS header keyword with the format

             
               BLANK = value  / This is the value of undefined pixels
             

where `value' is the integer null pixel value, should be added to the header by including it in the ASCII file specified by the HEADFILE parameter. For floating point format images (BITPIX = -32 or -64) a special IEEE NaN value is used to flag any undefined pixels and the BLANK keyword must not be use. In this case one may use the NULLVAL parameter to specify the data value in the input template file which is used to represent null values. If the NULLTEST parameter is set = yes, then the IEEE NaN value will be written in the FITS image in place of this value.

outfile = "" [FITS file name]
The name of the output FITS file. If preceeded by a !, then any existing file of the same name will be overwritten.

(headfile = "") [file name]
The name of the optional file of header keywords. Each line of this file defines one keyword, except that blank lines and lines beginning with # will be ignored. Each line should usually contain three tokens: (1) the KEYNAME, (2) the VALUE, and (3) the COMMENT string and must adhere to the following format rules:

The KEYNAME token must begin in columns 1-8 and be a maximum of 8 characters long. If the first 8 characters of the line are blank then the remainder of the line is considered to be a FITS comment (with a blank keyword name). A legal FITS keyword name may only contain the characters A-Z, 0-9, and '-' (minus sign) and '_' (underscore). This task will automatically convert any lowercase characters to uppercase in the FITS file. If KEYNAME = 'COMMENT' or 'HISTORY' then the remainder of the line is considered to be a FITS COMMENT or HISTORY record, respectively.

The VALUE token must be separated from the KEYNAME token by one or more spaces and/or an '=' character. The datatype of the VALUE token (numeric, logical, or character string) is automatically determined and the output FITS header record is formatted accordingly. Logical keyword values are represented by a T or F (not enclosed in quotes). The value token may be forced to be interpreted as a string (e.g. if it is a string of numeric digits) by enclosing it in single quotes.

The COMMENT token is optional, but if present must be separated from the VALUE token by at least one blank space. A leading '/' character may be used to mark the beginning of the comment field, otherwise the comment field begins with the first non-blank character following the value token.

(nskip = 0)
Number of rows at the beginning of the data template file to skip inclusive of any blank rows or rows beginning with '#'.

(history = TRUE)
If TRUE than a HISTORY keyword will be appended to the output FITS file giving the date that the file was created with the fimgcreate task.

(nulltest = FALSE)
As explained above, if NULLTEST = TRUE, than any pixels in the input ASCII data file which have a value equal to the NULLVAL parameter will be designated as undefined pixels by setting the pixel value in the FITS file equal to the IEEE NaN. This only applies to FITS files with BITPIX = -32 or -64.

(nullval = "")
The floating point value that is used in conjunction with the NULLTEST parameter to flag undefined pixels in the input image. Only applies if BITPIX = -32 or -64.

(clobber = no) [boolean]
If true, an existing file with the same name as the requested output file will be overwritten.


EXAMPLES

1. Create a FITS image called 'outfile.fits' containing 200 x 300 short-integer pixels from a data file called 'data.lis' and a header file called 'keywords.lis'.

     
       ft> fimgcreate 16 200,300  data.lis outfile.fits headfile=keywords.lis
     


BUGS


SEE ALSO

ftimgcreate, ftcreate, ftlist, fthedit

CATEGORY

Sept95 ftools.futils