.help fimgcreate Sept95 ftools.futils
.ih
NAME
fimgcreate --  Create a FITS primary array image from an ASCII template file.
.ih
USAGE
fimgcreate bitpix naxes datafile outfile	
.ih
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 
.ih
PARAMETERS
.ls bitpix = "" [integer]
The value for the FITS BITPIX keyword which defines the datatype
of the image.  The following values are allowed:
.nf
         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
.fi
.le
.ls naxes = "" [character string]
List giving the size of each axis in the image.  The numbers must
be separated by commas with no white space.
.le 
.ls 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
.nf

  BLANK = value  / This is the value of undefined pixels

.fi
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.
.le
.ls 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.
.le
.ls (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:
.ls
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.
.le
.le
.ls (nskip = 0) 
Number of rows at the beginning of the data template file to skip inclusive
of any blank rows or rows beginning with '#'.
.le
.ls (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.
.le
.ls (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.
.le
.ls (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.
.le
.ls (clobber = no) [boolean]
If true, an existing file with the same name as the requested output file
will be overwritten.
.le
.ih
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'.
.nf

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

.fi
.ih
BUGS
.ih
SEE ALSO
ftimgcreate, ftcreate, ftlist, fthedit
.endhelp
