idlastro / FITS Astrometry and Calibration: HBOXAVE

[Source code]

NAME
HBOXAVE
PURPOSE
Box average an image array and update the FITS header array
EXPLANATION
The function BOXAVE() is used.  This procedure is recommended for 
integer images when photometric precision is desired, because it 
performs intermediate steps using REAL*4 arithmetic.   Otherwise, the 
procedure HREBIN is much faster.
CALLING SEQUENCE
HBOXAVE, Oldim, Oldhd, Newim, Hewhd, box
        or
HBOXAVE, Oldim, Oldhd, box
INPUTS
Oldim - the original image array
Oldhd - the original image FITS header, string array
OPTIONAL INPUTS
box - the box size to be used, integer scalar.  If omitted, then
        HBOXAVE will prompt for this parameter.
OPTIONAL OUTPUTS
Newim - the image after boxaveraging
Newhd - header for newim containing updated astrometry info
        If output parameters are not supplied, the program
        will modify the input parameters OLDIM and OLDHD
        to contain the new array and updated header.
OPTIONAL KEYWORD OUTPUT
ERRMSG - If this keyword is supplied, then any error mesasges will be
        returned to the user in this parameter rather than depending on
        on the MESSAGE routine in IDL.   If no errors are encountered
        then a null string is returned.               
PROCEDURE
The parameters BSCALE, NAXIS1, NAXIS2, CRPIX1, and CRPIX2 and
the CD (or CDELT) parameters are updated for the new FITS header.
EXAMPLE
Compress the image in a FITS file 'image.fits' by a factor of 4 and 
update the astrometry in the FITS header
IDL> im = readfits('image.fits',hdr)    ;Read FITS file into IDL arrays
IDL> hboxave, im, hdr, 4                ;Boxaverage by 4
IDL> writefits,'image.fits',im,hdr      ;Write a new FITS file
CALLED PROCEDURES
CHECK_FITS - Check that the FITS header is appropriate to the image
BOXAVE() - Performs box averaging of an image
SXPAR(), SXADDPAR - Read and write FITS keyword values
MODIFICATION HISTORY
Written, Aug. 1986 W. Landsman, STI Corp.
IDLV2 changes, sxaddpar format keyword added, J. Isensee, July,1990
Fix 0.5 pixel offset in new CRPIX computation W. Landsman, Dec, 1991
Update BSCALE even if no astrometry present   W. Landsman, May 1997
Added ERRMSG keyword, Use double formatting   W. Landsman   April 2000
Recognize PC matrix astrometry format    W. Landsman   December 2001
Use V6.0 notation  W. Landsman  October 2012
eturn to caller on error
heck # of parameters
oes user want to return error messages?
Check for valid 2-D image & header
rompt for box size
heck for integer type
Update astrometry info if it exists
atio of old to new pixel areas
Dn_m Matrix