ftimgcreate - Create a FITS primary array image from an ASCII
ftimgcreate bitpix naxes datafile outfile
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.
- 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
- 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,
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
- (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
- (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.
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
The design of this task is based on the fimgcreate task
in the ftools package.