idlastro / FITS Astrometry and Calibration: HREBIN

[Source code]

NAME
HREBIN
PURPOSE
Expand or contract a FITS image using (F)REBIN and update the header 
EXPLANATION
If the output size is an exact multiple of the input size then REBIN is 
used, else FREBIN is used.   User can either overwrite the input array,
or write to new variables.
CALLING SEQUENCE
HREBIN, oldhd        ;Special calling sequence to just update header
HREBIN, oldim, oldhd, [ newim, newhd, newx, newy, OUTSIZE = ,/SAMPLE, 
                        ERRMSG =  ]
INPUTS
OLDIM - the original image array
OLDHD - the original image FITS header, string array
OPTIONAL INPUTS
NEWX - size of the new image in the X direction, integer scalar
NEWY - size of the new image in the Y direction, integer scalar
        HREBIN will prompt for NEWX and NEWY if not supplied
OPTIONAL OUTPUTS
NEWIM - the image after expansion or contraction with REBIN
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 INPUT KEYWORDS
/SAMPLE - Expansion or contraction is done using REBIN which uses 
          bilinear interpolation when magnifying and boxaveraging when 
          minifying.   If the SAMPLE keyword is supplied and non-zero, 
          then nearest neighbor sampling is used in both cases.   Keyword
          has no effect when output size is not a multiple of input size.
OUTSIZE - Two element integer vector which can be used instead of the
         NEWX and NEWY parameters to specify the output image dimensions
ALT - Single character 'A' through 'Z' or ' ' specifying which astrometry
      system to modify in the FITS header.    The default is to use the
      primary astrometry of ALT = ' '.    See Greisen and Calabretta (2002)
      for information about alternate astrometry keywords.
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 a 2048 x 2048 image array IM, with FITS header HDR, to a 
724 x 724 array.   Overwrite the input variables with the compressed 
image and header.
IDL> hrebin, im, hdr, OUT = [724, 724]
PROCEDURES USED
CHECK_FITS, EXTAST, FREBIN, GSSS_STDAST, STRN(), SXPAR(), SXADDHIST, 
SXADDPAR, ZPARCHECK
MODIFICATION HISTORY
Written, December 1990  W. Landsman, ST System Corp.
Update CD1_1 keywords   W. Landsman   November 1992
Check for a GSSS header   W. Landsman  June 1994
Update BSCALE even if no astrometry present   W. Landsman  May 1997
Converted to IDL V5.0   W. Landsman   September 1997
Use FREBIN to accept sizes that are not a integer multiple of the original
    size    W. Landsman     August 1998
Correct for "edge" effects when expanding with REBIN W. Landsman Apr. 1999
Fixed initialization of header only call broken in Apr 98 change May. 1999
Remove reference to obsolete !ERR  W. Landsman   February 2000
Use double precision formatting for CD matrix W. Landsman April 2000
Recognize PC00n00m astrometry format   W. Landsman   December 2001
Correct astrometry for integral contraction W. Landsman  April 2002
Fix output astrometry for non-equal plate scales for PC matrix or
CROTA2 keyword, added ALT keyword.   W. Landsman May 2005
Update distortion parameters if present  W. Landsman August 2007
Don't update BSCALE/BZERO for unsigned integer W.Landsman Mar 2008
Use post-V6.0 notation   W. Landsman  Nov 2011
Write CRPIX values as double precision if necessary W. Landsman Oct. 2012
heck # of parameters
oes user want to return error messages?
If only 1 parameter is supplied, then assume it is a FITS header
If an image array supplied then apply the REBIN  or FREBIN functions
If output size is a multiple of input size then use REBIN else use FREBIN
xpansion or contraction in X
xpansion or contraction in Y
easures change in aspect ratio.
atio of pixel areas
Update astrometry info if it exists
Correct the position of the reference pixel. Note that CRPIX values are
given in FORTRAN (first pixel is (1,1)) convention
When expanding with REBIN with bilinear interpolation (SAMPLE = 0), edge
effects are introduced, which require a different calculation of the updated
CRPIX1 and CRPIX2 values.
Scale either the CDELT parameters or the CD1_1 parameters.
Adjust the PC matrix if aspect ratio has changed. See equation 187 in
Calabretta & Greisen (2002)
an no longer use the simple CROTA2 convention, change to PC keywords
Dn_m Matrix format
Adjust BZERO and BSCALE for new pixel size, unless these values are used
to define unsigned integer data types.