- 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. By default, the counts/pixel is preserved,
though one can preserve the total counts or surface flux by setting /TOTAL
- 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
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.
OUTSIZE - Two element integer vector which can be used instead of the
NEWX and NEWY parameters to specify the output image dimensions
/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.
/TOTAL - If set then the output image will have the same total number of counts
as the input image. Because HREBIN also updates the astrometry,
use of the TOTAL keyword also preserves counts per surface area, e.g.
counts/(arc sec)@
- 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
Always call FREBIN, added TOTAL keyword W. Landsman Nov 2015
- heck # of parameters
- oes user want to return error messages?
- If only 1 parameter is supplied, then assume it is a FITS header
Modified Nov 2015 to always call FREBIN. FREBIN() will call the IDL REBIN()
function if we are changing dimensions by an exact multiple.
- 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.