ftimgcreate HEADAS help file

NAME

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

USAGE

ftimgcreate 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 given is 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 numeric size of each axis in the image. The numbers should be separated by commas with no white space. For the special case of naxes="none", a null image (NAXIS=0) is created.

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 [filename]

The name of the output FITS file.

(headfile = "")

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 ftimgcreate 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 the output file already exists, then setting "clobber = yes" will cause it to be overwritten.

(chatter = 1) [integer, 0 - 5]

Controls the amount of informative text written to standard output. Setting chatter = 5 will produce detailed diagnostic output, otherwise this task normally does not write any output.

(history = NO) [boolean]

If history = YES, then a set of HISTORY keywords will be written to the header of the output file to record the value of all the ftcopy task parameters that were used to produce the output file.

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> ftimgcreate 16 200,300  data.lis outfile.fits headfile=keywords.lis

LAST MODIFIED