.help fimgbin Jan91 ftools.fimage
.ih
NAME
fimgbin -- Rebin a FITS image using a rectangular bin size
.ih
USAGE
fimgbin input output xbinsize
.ih
PARAMETERS
.ls infile [file name]
Input FITS file and extension number to be convolved with the rectangular
 boxcar filter.
.le
.ls outfile [file name]
Output FITS file where the convolved image will be written. 
.le
.ls xbinsize [integer]
The number of pixels in the X direction to be binned together into the 
single pixel of the outfile.
.le
.ls (ybinsize = 0) [integer]
The number of pixels in the Y direction to be binned together into the 
single pixel of the outfile. A value less than 1 causes ybinsize to be
the same as the xbinsize. This is the default.
.le
.ls (datatype = "-") [character]
The data type for the resulting smoothed image.  If blank or "-",
defaults are to the bitpix of the input image.
Acceptable inputs are (b,8), (i,short,16), (j,integer,int,long,32),
(r,f,e,real,float,-32) and (d,double,-64). They are case-insensitive.
.le
.ls (overflow = no) [boolean]
Whether to ignore the overflow and underflow in the output file.
If true, the overflow and underflow elements of the output image
array will be ignored and replaced with the maximum and minimum
of the corresponding data type. If false, these elements
will throw an error and terminate the program. This option is only
relevant for byte, short and integer images.
.le
.ls (nullval = 0.0) [double]
Value to substitute for any undefined pixels within the image.
.le
.ls (average = no) [boolean]
This flag is used to cause the pixel count in the output bin to be
normalized by the number of pixels binned up into one (average). By default
the pixel count is simple summed.
.le
.ls (copyprime = yes) [boolean]
If true, all of the primary header keywords, the primary array (if any) 
and all of the extension keywords of the first input file are copied to 
the output file.  If false, only minimal headers are created.
.le
.ls (copyall = no) [boolean]
If true, all other extensions, including the primary array are copied
to the output file.
.le
.ls (clobber = no) [boolean]
If true, an existing output file of the same name will be overwritten.
.le

.ih
DESCRIPTION

FIMGBIN rebins an image by summing the values in each xbinsize by ybinsize
region of the infile into a single value of the outfile. The ybinsize is a
hidden parameter and when its value is less than 1, it defaults to the same
size as the xbinsize. Any pixels in the infile around the right or lower 
boundaries that do not conform to an integer number of bins will be left 
out of the output file. In order to preserve all pixels of the input image
in the output image the image dimension must be divisible by the xbinsize 
and ybinsize parameters.

.ih
EXAMPLES

1. Rebin an image so that each square of 4 by 4 pixels is binned up into a 
single pixel.

    cl> fimgbin image.fits rebin.fits 4

2. Rebin an image so that each square of 3 by 4 pixels is binned up into a 
single pixel and the resulting datatype for the image is real.

    cl> fimgbin img.fits rbimg.fits 3 ybinsize=4 datatype='e'

.ih
BUGS
.ih
SEE ALSO
fboxcar
.endhelp
