Name

---

      HEXTRACT

Purpose

---

      Extract a subimage from an array and update astrometry in FITS header

Explanation

---

      Extract a subimage from an array and create a new FITS header with
      updated astrometry for the subarray

Calling Sequence

---

      HEXTRACT, Oldim, Oldhd, [ Newim, Newhd, x0, x1, y0, y1, /SILENT ]
              or
      HEXTRACT, Oldim, Oldhd, [x0, x1, y0, y1, /SILENT, ERRMSG = ]

Inputs

---

      Oldim - the original image array
      Oldhd - the original image header

Optional Inputs

---

      x0, x1, y0, y1 - respectively, first and last X pixel, and first and
      last Y pixel to be extracted from the original image, integer scalars.
      HEXTRACT will convert these values to long integers.
      If omitted, HEXTRACT will prompt for these parameters

Optional Outputs

---

      Newim - the new subarray extracted from the original image
      Newhd - header for newim containing updated astrometry info
              If output parameters are not supplied or set equal to
              -1, then the HEXTRACT will modify the input parameters
              OLDIM and OLDHD to contain the subarray and updated header.

Optional Input Keyword

---

      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 or ALT = ' '. See Greisen and Calabretta (2002)
          for information about alternate astrometry keywords.
      /SILENT - If set and non-zero, then a message describing the extraction
              is not printed at the terminal. This message can also be
              suppressed by setting !QUIET.

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 FITS header parameters NAXIS1, NAXIS2, CRPIX1, and CRPIX2 are
      updated for the extracted image.

Example

---

      Read an image from a FITS file 'IMAGE', extract a 512 x 512 subimage
      with the same origin, and write to a new FITS file 'IMAGENEW'
      IDL> im = READFITS( 'IMAGE', hdr ) ;Read FITS files into IDL arrays
      IDL> hextract, im, h, 0, 511, 0, 511 ;Extract 512 x 512 subimage
      IDL> writefits, 'IMAGENEW', im ,h ;Write subimage to a FITS file

Procedures Called

---

      CHECK_FITS, STRN(), SXPAR(), SXADDPAR, SXADDHIST

Modification History

---

      Written, Aug. 1986 W. Landsman, STX Corp.
      Use astrometry structure, W. Landsman Jan, 1994
      Minor fix if bad Y range supplied W. Landsman Feb, 1996
      Added /SILENT keyword W. Landsman March, 1997
      Added ERRMSG keyword W. Landsman May 2000
      Work for dimensions larger than 32767 W.L., M.Symeonidis Mar 2007
      Added ALT keyword W.L. April 2007