.help flst2im July97 ftools.fimage
.ih
NAME
flst2im -- Create an output FITS image file from input list file containing a list of 
the coordinates and respective values.
.ih
USAGE
flst2im infile outfile 
.ih
DESCRIPTION

This task will read input data from either an ASCII file or a FITS
file containing columns of X, Y, and (optionally) VALUE and write as a
FITS image file.  If no VALUE is given (on a per-line basis for an
ASCII file or universally for a FITS file), a value of 1 will be
adopted.  Data for missing X-,Y- pixels are assigned zero.  Multiply-listed
pixels have their VALUEs summed.

An ASCII input file consists of any number of rows each containing 2
or 3 values separated by commas and/or whitespace. Blank rows or rows
starting with '#' are ignored.

If VALUE consists of all integers, the output image will default to
bitpix=32.  If at least one VALUE is real (or the FITS column type of
VALUE is real), the output image will have bitpix=-32, unless
overridden with the datatype parameter.

.ih
PARAMETERS
.ls infile [filename]
Name of the input ASCII/FITS file with extension.  Extension is
assumed to be 1, unless it is mentioned.
.le
.ls outfile [filename]
The name of the FITS image file to which the image is written.  It is
written in the primary extension.
.le
.ls (xcol = X) [string]
Name for the column in the input FITS file containing the X coordinate of
the pixel.
.le
.ls (ycol = Y) [string]
Name for the column in the input FITS file containing the Y coordinate of
the pixel.
.le
.ls (value = VALUE) [string]
Name of the column in the input FITS file containing the value of the pixel.
If blank or set to '-', each listed X,Y pixel will be assigned a value of 1.
.le
.ls xrange [string]
Range of x values to be included in the image. e.g 10.,20. If input is INDEF,
then xrange is calculated from minimum and maximum x-values. The ranges can
be separated by either TAB,comma or a blank space.
.le
.ls yrange [string]
Range of y values to be included in the image. e.g 10.,20. If input is INDEF,
then yrange is calculated from minimum and maximum y-values. The ranges can
be separated by either TAB,comma or a blank space.
.le
.ls rows [string]
The range of rows to be input. The default of '-'  means all rows are to be 
included. The first ten rows could be specified as 1-10 or just '-10'.  
To include the first  ten  rows  and  all  rows from  900  through  the  last  
(inclusive),  use 1-10,900-. Also '1,3,7,23 will' include only those four rows.
.le
.ls (nxbin = INDEF) [integer]
Number of bins in x-direction.  If INDEF, xrange will be interpretted
as an inclusive range with a unit binsize, such that nxbin =
Xmax-Xmin+1. Otherwise, xrange will be interpretted as a bounding box
with Xmax values excluded.
.le
.ls (nybin = INDEF) [integer]
Number of bins in y-direction.  If INDEF, yrange will be interpretted
as an inclusive range with a unit binsize, such that nybin =
Ymax-Ymin+1. Otherwise, yrange will be interpretted as a bounding box
with Ymax values excluded.
.le
.ls (datatype = ' ') [string]
The datatype (or bits/pixel) of the output image.  If blank or "-", 
the bitpix of the output image will be 32 or -32, depending on the
datatype of the VALUE.
Acceptable inputs are (b,8), (i,short,16), (j,integer,int,long,32),
(r,f,e,real,float,-32) and (d,double,-64).
.le
.ls (clobber = false) [integer]
Flag  specifying  whether  or  not a pre-existing file with the same name as that 
requested as the output file from  this  task will be overwritten.
.le
.ih
EXAMPLES 
1.  Construct an image file "image.fits" from an input file "list" 

    ft> flst2im list image.fits 

2. as above, but with dimension as 512X512

    ft> flst2im list image.fits nxbin=512 nybin=512

3. if name of Xcolumn is XCOLUMN, then

    ft> flst2im list image.fits xcol=XCOLUMN
    

.ih
NOTES:
FLST2IM uses dynamic memory to read in the entire list and construct an image list
at one time. If the requested list is larger than the available system memory, an 
error will be reported
.ih
BUGS
Unknown

.ih
SEE ALSO
.br
.nj
fim2lst
.br
.nj
.ih
LOG OF SIGNIFICANT CHANGES
.ls v1.0.0 (1997 July)
    Initial public release
.le
.ih
PRIMARY AUTHOR
 
.nj
Banashree M Seifert
.br
.nj
HEASARC
.br
.nj
NASA/GFSC
.br
.nj
http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
.ju


.endhelp
