idlastro / Disk I/O (e.g. IRAF files): WFPC2_READ

[Source code]

NAME
WFPC2_READ
PURPOSE
Read WFPC2 images in either FITS or STSDAS format into IDL variables.
EXPLANATION
This a versatile procedure for reading Wide Field Planetary Camera 2 
(WFPC2) images.   One can read either multi-extension FITS or  STSDAS or
STSDAS converted to FITS format, and specific 
chip or chips.    One can also read all four chips into a "batwing" mosaic--
so-called because the PC chip (chip 1) has a plate scale of 0.045", while
the other three WF chips have a plate scale of 0.1"
CALLING SEQUENCE
WFPC2_READ,filename,chip1,hdr1,chip2,hdr2,chip3,hdr3,chip4,hdr4
               or
WFPC2_READ,filename,chip,hdr, NUM_CHIP = [1,2,3,4], [/TRIM, PATH = ]
               or
WFPC2_READ,filename,image,hdr,/BATWING
INPUTS
filename - Name of FITS or STSDAS file with a stack of images from
        the four WF/PC-2 chips, followed by a FITS ASCII
        table with header parameters for each chip.    If the file
        name extension ends in 'h' then it is assumed to be an
        STSDAS file.   If no extension is supplied, and the file is
        is not found, then WFPC2_READ first tries appending a '.fits'
        extension, and then tries appending a '.c0h' extension.  
        The file may als be gzip compressed (with a .gz extension) 
INPUT KEYWORD PARAMETERS
NUM_CHIP - Integer scalar or vector, subset of 1, 2, 3, 4, specifying 
           particular chip numbers to read.    Outputs will be in same 
           order as specification of subset.   (See Example 2.)
/TRIM   - If set, trim off areas with no image and re-orient so that
          all  the chips have a common orientation suitable for insertion 
           into "bat-wing" mosaic (no image distortion removal, however).
PATH   -   scalar string specifying a !PATH-like list of directories
           in which to search for the file.   Default is to look only
           in the current directory.
/BATWING -  Return a 1600 x 1600 array containing all four chips in a
           "bat wing" mosaic formation.     This image is mainly for 
           display  purposes, since the PC chip is compressed to match the plate 
           scale of the WF chips.    In addition, a small astrometry error
           is introduced since chips do not have the same rotation, nor    
           are they aligned at the integer pixel level.
OUTPUTS
chipN    - 800 X 800 image from chip N.   If /TRIM is set then the output
           size is somewhat smaller (e.g. 756 x 757)
headerN  - Individual FITS header for chip N with correct astrometry.
PROCEDURES USED
For FITS I/O: FITS_CLOSE, FITS_OPEN, FITS_READ
For STSDAS I/O: EXTGRP, FTGET(), SXOPEN, SXREAD()
Other procedures:  CHECK_FITS, FDECOMP, FIND_WITH_DEF(), FREBIN, HEXTRACT, 
      HROTATE, SXADDHIST, SXADDPAR, SXPAR()
EXAMPLE
(1) Read all four chips of the FITS file u2ou0201t_c0f.fits
IDL> wfpc2_read,'u2ou0201t_c0f',c1,h1,c2,h2,c3,h3,c4,h4
 (2) Note that supplying the .fits extension is optional.   Now read only
 chips 1 (the PC chip) and 3.   Trim off portions of the arrays where
 there is no image.   
IDL> wfpc2_read,'u2ou0201t_c0f',c1,h1,c3,h3,num=[1,3],/trim
  (3) Note that with the /TRIM option the output chip sizes are no longer
      800 x 800 but odd sizes such as 770 by 753.    Now read all 4 chips
      into a 1600 x 1600 "batwing" mosaic
IDL> wfpc2_read,'u2ou0201t_c0f',im,h,/batwing
MODIFICATION HISTORY
Written by W. Landsman, Raytheon STX, for IDL V5.0     June 1998
Based on code by Robert Hill, Raytheon STX
Better astrometry of PC image in "batwing" configuration, W. Landsman
           August 1999
Use vector call to SXADDHIST  W. Landsman   March 2003
Don't use EXECUTE() for V6.1 or later W. Landsman Dec 2006
Assume since V6.1  W. Landsman  June 2009
Ability to read multi-extension format FITS  W. Landsman May 2010
Correct header in MEF form when only reading PC chip.  W.L. July 2010