Extended IDL Help

  • Return to IDL Topics

    Last modified: Tue Aug 7 08:53:42 2007.


    List of Routines


    Routine Descriptions

    CHECK_FITS

    [Next Routine] [List of Routines]
     NAME:
           CHECK_FITS
     PURPOSE:
           Check that keywords in a FITS header array match the associated data  
     EXPLANATION:
           Given a FITS array IM, and a associated FITS or STSDAS header HDR, this
           procedure will check that
                   (1) HDR is a string array, and IM is defined and numeric   
                   (2) The NAXISi values in HDR are appropriate to the dimensions 
                       of IM
                   (3) The BITPIX value in HDR is appropriate to the datatype of IM
           If HDR contains a DATATYPE keyword (as in STSDAS headers), then this is 
           also checked against the datatype of of IM
           If the /UPDATE keyword is present, then the FITS header will be 
           modified, if necessary, to force agreement with the image array
    
     CALLING SEQUENCE:
           check_FITS, im, hdr, [ dimen, idltype, /UPDATE, /NOTYPE, /SDAS, /SILENT
                                  ERRMSG = ]'
    
     INPUT PARAMETERS:
           IM -  FITS (or STSDAS) array, e.g. as read by READFITS
           HDR - FITS (or STSDAS) header (string array) associated with IM
    
     OPTIONAL OUTPUTS:
           dimen - vector containing actual array dimensions
           idltype- data type of the FITS array as specified in the IDL SIZE
                   function (1 for BYTE, 2 for INTEGER*2, 3 for INTEGER*4, etc.)
    
     OPTIONAL KEYWORD INPUTS:
           /NOTYPE - If this keyword is set, then only agreement of the array
                   dimensions with the FITS header are checked, and not the 
                   data type.
           /UPDATE - If this keyword is set then the BITPIX, NAXIS and DATATYPE
                   FITS keywords will be updated to agree with the array
           /SDAS - If this keyword is set then the header is assumed to be from
                   an SDAS (.hhh) file.    CHECK_FITS will then ensure that (1)
                   a DATATYPE keyword is included in the header and (2) BITPIX
                   is always written with positive values.
           /FITS -  If this keyword is present then CHECK_FITS assumes that it is
                   dealing with a FITS header and not an SDAS header, see notes
                   below.
           /SILENT - If keyword is set and nonzero, the informational messages 
                   will not be printed
     OPTIONAL KEYWORD OUTPUT:
           ERRMSG	= If this keyword is present, then any error messages will be
                     returned to the user in this parameter rather than
                     depending on the MESSAGE routine in IDL.  If no errors are
                     encountered, then a null string is returned.  
    
     SYSTEM VARIABLE:
           For consistency with previous versions, CHECK_FITS sets the obsolete
           !ERR keyword, although its use is discouraged in favor of the ERRMSG
           keyword.   If there is a fatal problem with the FITS array or header 
           then !ERR is set to -1.   ( If the UPDATE keyword was supplied, and the
           header could be fixed, then !ERR = 0.)    
    
     PROCEDURE:
           Program checks the NAXIS1 and NAXIS2 parameters in the header to
           see if they match the image array dimensions.
    
     NOTES:
           An important distinction between an STSDAS header and a FITS header
           is that the BITPIX value in an STSDAS header is always positive, 
           e.g. BITPIX=32 for REAL*4 data.    Users should use either the /SDAS 
           or the /FITS keyword if it is important whether the STSDAS or FITS 
           convention for REAL*4 data is used.     Otherwise, CHECK_FITS assumes 
           that if a DATATYPE keyword is present then it is dealing with an 
           STSDAS header.
    
     PROCEDURE CALLS:
           STRN(),FXADDPAR, fxpar() 
     MODIFICATION HISTORY:
           Written, December 1991  W. Landsman Hughes/STX to replace CHKIMHD
           No error returned if NAXIS=0 and IM is a scalar   W. Landsman  Feb 93
           Fixed bug for REAL*8 STSDAS data W. Landsman July 93
           Make sure NAXIS agrees with NAXISi  W. Landsman  October 93
            Converted to IDL V5.0   W. Landsman   September 1997
           Allow unsigned data types   W. Landsman December 1999
           Allow BZERO = 0 for unsigned data types   W. Landsman January 2000
           Added ERRMSG keyword, W. Landsman February 2000
           Use FXADDPAR to put NAXISi in proper order   W. Landsman August 2000
           Improper FXADDPAR call for DATATYPE keyword  W. Landsman December 2000
    

    (See ../pfidl/astro_lib/check_fits.pro)


    CONVOLVE

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	CONVOLVE
     PURPOSE:
    	Convolution of an image with a Point Spread Function (PSF)
     EXPLANATION:
    	The default is to compute the convolution using a product of 
    	Fourier transforms (for speed).
    
     CALLING SEQUENCE:
    
    	imconv = convolve( image1, psf, FT_PSF = psf_FT )
      or:
    	correl = convolve( image1, image2, /CORREL )
      or:
    	correl = convolve( image, /AUTO )
    
     INPUTS:
    	image = 2-D array (matrix) to be convolved with psf
    	psf = the Point Spread Function, (size < or = to size of image).
    
     OPTIONAL INPUT KEYWORDS:
    
    	FT_PSF = passes out/in the Fourier transform of the PSF,
    		(so that it can be re-used the next time function is called).
    	FT_IMAGE = passes out/in the Fourier transform of image.
    
    	/CORRELATE uses the conjugate of the Fourier transform of PSF,
    		to compute the cross-correlation of image and PSF,
    		(equivalent to IDL function convol() with NO rotation of PSF)
    
    	/AUTO_CORR computes the auto-correlation function of image using FFT.
    
    	/NO_FT overrides the use of FFT, using IDL function convol() instead.
    		(then PSF is rotated by 180 degrees to give same result)
     METHOD:
    	When using FFT, PSF is centered & expanded to size of image.
     HISTORY:
    	written, Frank Varosi, NASA/GSFC 1992.
    	Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/convolve.pro)


    CORREL_OPTIMIZE

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	CORREL_OPTIMIZE
    
     PURPOSE:
    	Find the optimal (x,y) pixel offset of image_B relative to image_A
     EXPLANATION"
    	Optimal offset is computed by means of maximizing the correlation 
    	function of the two images.
    
     CALLING SEQUENCE:
    	CORREL_OPTIMIZE, image_A, image_B, xoffset_optimum, yoffset_optimum 
    		[ XOFF_INIT=, YOFF_INIT=, MAGNIFICATION=, /PRINT, /NUMPIX, 
    		  /MONITOR, PLATEAU_THRESH=  ]
    
     INPUTS:
    	image_A, image_B = the two images of interest.
    
     OPTIONAL INPUT KEYWORDS:
    	XOFF_INIT = initial X pixel offset of image_B relative to image_A,
    	YOFF_INIT = Y pixel offset, (default offsets are 0 and 0).
    	MAGNIFICATION = option to determine offsets up to fractional pixels,
    			(example: MAG=2 means 1/2 pixel accuracy, default=1).
    	/NUMPIX: sqrt( sqrt( # pixels )) used as correlation weighting factor.
    	/MONITOR causes the progress of computation to be briefly printed.
    	/PRINT causes the results of analysis to be printed.
    	PLATEAU_THRESH = threshold used for detecting plateaus in 
    		the cross-correlation matrix near maximum, (default=0.01),
    		used only if MAGNIFICATION > 1.    Decrease this value for
    		high signal-to-noise data
    
     OUTPUTS:
    	xoffset_optimum = optimal X pixel offset of image_B relative to image_A.
    	yoffset_optimum = optimal Y pixel offset.
    
     CALLS:
    	function  correl_images( image_A, image_B )
    	pro  corrmat_analyze
    
     PROCEDURE:
    	The combination of function correl_images( image_A, image_B ) and
    	corrmat_analyze of the result is used to obtain the (x,y) offset
    	yielding maximal correlation. The combination is first executed at
    	large REDUCTION factors to speed up computation, then zooming in 
    	recursively on the optimal (x,y) offset by factors of 2.
    	Finally, the MAGNIFICATION option (if specified)
    	is executed to determine the (x,y) offset up to fractional pixels.
    	
     MODIFICATION HISTORY:
    	Written, July,1991, Frank Varosi, STX @ NASA/GSFC
    	Added PLATEAU_THRESH keyword  June 1997,  Wayne Landsman  STX   
    	Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/correl_optimize.pro)


    DAYCNV

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           DAYCNV
     PURPOSE:
           Converts Julian dates to Gregorian calendar dates
    
     CALLING SEQUENCE:
           DAYCNV, XJD, YR, MN, DAY, HR
    
     INPUTS:
           XJD = Julian date, positive double precision scalar or vector
    
     OUTPUTS:
           YR = Year (Integer)
           MN = Month (Integer)
           DAY = Day (Integer)
           HR = Hours and fractional hours (Real).   If XJD is a vector,
                   then YR,MN,DAY and HR will be vectors of the same length.
    
     EXAMPLE:
           IDL> DAYCNV, 2440000.D, yr, mn, day, hr    
    
           yields yr = 1968, mn =5, day = 23, hr =12.   
    
     WARNING:
           Be sure that the Julian date is specified as double precision to
           maintain accuracy at the fractional hour level.
    
     METHOD:
           Uses the algorithm of Fliegel and Van Falndern (1968) as reported in
           the "Explanatory Supplement to the Astronomical Almanac" (1992), p. 604
           Works for all Gregorian calendar dates with XJD > 0, i.e., dates after
           -4713 November 23.
     REVISION HISTORY:
           Converted to IDL from Yeoman's Comet Ephemeris Generator, 
           B. Pfarr, STX, 6/16/88
           Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/daycnv.pro)


    FITS_ADD_CHECKSUM

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
        FITS_ADD_CHECKSUM
     PURPOSE:
        Add or update the CHECKSUM and DATASUM keywords in a FITS header
     EXPLANATION: 
         Follows the 23 May 2002 version of the FITS checksum proposal at 
         http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html  
     CALLING SEQUENCE:
         FITS_ADD_CHECKSUM, Hdr, [ Data, /No_TIMESTAMP, /FROM_IEEE ]
     INPUT-OUTPUT:
         Hdr - FITS header (string array), it will be updated with new 
               (or modfied) CHECKSUM and DATASUM keywords 
     OPTIONAL INPUT:
         Data - data array associated with the FITS header.   If not supplied, or
               set to a scalar, then the program checks whether there is a 
               DATASUM keyword already in the FITS header containing the 32bit
               checksum for the data.   if there is no such keyword then ther 
               assumed to be no data array 
               associated with the FITS header.
     OPTIONAL INPUT KEYWORDS:
        /FROM_IEEE - If this keyword is set, then the input is assumed to be in 
                 big endian format (e.g. an untranslated FITS array).    This 
                 keyword only has an effect on little endian machines (e.g. 
                 a Linux box).
        /No_TIMESTAMP - If set, then a time stamp is not included in the comment
                 field of the CHECKSUM and DATASUM keywords.   Unless the 
                 /No_TIMESTAMP keyword is set, repeated calls to FITS_ADD_CHECKSUM
                 with the same header and data will yield different values of 
                 CHECKSUM (as the date stamp always changes).   However, use of the
                 date stamp is recommended in the checksum proposal. 
     PROCEDURES USED:
         CHECKSUM32, FITS_ASCII_ENCODE(), GET_DATE, SXADDPAR, SXPAR()
     REVISION HISTORY:
         W. Landsman    SSAI    December 2002
    

    (See ../pfidl/astro_lib/fits_add_checksum.pro)


    FITS_CLOSE

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
          FITS_CLOSE
    
    *PURPOSE:
           Close a FITS data file
    
    *CATEGORY:
           INPUT/OUTPUT
    
    *CALLING SEQUENCE:
           FITS_CLOSE,fcb
    
    *INPUTS:
           FCB: FITS control block returned by FITS_OPEN.
    
    *KEYWORD PARAMETERS:
           /NO_ABORT: Set to return to calling program instead of a RETALL
                   when an I/O error is encountered.  If set, the routine will
                   return  a non-null string (containing the error message) in the
                   keyword MESSAGE.    (For backward compatibility, the obsolete 
                   system variable !ERR is also set to -1 in case of an error.)   
                   If /NO_ABORT not set, then FITS_CLOSE will print the message and
                   issue a RETALL
           MESSAGE = value: Output error message
           
    *EXAMPLES:
           Open a FITS file, read some data, and close it with FITS_CLOSE
    
                   FITS_OPEN,'infile',fcb
                   FITS_READ,fcb,data
                   FITS_READ,fcb,moredata
                   FITS_CLOSE,fcb
    
    *HISTORY:
           Written by:     D. Lindler      August, 1995
           Converted to IDL V5.0   W. Landsman   September 1997
           Do nothing if fcb an invalid structure D. Schlegel/W. Landsman Oct. 2000
           Return Message='' for to signal normal operation W. Landsman Nov. 2000
    

    (See ../pfidl/astro_lib/fits_close.pro)


    FITS_HELP

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	FITS_HELP
    
    *PURPOSE:
    	To print a summary of the primary data units and extensions in a
    	FITS file.
    
    *CATEGORY:
    	INPUT/OUTPUT
    
    *CALLING SEQUENCE:
    	FITS_HELP,filename_or_fcb
    
    *INPUTS:
    	FILENAME_OR_FCB - name of the fits file or the FITS Control Block (FCB)
    		returned by FITS_OPEN.     For versions since V5.3, the 
                   file name is allowed to be gzip compressed (with a .gz 
                   extension)
    
    *OUTPUTS:
    	a summary of the fits file is printed.	
    
    *EXAMPLES:
    	FITS_HELP,'myfile.fits'
    
    	FITS_OPEN,'anotherfile.fits',fcb
    	FITS_HELP,fcb
    
    *PROCEDURES USED:
    	FITS_OPEN, FITS_CLOSE
    *HISTORY:
    	Written by:	D. Lindler	August, 1995
    	Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/fits_help.pro)


    FITS_INFO

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
         FITS_INFO
     PURPOSE:
         Provide information about the contents of a FITS file
     EXPLANATION:
         Information includes number of header records and size of data array.
         Applies to primary header and all extensions.    Information can be 
         printed at the terminal and/or stored in a common block
    
     CALLING SEQUENCE:
         FITS_INFO, Filename, [ /SILENT , TEXTOUT = , N_ext = ]
    
     INPUT:
         Filename - Scalar string giving the name of the FITS file(s)
                   Can include wildcards such as '*.fits'.   In IDL V5.5 one can
                   use the regular expressions allowed by the FILE_SEARCH()
                   function.     Since V5.3 one can also search gzip compressed 
                   FITS files.
     OPTIONAL INPUT KEYWORDS:
         /SILENT - If set, then the display of the file description on the 
                    terminal will be suppressed
    
          TEXTOUT - specifies output device.
                   textout=1        TERMINAL using /more option
                   textout=2        TERMINAL without /more option
                   textout=3        .prt
                   textout=4        laser.tmp
                   textout=5        user must open file, see TEXTOPEN
                   textout=7       append to existing  file
                   textout = filename (default extension of .prt)
    
                   If TEXTOUT is not supplied, then !TEXTOUT is used
     OPTIONAL OUTPUT KEYWORD:
           N_ext - Returns an integer scalar giving the number of extensions in
                   the FITS file
    
     COMMON BLOCKS
           DESCRIPTOR =  File descriptor string of the form N_hdrrec Naxis IDL_type
                   Naxis1 Naxis2 ... Naxisn [N_hdrrec table_type Naxis
                   IDL_type Naxis1 ... Naxisn] (repeated for each extension) 
                   See the procedure RDFITS_STRUCT for an example of the
                   use of this common block
    
     EXAMPLE:
           Display info about all FITS files of the form '*.fit' in the current
                   directory
    
                   IDL> fits_info, '*.fit'
    
           Any time a *.fit file is found which is *not* in FITS format, an error 
           message is displayed at the terminal and the program continues
    
     PROCEDURES USED:
           GETTOK(), MRD_SKIP, STRN(), SXPAR(), TEXTOPEN, TEXTCLOSE 
    
     SYSTEM VARIABLES:
           The non-standard system variables !TEXTOUT and !TEXTUNIT will be  
           created by FITS_INFO if they are not previously defined.   
    
           DEFSYSV,'!TEXTOUT',1
           DEFSYSV,'!TEXTUNIT',0
    
           See TEXTOPEN.PRO for more info
     MODIFICATION HISTORY:
           Written, K. Venkatakrishna, Hughes STX, May 1992
           Added N_ext keyword, and table_name info, G. Reichert
           Work on *very* large FITS files   October 92
           More checks to recognize corrupted FITS files     February, 1993
           Proper check for END keyword    December 1994
           Correctly size variable length binary tables  WBL December 1994
           EXTNAME keyword can be anywhere in extension header WBL  January 1998
           Correctly skip past extensions with no data   WBL   April 1998
           Converted to IDL V5.0, W. Landsman, April 1998
           No need for !TEXTOUT if /SILENT D.Finkbeiner   February 2002
    	Define !TEXTOUT if needed.  R. Sterner, 2002 Aug 27
           Work on gzip compressed files for V5.3 or later  W. Landsman 2003 Jan
           Improve speed by only reading first 36 lines of header 
           Count headers with more than 32767 lines         W. Landsman Feb. 2003
    

    (See ../pfidl/astro_lib/fits_info.pro)


    FITS_OPEN

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           FITS_OPEN
    
    *PURPOSE:
           Opens a FITS (Flexible Image Transport System) data file.
    
    *CATEGORY:
           INPUT/OUTPUT
    
    *CALLING SEQUENCE:
           FITS_OPEN, filename, fcb
    
    *INPUTS:
           filename : name of the FITS file to open, scalar string
                      FITS_OPEN can also open gzip compressed (.gz) file *for 
                      reading only*, in IDL V5.3 or later, although there is a 
                      performance penalty 
    *OUTPUTS:
           fcb : (FITS Control Block) a IDL structure containing information
                   concerning the file.  It is an input to FITS_READ, FITS_WRITE
                   and FITS_CLOSE
    
     INPUT KEYWORD PARAMETERS:
           /APPEND: Set to append to an existing file.
           /HPRINT - print headers with routine HPRINT as they are read.
                   (useful for debugging a strange file)
           /NO_ABORT: Set to return to calling program instead of a RETALL
                   when an I/O error is encountered.  If set, the routine will
                   return  a non-null string (containing the error message) in the
                   keyword MESSAGE.    (For backward compatibility, the obsolete 
                   system variable !ERR is also set to -1 in case of an error.)   
                   If /NO_ABORT not set, then FITS_OPEN will print the message and
                   issue a RETALL
           /UPDATE Set this keyword to open an existing file for update
           /WRITE: Set this keyword to open a new file for writing. 
    
     OUTPUT KEYWORD PARAMETERS:
           MESSAGE = value: Output error message.    If the FITS file was opened
                   successfully, then message = ''.
           
    *NOTES:
           The output FCB should be passed to the other FITS routines (FITS_OPEN,
           FITS_READ, FITS_HELP, and FITS_WRITE).  It has the following structure
           when FITS_OPEN is called without /WRITE or /APPEND keywords set.
    
               FCB.FILENAME - name of the input file
                   .UNIT - unit number the file is opened to
                   .NEXTEND - number of extensions in the file.
                   .XTENSION - string array giving the extension type for each
                           extension.
                   .EXTNAME - string array giving the extension name for each
                           extension. (null string if not defined the extension)
                   .EXTVER - vector of extension version numbers (0 if not
                           defined)
                   .EXTLEVEL - vector of extension levels (0 if not defined)
                   .GCOUNT - vector with the number of groups in each extension.
                   .PCOUNT - vector with parameter count for each group
                   .BITPIX - BITPIX for each extension with values
                                      8    byte data
                                    16     short word integers
                                    32     long word integers
                                   -32     IEEE floating point
                                   -64     IEEE double precision floating point
                   .NAXIS - number of axes for each extension.  (0 for null data
                           units)
                   .AXIS - 2-D array where axis(*,N) gives the size of each axes
                           for extension N
                   .START_HEADER - vector giving the starting byte in the file
                                   where each extension header begins
                   .START_DATA - vector giving the starting byte in the file
                                   where the data for each extension begins
    
                   .HMAIN - keyword parameters (less standard required FITS
                                   keywords) for the primary data unit.
                   .OPEN_FOR_WRITE - flag (0= open for read, 1=open for write, 
                                                    2=open for update)
                   .LAST_EXTENSION - last extension number read.
                   .RANDOM_GROUPS - 1 if the PDU is random groups format,
                                   0 otherwise
                   .NBYTES - total number of (uncompressed) bytes in the FITS file
    
           When FITS open is called with the /WRITE or /APPEND option, FCB
           contains:
    
               FCB.FILENAME - name of the input file
                   .UNIT - unit number the file is opened to
                   .NEXTEND - number of extensions in the file.
                   .OPEN_FOR_WRITE - flag (1=open for write, 2=open for append
                                           3=open for update)
    
    
    *EXAMPLES:
           Open a FITS file for reading:
                   FITS_OPEN,'myfile.fits',fcb
    
           Open a new FITS file for output:
                   FITS_OPEN,'newfile.fits',fcb,/write
     PROCEDURES USED:
           HPRINT, SXDELPAR, SXPAR()
    *HISTORY:
           Written by:     D. Lindler      August, 1995
           July, 1996      NICMOS  Modified to allow open for overwrite
                                   to allow primary header to be modified
           DJL Oct. 15, 1996   corrected to properly extend AXIS when more
                           than 100 extensions present
           Converted to IDL V5.0   W. Landsman   September 1997
           Use Message = '' rather than !ERR =1 as preferred signal of normal
               operation   W. Landsman  November 2000
         	Lindler, Dec, 2001, Modified to use 64 bit words for storing byte
                 positions within the file to allow support for very large
                 files 
           Work with gzip compressed files W. Landsman    January 2003
    

    (See ../pfidl/astro_lib/fits_open.pro)


    FITS_READ

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           FITS_READ
    *PURPOSE:
           To read a FITS file.
    
    *CATEGORY:
           INPUT/OUTPUT
    
    *CALLING SEQUENCE:
           FITS_READ, filename_or_fcb, data [,header, group_par]
    
    *INPUTS:
           FILENAME_OR_FCB - this parameter can be the FITS Control Block (FCB)
                   returned by FITS_OPEN or the file name of the FITS file.  If
                   a file name is supplied, FITS_READ will open the file with
                   FITS_OPEN and close the file with FITS_CLOSE before exiting.
                   When multiple extensions are to be read from the file, it is
                   more efficient for the user to call FITS_OPEN and leave the
                   file open until all extensions are read.
    
    *OUTPUTS:
           DATA - data array.  If /NOSCALE is specified, BSCALE and BZERO
                   (if present in the header) will not be used to scale the data.
                   If Keywords FIRST and LAST are used to read a portion of the
                   data or the heap portion of an extension, no scaling is done
                   and data is returned as a 1-D vector. The user can use the IDL
                   function REFORM to convert the data to the correct dimensions
                   if desired.  If /DATA_ONLY is specified, no scaling is done.
           HEADER - FITS Header.  If an extension is read, and the /NO_PDU keyword
                   parameter is not supplied, the primary data unit header
                   and the extension header will be combined.  The header will have
                   the form:
    
                           
                           BEGIN MAIN HEADER --------------------------------
                           
                           BEGIN EXTENSION HEADER ---------------------------
                           1.  (Default=0, the first group)
           
    *OUTPUT KEYWORD PARAMETERS:
           ENUM - Output extension number that was read.  
           MESSAGE = value: Output error message
    
    *NOTES:
           Determination or which extension to read.
                   case 1: EXTEN_NO specified. EXTEN_NO will give the number of the
                           extension to read.  The primary data unit is refered
                           to as extension 0. If EXTEN_NO is specified, XTENSION,
                           EXTNAME, EXTVER, and EXTLEVEL parameters are ignored.
                   case 2: if EXTEN_NO is not specified, the first extension
                           with the specified XTENSION, EXTNAME, EXTVER, and
                           EXTLEVEL will be read.  If any of the 4 parameters
                           are not specified, they will not be used in the search.
                           Setting EXTLEVEL=0, EXTVER=0, EXTNAME='', or
                           XTENSION='' is the same as not supplying them.
                   case 3: if none of the keyword parameters, EXTEN_NO, XTENSION,
                           EXTNAME, EXTVER, or EXTLEVEL are supplied.  FITS_READ
                           will read the next extension in the file.  If the
                           primary data unit (PDU), extension 0, is null, the
                           first call to FITS_READ will read the first extension
                           of the file.
    
                   The only way to read a null PDU is to use EXTEN_NO = 0.
    
           If FIRST and LAST are specified, the data is returned without applying
           any scale factors (BSCALE and BZERO) and the data is returned in a
           1-D vector.  This will allow you to read any portion of a multiple
           dimension data set.  Once returned, the IDL function REFORM can be
           used to place the correct dimensions on the data.
    
           IMPLICIT IMAGES: FITS_READ will construct an implicit image
                   for cases where NAXIS=0 and the NPIX1, NPIX2, and PIXVALUE
                   keywords are present.  The output image will be:
                           image = replicate(PIXVALUE,NPIX1,NPIX2)
    
    *EXAMPLES:
           Read the primary data unit of a FITS file, if it is null read the
           first extension:
                   FITS_READ, 'myfile.fits', data, header
    
           Read the first two extensions of a FITS file and the extension with
           EXTNAME = 'FLUX' and EXTVER = 4
                   FITS_OPEN, 'myfile.fits', fcb
                   FITS_READ, fcb,data1, header2, exten_no = 1
                   FITS_READ, fcb,data1, header2, exten_no = 2
                   FITS_READ, fcb,data3, header3, extname='flux', extver=4
                   FITS_CLOSE, fcb
           
           Read the sixth image in a data cube for the fourth extension.
    
                   FITS_OPEN, 'myfile.fits', fcb
                   image_number = 6
                   ns = fcb.axis(0,4)
                   nl = fcb.axis(1,4)
                   i1 = (ns*nl)*(image_number-1)
                   i2 = i2 + ns*nl-1
                   FITS_READ,fcb,image,header,first=i1,last=i2
                   image = reform(image,ns,nl,/overwrite)
                   FITS_CLOSE
    
    *PROCEDURES USED:
           FITS_CLOSE, FITS_OPEN, IEEE_TO_HOST, IS_IEEE_BIG() 
           SXADDPAR, SXDELPAR, SXPAR()
    *HISTORY:
           Written by:     D. Lindler, August 1995
           Converted to IDL V5.0   W. Landsman   September 1997
           Avoid use of !ERR       W. Landsman   August 1999
           Read unsigned datatypes, added /no_unsigned   W. Landsman December 1999
           Don't call FITS_CLOSE unless fcb is defined   W. Landsman January 2000
           Set BZERO = 0 for unsigned integer data   W. Landsman  January 2000
           Only call IEEE_TO_HOST if needed          W. Landsman February 2000
           Ensure EXTEND keyword in primary header   W. Landsman April 2001
           Don't erase ERROR message when closing file  W. Landsman April 2002
           Assume at least V5.1 remove NANValue keyword  W. Landsman November 2002
           Work with compress files (read file size from fcb),
           requires updated (Jan 2003) version of FITS_OPEN W. Landsman Jan 2003
    

    (See ../pfidl/astro_lib/fits_read.pro)


    FITS_TEST_CHECKSUM()

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
        FITS_TEST_CHECKSUM()
     PURPOSE:
        Verify the values of the CHECKSUM and DATASUM keywords in a FITS header 
     EXPLANATION: 
         Follows the 23 May 2002 version of the FITS checksum proposal at 
         http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html   
     
     CALLING SEQUENCE:
        result = FITS_TEST_CHECKSUM(HDR, [ DATA, ERRMSG=, /FROM_IEEE ])
     INPUTS:
        HDR - FITS header (vector string)
     OPTIONAL DATA:
        DATA - data array associated with the FITS header.   If not supplied, or
               set to a scalar, then there is assumed to be no data array 
               associated with the FITS header.
     RESULT:
         An integer -1, 0 or 1 indicating the following conditions:
               1 - CHECKSUM (and DATASUM) keywords are present with correct values
               0 - CHECKSUM keyword is not present
              -1 - CHECKSUM or DATASUM keyword does not have the correct value
                   indicating possible data corruption.
     OPTIONAL INPUT KEYWORD:
        /FROM_IEEE - If this keyword is set, then the input is assumed to be in 
                 big endian format (e.g. an untranslated FITS array).    This 
                 keyword only has an effect on little endian machines (e.g. 
                 a Linux box).
     OPTIONAL OUTPUT KEYWORD:
         ERRMSG - will contain a scalar string giving the error condition.   If
                  RESULT = 1 then ERRMSG will be an empty string.   If this 
                  output keyword is not supplied, then the error message will be
                  printed at the terminal.
     NOTES:
         The header and data must be *exactly* as originally written in the FITS 
         file.  By default, some FITS readers may alter keyword values (e.g. 
         BSCALE) or append information (e.g. HISTORY or an inherited primary 
         header) and this will alter the checksum value.           
     PROCEDURES USED:
        CHECKSUM32, FITS_ASCII_ENCODE(), SXPAR()
     EXAMPLE:
         Verify the CHECKSUM keywords in the primary header/data unit of a FITS 
         file 'test.fits'
    
         FITS_READ,'test.fits',data,hdr,/no_PDU,/NoSCALE
         print,FITS_TEST_CHECKSUM(hdr,data)
    
         Note the use of the /No_PDU and /NoSCALE keywords to avoid any alteration 
         of the FITS header
     REVISION HISTORY:
         W. Landsman  SSAI               December 2002
    

    (See ../pfidl/astro_lib/fits_test_checksum.pro)


    FITS_WRITE

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	FITS_WRITE
    
    *PURPOSE:
    	To write a FITS primary data unit or extension.
    
    *CATEGORY:
    	INPUT/OUTPUT
    
    *CALLING SEQUENCE:
    	FITS_WRITE, filename_or_fcb, data, [header_in]
    
    *INPUTS:
    	FILENAME_OR_FCB: name of the output data file or the FITS control
    		block returned by FITS_OPEN (called with the /WRITE or
    		/APPEND) parameters.
    
    *OPTIONAL INPUTS:
    	DATA: data array to write.  If not supplied or set to a scalar, a
    		null image is written.
    	HEADER_IN: FITS header keyword.  If not supplied, a minimal basic
    		header will be created.  Required FITS keywords, SIMPLE,
    		BITPIX, XTENSION, NAXIS, ... are added by FITS_WRITE and
    		do not need to be supplied with the header.  If supplied,
    		their values will be updated as necessary to reflect DATA.
    
    *INPUT KEYWORD PARAMETERS:
    
    	XTENSION: type of extension to write (Default="IMAGE"). If not
    		supplied, it will be taken from HEADER_IN.  If not in either
    		place, the default is "IMAGE".  This parameter is ignored
    		when writing the primary data unit.
    	EXTNAME: EXTNAME for the extension.  If not supplied, it will be taken
    		from HEADER_IN.  If not supplied and not in HEADER_IN, no
    		EXTNAME will be written into the output extension.
    	EXTVER: EXTVER for the extension.  If not supplied, it will be taken
                   from HEADER_IN.  If not supplied and not in HEADER_IN, no
                   EXTVER will be written into the output extension.
    	EXTLEVEL: EXTLEVEL for the extension.  If not supplied, it will be taken
                   from HEADER_IN.  If not supplied and not in HEADER_IN, no
                   EXTLEVEL will be written into the output extension.
           /NO_ABORT: Set to return to calling program instead of a RETALL
                   when an I/O error is encountered.  If set, the routine will
                   return  a non-null string (containing the error message) in the
                   keyword MESSAGE.    (For backward compatibility, the obsolete 
                   system variable !ERR is also set to -1 in case of an error.)   
                   If /NO_ABORT not set, then FITS_WRITE will print the message and
                   issue a RETALL
    	/NO_DATA: Set if you only want FITS_WRITE to write a header.  The
    		header supplied will be written without modification and
    		the user is expected to write the data using WRITEU to unit
    		FCB.UNIT. When FITS_WRITE is called with /NO_DATA, the user is
    		responsible for the validity of the header, and must write
    		the correct amount and format of the data.  When FITS_WRITE
    		is used in this fashion, it will pad the data from a previously
    		written extension to 2880 blocks before writting the header.
    
    *OUTPUT KEYWORD PARAMETERS:
           MESSAGE: value of the error message for use with /NO_ABORT
    	HEADER: actual output header written to the FITS file.
    
    *NOTES:
    	If the first call to FITS_WRITE is an extension, FITS_WRITE will
    	automatically write a null image as the primary data unit.
    
    	Keywords and history in the input header will be properly separated
    	into the primary data unit and extension portions when constructing
    	the output header (See FITS_READ for information on the internal
    	Header format which separates the extension and PDU header portions).
    	
    *EXAMPLES:
    	Write an IDL variable to a FITS file with the minimal required header.
    		FITS_WRITE,'newfile.fits',ARRAY
    
    	Write the same array as an image extension, with a null Primary data
    	unit.
    		FITS_WRITE,'newfile.fits',ARRAY,xtension='IMAGE'
    
    	Write 4 additional image extensions to the same file.
    		FITS_OPEN,'newfile.fits',fcb
    		FITS_WRITE,fcb,data1,extname='FLUX',extver=1
    		FITS_WRITE,fcb,err1,extname'ERR',extver=1
    		FITS_WRITE,fcb,data2,extname='FLUX',extver=2
    		FITS_WRITE,fcb,err2,extname='ERR',extver=2
    		FITS_CLOSE,FCB
    		
    *PROCEDURES USED:
    	FITS_OPEN, SXADDPAR, SXDELPAR, SXPAR()
    *HISTORY:
    	Written by:	D. Lindler	August, 1995
    	Work for variable length extensions  W. Landsman   August 1997
    	Converted to IDL V5.0   W. Landsman   September 1997
    	PCOUNT and GCOUNT added for IMAGE extensions   J. Graham  October 1999
           Write unsigned data types      W. Landsman   December 1999
           Pad data area with zeros not blanks  W. McCann/W. Landsman October 2000
           Return Message='' to signal normal operation W. Landsman Nov. 2000
           Ensure that required extension table keywords are in proper order
                 W.V. Dixon/W. Landsman          March 2001
           Assume since V5.1, remove NaNValue keyword   W. Landsman Nov. 2002
    

    (See ../pfidl/astro_lib/fits_write.pro)


    FXADDPAR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME: 
           FXADDPAR
     Purpose     : 
           Add or modify a parameter in a FITS header array.
     Explanation : 
           This version of FXADDPAR will write string values longer than 68 
           characters using the FITS continuation convention described at 
           http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.html
     Use         : 
           FXADDPAR, HEADER, NAME, VALUE, COMMENT
     Inputs      : 
           HEADER  = String array containing FITS header.  The maximum string
                     length must be equal to 80.  If not defined, then FXADDPAR
                     will create an empty FITS header array.
    
           NAME    = Name of parameter.  If NAME is already in the header the
                     value and possibly comment fields are modified. Otherwise a
                     new record is added to the header.  If NAME is equal to
                     either "COMMENT" or "HISTORY" then the value will be added to
                     the record without replacement.  In this case the comment
                     parameter is ignored.
    
           VALUE   = Value for parameter.  The value expression must be of the
                     correct type, e.g. integer, floating or string.
                     String values of 'T' or 'F' are considered logical
                     values.  If the value is a string and is "long"
                     (more than 69 characters), then it may be continued
                     over more than one line using the OGIP CONTINUE
                     standard.
    
     Opt. Inputs : 
           COMMENT = String field.  The '/' is added by this routine.  Added
                     starting in position 31.  If not supplied, or set equal to ''
                     (the null string), then any previous comment field in the
                     header for that keyword is retained (when found).
     Outputs     : 
           HEADER  = Updated header array.
     Opt. Outputs: 
           None.
     Keywords    : 
           BEFORE  = Keyword string name.  The parameter will be placed before the
                     location of this keyword.  For example, if BEFORE='HISTORY'
                     then the parameter will be placed before the first history
                     location.  This applies only when adding a new keyword;
                     keywords already in the header are kept in the same position.
    
           AFTER   = Same as BEFORE, but the parameter will be placed after the
                     location of this keyword.  This keyword takes precedence over
                     BEFORE.
    
           FORMAT  = Specifies FORTRAN-like format for parameter, e.g. "F7.3".  A
                     scalar string should be used.  For complex numbers the format
                     should be defined so that it can be applied separately to the
                     real and imaginary parts.
    
           /NOCONTINUE = By default, FXADDPAR will break strings longer than 68 
                    characters into multiple lines using the continuation
                    convention.    If this keyword is set, then the line will
                    instead be truncated to 68 characters.    This was the default
                    behaviour of FXADDPAR prior to December 1999.  
     Calls       : 
           DETABIFY(), FXPAR(), FXPARPOS()
     Common      : 
           None.
     Restrictions: 
           Warning -- Parameters and names are not checked against valid FITS
           parameter names, values and types.
    
           The required FITS keywords SIMPLE (or XTENSION), BITPIX, NAXIS, NAXIS1,
           NAXIS2, etc., must be entered in order.  The actual values of these
           keywords are not checked for legality and consistency, however.
    
     Side effects: 
           All HISTORY records are inserted in order at the end of the header.
    
           All COMMENT records are also inserted in order at the end of the
           header, but before the HISTORY records.  The BEFORE and AFTER keywords
           can override this.
    
           All records with no keyword (blank) are inserted in order at the end of
           the header, but before the COMMENT and HISTORY records.  The BEFORE and
           AFTER keywords can override this.
    
           All other records are inserted before any of the HISTORY, COMMENT, or
           "blank" records.  The BEFORE and AFTER keywords can override this.
    
           String values longer than 68 characters will be split into multiple
           lines using the OGIP CONTINUE convention, unless the /NOCONTINUE keyword
           is set.    For a description of the CONTINUE convention see    
           http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.htm
     Category    : 
           Data Handling, I/O, FITS, Generic.
     Prev. Hist. : 
           William Thompson, Jan 1992, from SXADDPAR by D. Lindler and J. Isensee.
           Differences include:
    
                   * LOCATION parameter replaced with keywords BEFORE and AFTER.
                   * Support for COMMENT and "blank" FITS keywords.
                   * Better support for standard FITS formatting of string and
                     complex values.
                   * Built-in knowledge of the proper position of required
                     keywords in FITS (although not necessarily SDAS/Geis) primary
                     headers, and in TABLE and BINTABLE extension headers.
    
           William Thompson, May 1992, fixed bug when extending length of header,
           and new record is COMMENT, HISTORY, or blank.
     Written     : 
           William Thompson, GSFC, January 1992.
     Modified    : 
           Version 1, William Thompson, GSFC, 12 April 1993.
                   Incorporated into CDS library.
           Version 2, William Thompson, GSFC, 5 September 1997
                   Fixed bug replacing strings that contain "/" character--it
                   interpreted the following characters as a comment.
           Version 3, Craig Markwardt, GSFC,  December 1997
                   Allow long values to extend over multiple lines
    	Version 4, D. Lindler, March 2000, modified to use capital E instead
    		of a lower case e for exponential format.
           Version 4.1 W. Landsman April 2000, make user-supplied format uppercase
           Version 4.2 W. Landsman July 2002, positioning of EXTEND keyword
     Version     : 
           Version 4.2, July 2002
    

    (See ../pfidl/astro_lib/fxaddpar.pro)


    FXHREAD

    [Previous Routine] [Next Routine] [List of Routines]
     NAME: 
    	FXHREAD
     Purpose     : 
           Reads a FITS header from an opened disk file.
     Explanation : 
           Reads a FITS header from an opened disk file.
     Use         : 
    	FXHREAD, UNIT, HEADER  [, STATUS ]
     Inputs      : 
    	UNIT	= Logical unit number.
     Opt. Inputs : 
    
     Outputs     : 
    	HEADER	= String array containing the FITS header.
     Opt. Outputs: 
    	STATUS	= Condition code giving the status of the read.  Normally, this
    		  is zero, but is set to !ERR if an error occurs, or if the
    		  first byte of the header is zero (ASCII null).
     Keywords    : 
    	None.
     Calls       : 
    	None.
     Common      : 
    	None.
     Restrictions: 
    	The file must already be positioned at the start of the header.  It
    	must be a proper FITS file.
     Side effects: 
    	The file ends by being positioned at the end of the FITS header, unless
    	an error occurs.
     Category    : 
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. : 
    	W. Thompson, Feb 1992, from READFITS by J. Woffard and W. Landsman.
    	W. Thompson, Aug 1992, added test for SIMPLE keyword.
     Written     : 
    	William Thompson, GSFC, February 1992.
     Modified    : 
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
     Version     : 
    	Version 1, 12 April 1993.
    	Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/fxhread.pro)


    FXMOVE

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
         FXMOVE
     PURPOSE:
         Skip a specified number of extensions in a FITS file
    
     CALLING SEQUENCE:
         STATUS=FXMOVE(UNIT, N_EXT, /Silent)
    
     INPUT PARAMETERS:
         UNIT     = An open unit descriptor for a FITS data stream.
         N_EXT   = Number of extensions to skip.
    
     OPTIONAL INPUT PARAMETER:
         /SILENT - If set, then any messages about invalid characters in the 
                   FITS file are suppressed.
     RETURNS:
         0 if successful.
        -1 if an error is encountered.
    
     COMMON BLOCKS:
          None.
     SIDE EFFECTS:
          Repositions the file pointer.
     PROCEDURE:
          Each FITS header is read in and parsed, and the file pointer is moved
          to where the next FITS extension header until the desired
          extension is reached.
     PROCEDURE CALLS:
          FXPAR(), MRD_HREAD, MRD_SKIP
     MODIFICATION HISTORY:
          Extracted from FXPOSIT 8-March-2000 by T. McGlynn
          Added /SILENT keyword  14-Dec-2000 by W. Landsman
          Save time by not reading the full header  W. Landsman   Feb. 2003
    

    (See ../pfidl/astro_lib/fxmove.pro)


    FXPAR()

    [Previous Routine] [Next Routine] [List of Routines]
     NAME: 
            FXPAR()
     PURPOSE: 
           Obtain the value of a parameter in a FITS header.
     EXPLANATION: 
           The first 8 chacters of each element of HDR are searched for a match to
           NAME.  If the keyword is one of those allowed to take multiple values
           ("HISTORY", "COMMENT", or "        " (blank)), then the value is taken
           as the next 72 characters.  Otherwise, it is assumed that the next
           character is "=", and the value (and optional comment) is then parsed
           from the last 71 characters.  An error occurs if there is no parameter
           with the given name.
          
           If the value is too long for one line, it may be continued on to the
           the next input card, using the OGIP CONTINUE convention.  For more info,
           http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.html
    
           Complex numbers are recognized as two numbers separated by one or more
           space characters.
    
           If a numeric value has no decimal point (or E or D) it is returned as
           type LONG.  If it contains more than 8 numerals, or contains the
           character 'D', then it is returned as type DOUBLE.  Otherwise it is
           returned as type FLOAT.    If an integer is too large to be stored as
           type LONG, then it is returned as DOUBLE.
    
     CALLING SEQUENCE: 
           Result = FXPAR( HDR, NAME  [, ABORT, COUNT=, COMMENT=, /NOCONTINUE ] )
    
           Result = FXPAR(HEADER,'DATE')           ;Finds the value of DATE
           Result = FXPAR(HEADER,'NAXIS*')         ;Returns array dimensions as
                                                   ;vector
     REQUIRED INPUTS: 
           HDR     = FITS header string array (e.g. as returned by FXREAD).  Each
                     element should have a length of 80 characters
           NAME    = String name of the parameter to return.  If NAME is of the
                     form 'keyword*' then an array is returned containing values
                     of keywordN where N is an integer.  The value of keywordN
                     will be placed in RESULT(N-1).  The data type of RESULT will
                     be the type of the first valid match of keywordN found.
     OPTIONAL INPUT: 
           ABORT   = String specifying that FXPAR should do a RETALL if a
                     parameter is not found.  ABORT should contain a string to be
                     printed if the keyword parameter is not found.  If not
                     supplied, FXPAR will return with a negative !err if a keyword
                     is not found.
           START   = A best-guess starting position of the sought-after
                     keyword in the header.  If specified, then FXPAR
                     first searches for scalar keywords in the header in
                     the index range bounded by START-PRECHECK and
                     START+POSTCHECK.  This can speed up keyword searches
                     in large headers.  If the keyword is not found, then
                     FXPAR searches the entire header.  
    
                     If not specified then the entire header is searched.
                     Searches of the form 'keyword*' also search the
                     entire header and ignore START.
    
                     Upon return START is changed to be the position of
                     the newly found keyword.  Thus the best way to
                     search for a series of keywords is to search for
                     them in the order they appear in the header like
                     this:
    
                           START = 0L
                           P1 = FXPAR('P1', START=START)
                           P2 = FXPAR('P2', START=START)
           PRECHECK = If START is specified, then PRECHECK is the number
                      of keywords preceding START to be searched.
                      Default: 5
           POSTCHECK = If START is specified, then POSTCHECK is the number
                       of keywords after START to be searched.
                       Default: 20
     OUTPUT: 
           The returned value of the function is the value(s) associated with the
           requested keyword in the header array.
    
           If the parameter is complex, double precision, floating point, long or
           string, then the result is of that type.  Apostrophes are stripped from
           strings.  If the parameter is logical, 1 is returned for T, and 0 is
           returned for F.
    
           If NAME was of form 'keyword*' then a vector of values are returned.
    
     OPTIONAL INPUT KEYWORDS: 
           /NOCONTINUE = If set, then continuation lines will not be read, even
                     if present in the header
     OPTIONAL OUTPUT KEYWORD:
           COUNT   = Optional keyword to return a value equal to the number of
                     parameters found by FXPAR.
           COMMENTS= Array of comments associated with the returned values.
    
     PROCEDURE CALLS: 
           GETTOK(), VALID_NUM
     SIDE EFFECTS: 
    
           The system variable !err is set to -1 if parameter not found, 0 for a
           scalar value returned.  If a vector is returned it is set to the number
           of keyword matches found.
    
           If a keyword occurs more than once in a header, a warning is given,
           and the first occurence is used.  However, if the keyword is "HISTORY",
           "COMMENT", or "        " (blank), then multiple values are returned.
    
     NOTES:
    	The functions SXPAR() and FXPAR() are nearly identical, although
    	FXPAR() has slightly more sophisticated parsing.   There is no
    	particular reason for having two nearly identical procedures, but
    	both are too widely used to drop either one.
    
     REVISION HISTORY: 
           Version 1, William Thompson, GSFC, 12 April 1993.
                   Adapted from SXPAR
           Version 2, William Thompson, GSFC, 14 October 1994
                   Modified to use VALID_NUM instead of STRNUMBER.  Inserted
                   additional call to VALID_NUM to trap cases where character
                   strings did not contain quotation marks.
           Version 3, William Thompson, GSFC, 22 December 1994
                   Fixed bug with blank keywords, following suggestion by Wayne
                   Landsman.
           Version 4, Mons Morrison, LMSAL, 9-Jan-98
                   Made non-trailing ' for string tag just be a warning (not
                   a fatal error).  It was needed because "sxaddpar" had an
                   error which did not write tags properly for long strings
                   (over 68 characters)
           Version 5, Wayne Landsman GSFC, 29 May 1998
                   Fixed potential problem with overflow of LONG values
           Version 6, Craig Markwardt, GSFC, 28 Jan 1998, 
                   Added CONTINUE parsing         
           Version 7, Craig Markwardt, GSFC, 18 Nov 1999,
                   Added START, PRE/POSTCHECK keywords for better performance
    

    (See ../pfidl/astro_lib/fxpar.pro)


    FXPARPOS()

    [Previous Routine] [Next Routine] [List of Routines]
     NAME: 
    	FXPARPOS()
     Purpose     : 
    	Finds position to insert record into FITS header.
     Explanation : 
    	Finds the position to insert a record into a FITS header.  Called from
    	FXADDPAR.
     Use         : 
    	Result = FXPARPOS(KEYWRD, IEND  [, BEFORE=BEFORE ]  [, AFTER=AFTER ])
     Inputs      : 
    	KEYWRD	= Array of eight-character keywords in header.
    	IEND	= Position of END keyword.
     Opt. Inputs : 
    	None.
     Outputs     : 
    	Result of function is position to insert record.
     Opt. Outputs: 
    	None.
     Keywords    : 
    	BEFORE	= Keyword string name.  The parameter will be placed before the
    		  location of this keyword.  For example, if BEFORE='HISTORY'
    		  then the parameter will be placed before the first history
    		  location.  This applies only when adding a new keyword;
    		  keywords already in the header are kept in the same position.
    
    	AFTER	= Same as BEFORE, but the parameter will be placed after the
    		  location of this keyword.  This keyword takes precedence over
    		  BEFORE.
    
    	If neither BEFORE or AFTER keywords are passed, then IEND is returned.
    
     Calls       : 
    	None.
     Common      : 
    	None.
     Restrictions: 
    	KEYWRD and IEND must be consistent with the relevant FITS header.
     Side effects: 
    	None.
     Category    : 
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. : 
    	William Thompson, Jan 1992.
     Written     : 
    	William Thompson, GSFC, January 1992.
     Modified    : 
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
     Version     : 
    	Version 1, 12 April 1993.
    	Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/fxparpos.pro)


    FXPOSIT

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
         FXPOSIT
     PURPOSE:
         Return the unit number of a FITS file positioned at specified extension
     EXPLANATION:
         The FITS file will be ready to be read at the beginning of the 
         specified extension.
    
     CALLING SEQUENCE:
         unit=FXPOSIT(FILE, EXT_NO, /READONLY, COMPRESS=program, /SILENT)
    
     INPUT PARAMETERS:
         FILE    = FITS file name, scalar string
         EXT_NO  = Extension to be moved to, scalar nonnegative integer
    
     RETURNS:
         Unit number of file or -1 if an error is detected.
    
     OPTIONAL KEYWORD PARAMETER:
         /READONLY - If this keyword is set and non-zero, then OPENR rather 
                    than OPENU will be used to open the FITS file.
         COMPRESS - If this keyword is set and non-zero, then then treat
                    the file as compressed.  If 1 assume a gzipped file.
                    Where possible use IDLs internal decompression
                    facilities (i.e., v5.3 or greater) or on Unix systems
                    spawn off a process to decompress and use its output
                    as the FITS stream.  If the keyword is not 1, then
                    use its value as a string giving the command needed for
                    decompression.
         /SILENT    If set, then suppress any messages about invalid characters
                    in the FITS file.
    
     COMMON BLOCKS:
          None.
     SIDE EFFECTS:
          Opens and returns the descriptor of a file.
     PROCEDURE:
          Open the appropriate file, or spawn a command and intercept
          the output.
          Call FXMOVE to get to the appropriate extension.
     PROCEDURE CALLS:
          EXPAND_TILDE() (Unix only), FXPAR(), FXMOVE()
     MODIFICATION HISTORY:
          Derived from William Thompson's FXFINDEND routine.
          Modified by T.McGlynn, 5-October-1994.
           Modified by T.McGlynn, 25-Feb-1995 to handle compressed
              files.  Pipes cannot be accessed using FXHREAD so
              MRD_HREAD was written.
           W. Landsman 23-Apr-1997    Force the /bin/sh shell when uncompressing 
           W. Landsman 26-May-1997    Non-unix is not just VMS
           T. McGlynn  22-Apr-1999    Add /binary modifier needed for Windows
           T. McGlynn  03-June-1999   Use /noshell option to get rid of processes left by spawn.
                                      Use findfile to retain ability to use wildcards
           W. Landsman 03-Aug-1999    Use EXPAND_TILDE under Unix to find file
           T. McGlynn  04-Apr-2000    Put reading code into FXMOVE,
                                      additional support for compression from D.Palmer.
           W. Landsman/D.Zarro 04-Jul-2000    Added test for !VERSION.OS EQ 'Win32' (WinNT)
           W. Landsman    12-Dec-2000 Added /SILENT keyword
           W. Landsman April 2002     Use FILE_SEARCH for V5.5 or later
    

    (See ../pfidl/astro_lib/fxposit.pro)


    FXREAD

    [Previous Routine] [Next Routine] [List of Routines]
     NAME: 
    	FXREAD
     Purpose     : 
    	Read basic FITS files.
     Explanation : 
    	Read the primary array from a disk FITS file.  Optionally allows the
    	user to read in only a subarray and/or every Nth pixel.
     Use         : 
    	FXREAD, FILENAME, DATA  [, HEADER  [, I1, I2  [, J1, J2 ]]  [, STEP]]
     Inputs      : 
    	FILENAME = String containing the name of the file to be read.
     Opt. Inputs : 
    	I1,I2	 = Data range to read in the first dimension.  If passed, then
    		   HEADER must also be passed.  If not passed, or set to -1,-1,
    		   then the entire range is read.
    	J1,J2	 = Data range to read in the second dimension.  If passed, then
    		   HEADER and I1,J2 must also be passed.  If not passed, or set
    		   to -1,-1, then the entire range is read.
    	STEP	 = Step size to use in reading the data.  If passed, then
    		   HEADER must also be passed.  Default value is 1.  Ignored if
    		   less than 1.
     Outputs     : 
    	DATA	 = Data array to be read from the file.
     Opt. Outputs: 
    	HEADER	 = String array containing the header for the FITS file.
     Keywords    : 
    	NANVALUE = Value signalling data dropout.  All points corresponding to
    		   IEEE NaN (not-a-number) are set to this value.  Ignored
    		   unless DATA is of type float or double-precision.
    	PROMPT	 = If set, then the optional parameters are prompted for at the
    		   keyboard.
    	AVERAGE	 = If set, then the array size is reduced by averaging pixels
    		   together rather than by subselecting pixels.  Ignored unless
    		   STEP is nontrivial.  Note:  this is much slower.
    	YSTEP	 = If passed, then STEP is the step size in the 1st dimension,
    		   and YSTEP is the step size in the 2nd dimension.  Otherwise,
    		   STEP applies to both directions.
    	NOSCALE	 = If set, then the output data will not be scaled using the
    		   optional BSCALE and BZERO keywords in the FITS header.
    		   Default is to scale, if and only if BSCALE and BZERO are
    		   present and nontrivial.
    	NOUPDATE = If set, then the optional BSCALE and BZERO keywords in the
    		   optional HEADER array will not be changed.  The default is
    		   to reset these keywords to BSCALE=1, BZERO=0.  Ignored if
    		   NOSCALE is set.
    	ERRMSG   = If defined and passed, then any error messages will be
    		   returned to the user in this parameter rather than
    		   depending on the MESSAGE routine in IDL.  If no errors are
    		   encountered, then a null string is returned.  In order to
    		   use this feature, ERRMSG must be defined first, e.g.
    
    			ERRMSG = ''
    			FXREAD, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...
    
     Calls       : 
    	GET_DATE, IEEE_TO_HOST, FXADDPAR, FXHREAD, FXPAR, WHERENAN
     Common      : 
    	None.
     Restrictions: 
    	Groups are not supported.
    
    	The optional parameters I1, I2, and STEP only work with one or
    	two-dimensional arrays.  J1 and J2 only work with two-dimensional
    	arrays.
    
    	Use of the AVERAGE keyword is not compatible with arrays with missing
    	pixels.
    
     Side effects: 
    	If the keywords BSCALE and BZERO are present in the FITS header, and
    	have non-trivial values, then the returned array DATA is formed by the
    	equation
    
    			DATA = BSCALE*original + BZERO
    
    	However, this behavior can overridden by using the /NOSCALE keyword.
    
    	If the data is scaled, then the optional HEADER array is changed so
    	that BSCALE=1 and BZERO=0.  This is so that these scaling parameters
    	are not applied to the data a second time by another routine.  Also,
    	history records are added storing the original values of these
    	constants.  Note that only the returned array is modified--the header
    	in the FITS file itself is untouched.
    
    	If the /NOUPDATE keyword is set, however, then the BSCALE and BZERO
    	keywords are not changed.  It is then the user's responsibility to
    	ensure that these parameters are not reapplied to the data.  In
    	particular, these keywords should not be present in any header when
    	writing another FITS file, unless the user wants their values to be
    	applied when the file is read back in.  Otherwise, FITS readers will
    	read in the wrong values for the data array.
    	
     Category    : 
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. : 
    	W. Thompson, May 1992, based in part on READFITS by W. Landsman, and
    			       STSUB by M. Greason and K. Venkatakrishna.
    	W. Thompson, Jun 1992, added code to interpret BSCALE and BZERO
    			       records, and added NOSCALE and NOUPDATE
    			       keywords.
    	W. Thompson, Aug 1992, changed to call FXHREAD, and to add history
    			       records for BZERO, BSCALE.
     Written     : 
    	William Thompson, GSFC, May 1992.
     Modified    : 
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 17 November 1993.
    		Corrected bug with AVERAGE keyword on non-IEEE compatible
    		machines.
    		Corrected bug with subsampling on VAX machines.
    	Version 3, William Thompson, GSFC, 31 May 1994
    		Added ERRMSG keyword.
           Version 4, William Thompson, GSFC, 23 June 1994
                   Modified so that ERRMSG is not touched if not defined.
           Version 5, Zarro (SAC/GSFC), 14 Feb 1997 
                   Added I/O error checking
           Version 6, 20-May-1998, David Schlegel/W. Thompson
                   Allow a single pixel to be read in.
                   Change the signal to read in the entire array to be -1
     Version     :
           Version 6,   20-May-1998
    

    (See ../pfidl/astro_lib/fxread.pro)


    GAUSSIAN

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           GAUSSIAN
     PURPOSE:
           Compute the 1-d Gaussian function and optionally the derivative
     EXPLANATION:
           Compute the 1-D Gaussian function and optionally the derivative 
           at an array of points.
    
     CALLING SEQUENCE:
           y = gaussian( xi, parms,[ pderiv ])
    
     INPUTS:
           xi = array, independent variable of Gaussian function.
    
           parms = parameters of Gaussian, 2, 3 or 4 element array:
                   parms[0] = maximum value (factor) of Gaussian,
                   parms[1] = mean value (center) of Gaussian,
                   parms[2] = standard deviation (sigma) of Gaussian.
                   (if parms has only 2 elements then sigma taken from previous
                   call to gaussian(), which is stored in a  common block).
                   parms[3] = optional, constant offset added to Gaussian.
     OUTPUT:
           y -  Function returns array of Gaussian evaluated at xi.    Values will
                be floating pt. (even if xi is double) unless the /DOUBLE keyword
                is set.
    
     OPTIONAL INPUT:
           /DOUBLE - set this keyword to return double precision for both
                 the function values and (optionally) the partial derivatives.
     OPTIONAL OUTPUT:
           pderiv = [N,3] or [N,4] output array of partial derivatives,
                   computed only if parameter is present in call.
    
                   pderiv[*,i] = partial derivative at all xi absisca values
                   with respect to parms[i], i=0,1,2,[3].
    
    
     EXAMPLE:
           Evaulate a Gaussian centered at x=0, with sigma=1, and a peak value
           of 10 at the points 0.5 and 1.5.   Also compute the derivative
    
           IDL> f = gaussian( [0.5,1.5], [10,0,1], DERIV )
           ==> f= [8.825,3.25].   DERIV will be a 2 x 3 array containing the
           numerical derivative at the two points with respect to the 3 parameters.
     
     COMMON BLOCKS:
           None
     HISTORY:
           Written, Frank Varosi NASA/GSFC 1992.
           Converted to IDL V5.0   W. Landsman   September 1997
           Use machar() for machine precision, added /DOUBLE keyword,
           add optional constant 4th parameter    W. Landsman   November 2001
    

    (See ../pfidl/astro_lib/gaussian.pro)


    GETPSF

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	GETPSF
     PURPOSE:
    	To generate a point-spread function (PSF) from observed stars. 
     EXPLANATION:
    	The PSF is represented as a 2-dimensional Gaussian
    	(integrated over each pixel) and a lookup table of residuals.
    	The lookup table and Gaussian parameters are output in a FITS
    	image file.   The PSF FITS file created by GETPSF can be
    	read with the procedure RDPSF.      Adapted from the 1986 STSDAS 
    	version of DAOPHOT
    
     CALLING SEQUENCE:
    	GETPSF, image, xc, yc, apmag, sky, [ronois, phpadu, gauss, psf, 
    			idpsf, psfrad, fitrad, psfname, /DEBUG ]
    
     INPUTS:
    	IMAGE  - input image array
    	XC     - input vector of x coordinates (from FIND), these should be
    		IDL (first pixel is (0,0)) convention.
    	YC     - input vector of y coordinates (from FIND)
    	APMAG  - vector of magnitudes (from APER), used for initial estimate
    		of gaussian intensity.  If APMAG is multidimensional, (more
    		than 1 aperture was used in APER) then the first aperture
    		is used.
    	SKY    - vector of sky values (from APER)                
    
     OPTIONAL INPUTS:
    	The user will be prompted for the following parameters if not supplied.
    
    	RONOIS - readout noise per pixel, (in electrons, or equivalent photons)
    	PHPADU - photons per analog digital unit, used to scale the data
    		numbers in IMAGE into photon units
    	IDPSF  - subscripts of the list of stars created by 
    		APER which will be used to define the PSF.   Stars whose
    		centroid does not fall within PSFRAD of the edge of the frame,
    		or for which a Gaussian fit requires more than 25 iterations,
    		will be ignored when creating the final PSF.
    	PSFRAD - the scalar radius, in pixels, of the circular area within
    		which the PSF will be defined.   This should be slightly larger
    		than the radius of the brightest star that one will be
    		interested in.
    	FITRAD - the scalar radius, in pixels of the circular area used in the
    		least-square star fits.  Stetson suggest that FITRAD should
    		approximately equal to the FWHM, slightly less for crowded
    		fields.  (FITRAD must be smaller than PSFRAD.)
    	PSFNAME- Name of the FITS file that will contain the table of residuals,
    		and the best-fit Gaussian parameters.    This file is 
    		subsequently required for use by NSTAR.  
    
     OPTIONAL OUTPUTS:
    	GAUSS  - 5 element vector giving parameters of gaussian fit to the 
    		first PSF star
    		GAUSS(0) - height of the gaussian (above sky)
    		GAUSS(1) - the offset (in pixels) of the best fitting gaussian
    			and the original X centroid
    		GAUSS(2) - similiar offset from the Y centroid 
    		GAUSS(3) - Gaussian sigma in X
    		GAUSS(4) - Gaussian sigma in Y
    	PSF    - 2-d array of PSF residuals after a Gaussian fit.
    
     PROCEDURE:
    	GETPSF fits a Gaussian profile to the core of the first PSF star 
    	and generates a look-up table of the residuals of the
    	actual image data from the Gaussian fit.  If desired, it will then
    	fit this PSF to another star (using PKFIT) to determine its precise 
    	centroid, scale the same Gaussian to the new star's core, and add the
    	differences between the actual data and the scaled Gaussian to the
    	table of residuals.   (In other words, the Gaussian fit is performed
    	only on the first star.)
    
     OPTIONAL KEYWORD INPUT:
    	DEBUG - if this keyword is set and non-zero, then the result of each
    		fitting iteration will be displayed.
    
     PROCEDURES CALLED
    	DAOERF, MAKE_2D, MKHDR, RINTER(), PKFIT, STRNUMBER(), STRN(), WRITEFITS
    
     REVISON HISTORY:
    	Adapted from the 1986 version of DAOPHOT in STSDAS
    	IDL Version 2  W Landsman           November 1988
    	Use DEBUG keyword instead of !DEBUG  W. Landsman       May 1996
    	Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/getpsf.pro)


    GETTOK

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	GETTOK                                    
     PURPOSE:
    	Retrieve the first part of the string up to a specified character
     EXPLANATION:
    	GET TOKen - Retrieve first part of string until the character char 
    	is encountered.
    
     CALLING SEQUENCE:
    	token = gettok( st, char )
    
     INPUT:
    	char - character separating tokens, scalar string
    
     INPUT-OUTPUT:
    	st - (scalar) string to get token from (on output token is removed)
    
     OUTPUT:
    	token - scalar string value is returned 
    
     EXAMPLE:
    	If ST is 'abc=999' then gettok(ST,'=') would return
    	'abc' and ST would be left as '999' 
    
     NOTES:
           A version of GETTOK that accepts vector strings is available for users 
           of IDL V5.3 or later from  http://idlastro.gsfc.nasa.gov/ftp/v53/
     HISTORY
    	version 1  by D. Lindler APR,86
    	Remove leading blanks    W. Landsman (from JKF)    Aug. 1991
    	Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/gettok.pro)


    GET_DATE

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           GET_DATE
     PURPOSE:
           Return the (current) UTC date in CCYY-MM-DD format for FITS headers
     EXPLANATION:
           This is the format required by the DATE and DATE-OBS keywords in a 
           FITS header.
    
     CALLING SEQUENCE:
           GET_DATE, FITS_date, [ in_date, /OLD, /TIMETAG, LOCAL_DIFF=]
     OPTIONAL INPUTS:
           in_date - string (scalar or vector) containing dates in IDL
                systime() format (e.g. 'Tue Sep 25 14:56:14 2001')
     OUTPUTS:
           FITS_date = A scalar character string giving the current date.    Actual
                   appearance of dte depends on which keywords are supplied.
           
           No Keywords supplied - dte is a 10 character string with the format
                   CCYY-MM-DD where  represents a calendar year,  the
                   ordinal number of a calendar month within the calendar year, 
                   and 
    the ordinal number of a day within the calendar month. /TIMETAG set - dte is a 19 character string with the format CCYY-MM-DDThh:mm:ss where represents the hour in the day, the minutes, the seconds, and the literal 'T' the ISO 8601 time designator /OLD set - dte is an 8 character string in DD/MM/YY format INPUT KEYWORDS: /TIMETAG - Specify the time to the nearest second in the DATE format /OLD - Return the DATE format formerly (pre-1997) recommended for FITS Note that this format is now deprecated because it uses only a 2 digit representation of the year. LOCAL_DIFF - numeric scalar giving the difference between local time and Greenwich Mean Time (GMT) in hours. This keyword is only needed for non-Unix users prior to V5.4. Unix users should not use this keyword because under Unix (or since V5.4 with any OS), SYSTIME(1) returns the UTC (=GMT) time directly. Users on other machines must either supply a LOCAL_DIFF keyword, or use the TIME_CONV environment variable discussed below. For example, a user on U.S. Eastern Standard Time should set LOCAL_DIFF = -5 EXAMPLE: Add the current date to the DATE keyword in a FITS header,h IDL> GET_DATE,dte IDL> sxaddpar, h, 'DATE', dte, 'Date header was created' ENVIRONMENT VARIABLE: An alternate method of inputing the difference between local and GMT time for non-Unix machines is to specify this information in a file named local_diff.dat in a directory specified with the environment variable TIME_CONV. For example, a user in EST should write -5 on this first (and only) line of this file. NOTES: (1) A discussion of the DATExxx syntax in FITS headers can be found in http://www.cv.nrao.edu/fits/documents/standards/year2000.txt (2) Those who wish to use need further flexibility in their date formats (e.g. to use TAI time) should look at Bill Thompson's time routines in http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/time PROCEDURES USED: DAYCNV - Convert Julian date to Gregorian calendar date REVISION HISTORY: Written W. Landsman March 1991 Major rewrite to write new DATExxx syntax W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997 Work after year 2000 even with /OLD keyword W. Landsman January 2000 Don't need to worry about TIME_DIFF since V5.4 W. Landsman July 2001

    (See ../pfidl/astro_lib/get_date.pro)


    HEADFITS

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           HEADFITS
     PURPOSE:
           Read a FITS (primary or extension) header into a string array.
     EXPLANATION:
           Under Unix, HEADFITS() can also read gzip (.gz) or Unix compressed
           (.Z) FITS files.   In IDL V5.3 or later, HEADFITS() can read gzip files
           under any machine OS. 
    
     CALLING SEQUENCE:
           Result = HEADFITS(Filename/Fileunit ,[ ERRMSG =, EXTEN= , COMPRESS=, 
                                                /SILENT ])
    
     INPUTS:
           Filename = String containing the name of the FITS file to be read.
                    File names ending in '.gz' are assumed to be gzip'ed compressed
                    and under Unix file names ending in '.Z' are assumed to be
                    Unix compressed.    If this default behaviour is not sufficient
                    then use the COMPRESS keyword.
                                or
           Fileunit - A scalar integer specifying the unit of an already opened
                      FITS file.  The unit will remain open after exiting 
                      HEADFITS().  There are two possible reasons for choosing 
                      to specify a unit number rather than a file name:
              (1) For a FITS file with many extensions, one can move to the 
                  desired extensions with FXPOSIT() and then use HEADFITS().  This
                  is more efficient that repeatedly starting at the beginning of 
                  the file.
              (2) For reading a FITS file across a Web http: address after opening
                  the unit with the SOCKET procedure (IDL V5.4 or later,
                  Unix and Windows only) 
     OPTIONAL INPUT KEYWORDS:
          EXTEN  = integer scalar, specifying which FITS extension to read.
                   For example, to read the header of the first extension set
                   EXTEN = 1.   Default is to read the primary FITS header 
                   (EXTEN = 0).    The EXTEN keyword cannot be used when a unit
                   number is supplied instead of a file name.
         COMPRESS - If this keyword is set and non-zero, then treat the file
                  as compressed.  If 1 assume a gzipped file.   Where possible use
                  IDLs internal decompression facilities (i.e., v5.3 or greater) 
                  or on Unix systems spawn off a process to decompress and use its
                  output as the FITS stream.  If the keyword is not 1, then use 
                  its value as a string giving the command needed for 
                  decompression.   See FXPOSIT for more info.
         /SILENT - If set, then suppress any warning messages about invalid 
                  characters in the FITS file.
     OPTIONAL KEYWORD OUTPUT:
           ERRMSG	= If this keyword is present, then any error messages will be
                     returned to the user in this parameter rather than
                     depending on the MESSAGE routine in IDL.  If no errors are
                     encountered, then a null string is returned.  
    
     OUTPUTS:
           Result of function = FITS header, string array
    
     EXAMPLE:
           Print the main FITS header of a file 'test.fits' into a string 
           variable, h
    
           IDL>  print, headfits( 'test.fits')
    
           Print the second extension header of a gzip compressed FITS file
           'test.fits.gz'.  Use HPRINT for pretty format
    
           IDL> hprint, headfits( 'test.fits.gz', ext=2)
    
     PROCEDURES CALLED
           FXPOSIT(), MRD_HREAD
     MODIFICATION HISTORY:
           adapted by Frank Varosi from READFITS by Jim Wofford, January, 24 1989
           Keyword EXTEN added, K.Venkatakrishna, May 1992
           Make sure first 8 characters are 'SIMPLE'  W. Landsman October 1993
           Check PCOUNT and GCOUNT   W. Landsman    December 1994
           Major rewrite, work for Unix gzip files,   W. Landsman  April 1996
           Converted to IDL V5.0   W. Landsman   September 1997
           Added COMPRESS keyword  W. Landsman   April 2000
           Added ERRMSG keyword    W. Landsman   July 2000
           Added /SILENT keyword   W. Landsman    December 2000
           Option to read a unit number rather than file name W.L    October 2001
    

    (See ../pfidl/astro_lib/headfits.pro)


    HPRINT

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           HPRINT
     PURPOSE:
           Print a FITS header (or other string array) one line at a time
     EXPLANATION:
           The string array is  printed 1 line at a time.
           Needed because IDL will add an extra space to the 80 character
           FITS lines on TTY terminals, causing a space to appear between lines.
    
     CALLING SEQUENCE:
           HPRINT, h, [ firstline ]
    
     INPUTS:
           H - FITS header (or any other string array).
    
     OPTIONAL INPUT:
           FIRSTLINE - scalar integer specifying the first line to begin 
                   displaying.   The default is FIRSTLINE = 1, i.e. display 
                   all the lines.     If Firstline is negative, then the first
                   line to be printed is counted backward from the last line.
    
     NOTES:
           HPRINT has the following differences from the intrinsic PRINT procedure
    
           (1) Arrays are printed one line at a time to avoid a space between 80
                   character lines
           (2) Lines are trimmed with STRTRIM before being printed to speed up 
                   display
           (3) The /more option is used for output. 
    
     EXAMPLE:
           Read the header from a FITS file named 'test.fits' and display it at the
           terminal beginning with line 50
    
           IDL> h = headfits( 'test.fits')         ;Read FITS header
           IDL> hprint, h, 50                      ;Display starting at line 50
    
           To print the last 25 lines of the header
    
           IDL> hprint, h, -25
    
     REVISION HISTORY:
           Written W. Landsman                     July, 1990
           Added test for user quit                July, 1991
           Added optional FIRSTLINE parameter      November, 1992
           Modified for when STDOUT is not a TTY W. Landsman  September 1995
           Converted to IDL V5.0   W. Landsman   September 1997
           Fixed printing in IDLDE, C. Gehman      August, 1998
    

    (See ../pfidl/astro_lib/hprint.pro)


    IEEE_TO_HOST

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
         IEEE_TO_HOST
     PURPOSE:
         Translate an IDL variable from IEEE-754 to host representation 
     EXPLANATION:
         The variable is translated from IEEE-754 (as used, for
         example, in FITS data ), into the host machine architecture.
    
         Duplicates most of the functionality of the SWAP_ENDIAN_INPLACE procedure
         introduced in V5.6, with the addition of the IDLTYPE keyword.
     CALLING SEQUENCE:
         IEEE_TO_HOST, data, [ IDLTYPE = , ]
    
     INPUT-OUTPUT PARAMETERS:
         data - any IDL variable, scalar or vector.   It will be modified by
                 IEEE_TO_HOST to convert from IEEE to host representation.  Byte 
                 and string variables are returned by IEEE_TO_HOST unchanged
    
     OPTIONAL KEYWORD INPUTS:
         IDLTYPE - scalar integer (1-15) specifying the IDL datatype according
                   to the code given by the SIZE function.     This keyword
                   is usually when DATA is a byte array to be interpreted as
                   another datatype (e.g. FLOAT).
    
     EXAMPLE:
           A 2880 byte array (named FITARR) from a FITS record is to be 
           interpreted as floating and converted to the host representaton:
    
           IDL> IEEE_TO_HOST, fitarr, IDLTYPE = 4     
    
     METHOD:
           The BYTEORDER procedure is called with the appropriate keyword
    
     MODIFICATION HISTORY:
          Written, W. Landsman   Hughes/STX   May, 1992
          Converted to IDL V5.0   W. Landsman   September 1997
          Under VMS check for IEEE -0.0 values   January 1998
          VMS now handle -0.0 values under IDL V5.1    July 1998
          Added new integer datatypes  C. Markwardt/W. Landsman  July 2000
          Post-V5.1 version, no VMS negative zero check  W. Landsman July 2001
          Use size(/type)  W. Landsman December 2002
          Use /SWAP_IF_LITTLE_ENDIAN keyword for 64bit types W. Landsman Feb 2003
    

    (See ../pfidl/astro_lib/ieee_to_host.pro)


    IMAGE_DECONVOLVE

    [Previous Routine] [Next Routine] [List of Routines]
    
    unction image_deconvolve,datain,psfin,sigmain,guess=guess, $
                             maxiterations=maxiter,double=double, $
                             uselog=uselogin, positive=positive, $
                             quiet=quietin, mask=maskin, float=float, $
                             usepsfcorr=usepsfcorrin, $
                             useautocorr=useautocorrin, chi2limit=chi2limitin, $
                             memweight=memweight, usepoisson=usepoissonin, $
                             chi2aim=chi2aimin, fixmemweight=fixmemweight, $
                             flux=fluxin,fftguess=fftguess
    
    NAME:
         IMAGE_DECONVOLVE
    PURPOSE:
         Deconvolve a PSF from an image
    CATEGORY:
    CALLING SEQUENCE:
         new_image = image_deconvolve(image,psf,sigma)
    INPUTS:
         image = raw image
         psf = PSF centered on floor(nx/2),floor(ny/2)
         sigma = error estimate for image (must be positive and non-zero)
    OPTIONAL INPUT PARAMETERS:
    KEYWORD PARAMETERS
         guess = initial guess (default = image)
         /fftguess = Use the direct FFT inversion as the initial guess.  The
                     inversion is returned in teh guess keyword, overwriting
                     the contents of guess.
         maxiterations = maximum number of iterattions (def = 100)
         /double = use double precision in the FFT's (DEFAULT)
         /float = use single precision in the FFT's (faster but less robust)
         /uselog = Iterate the log of the image to provide an absolute positivity
                   constraint.
         /positive = Apply crude positivity constraint.  Can cause failure to 
                     converge.  Ignored if /uselog is set.  If neither /positive
                     not /uselog is set, then the deconvolved image is allowed to 
                     go negative.
         flux = Try to force flux to be conserved by adding a condition that 
                the residuals are balanced (i.e. sum to zero).  The value of 
                flux is the weight given to the condition, start at 1.0 and work
                work your way up or down from there (bigger means more weight on
                this condition).
                There is no guarantee that the flux conservation will succeed.
                Note that masked areas are allowed to float and are not included
                in the flux calculation.
         /quiet = Do not print diagnostics or plot intermediate images.
         mask = index vector of pixels in image that should be NOT be included in the
                GOF calculation.  If not set, all pixels are used.  Slows down the
                calculation, so should not be used unless necessary.
         /usepsfcorr = add a term to force the correlation of the residual and the
                       PSF to be flat.  This is sometimes useful for avoiding
                       overcorrections. 
         chi2limit = limit for chi^2.  When this value is reached the iteration
                     is terminated.
         chi2aim = The value of chi^2 that the algorithm should aim for.  The
                   weight is dynamically adjusted to get chi^2 to this value.
                   there's no guarantee it will succeed, however.  Default = 1.0.
         /usepoisson = Use poisson statistics instead of Gaussian statistics.
                       In this case sigma isn't really used, but you have to 
                       put in something reasonalbe to make the displays look
                       right.  Also if /usepsfcorr is set, sigma is used in the
                       gradient calculation even when /usepoisson is set.
         memweight = Initial weight of the entropy terms.  Will be adjusted by
                     the algorithm to make chi^2=chi2aim.  Default = 1.0.
         /fixmemweight = Force memweight to reamain fixed at the value given by
                         the memweight keyword.  Try setting this if the
                         algorithm fails to converge.
    OUTPUTS:
    COMMON BLOCKS:
    SIDE EFFECTS:
    RESTRICTIONS:
         The deconvolution is done with the FFT so the dimension of the input
         data should be a power of two for speed.
    
         The iteration is done on the log of the image to give a strict
         positivity constraint.  Hence, if the data is anywhere equal to zero,
         the zero values are changed to 1. 
    PROCEDURE:
         Uses a simple (and slow!) maximum entropy technique.  Iterates the log
         of the image for a positivity constraint with the /uselog keyword set.
    MODIFICATION HISTORY:
         T. Metcalf 1999-Sep-21
         T. Metcalf 1999-Oct-01  Added /uselog and /positive.
         T. Metcalf 2000-Feb-09  Added /quiet keyword
         T. Metcalf 2000-Mar-01  Added /float and made /double the default.
         T. Metcalf 2000-Mar-07  Changed the weighting of the entropy term
         T. Metcalf 2000-Mar-21  New implementation of usepsfcorr
         T. Metcalf 2000-Mar-23  Fixed bug in entropy gradient
         T. Metcalf 2000-Mar-24  Added /usepoisson, chi2aim keywords.
         T. Metcalf 2000-Mar-31  Added memweight and /fixmemweight keywords and
                                 allow a crude search for the best value of the
                                 MEM weighting by attempting to reach a final
                                 chi^2 value given by the chi2aim keyword.  Also
                                 changed the implementation of the usepsfcorr
                                 term slightly.
         T. Metcalf 2000-Sep-15  Added /flux keyword.
         T. Metcalf 2001-Jan-10  Fixed calculation of flux when mask is set.
         T. Metcalf 2001-Jan-16  Added check for sigma > 0.0
         T. Metcalf 2001-Jan-24  Added /fftguess keyword
         T. Metcalf 2001-Jan-29  The main code now uses the C-statistic when 
                                 /usepoisson is set.  The image_decon_func always
                                 used this anyway, but the change makes the
                                 MEM Lagrange multiplier calculation better with
                                 /usepoisson.
    

    (See ../pfidl/astro_lib/image_deconvolve.pro)


    IS_IEEE_BIG

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	IS_IEEE_BIG
     PURPOSE:
    	Determine if the current machine uses IEEE, big-endian numbers.
     EXPLANATION:
           (Big endian implies that byteorder XDR conversions are no-ops).
     CALLING SEQUENCE:
    	flag = is_ieee_big()
     INPUT PARAMETERS:
           None
     RETURNS:
           1 if the machine appears to be IEEE-compliant, 0 if not.
     COMMON BLOCKS:
    	None.
     SIDE EFFECTS:
    	None
     RESTRICTIONS:
     PROCEDURE:
           A sample int, long, float and double are converted using
           byteorder and compared with the original.  If there is no
           change, the machine is assumed to be IEEE compliant and
           big-endian.
     MODIFICATION HISTORY:
           Written 15-April-1996 by T. McGlynn for use in MRDFITS.
    	13-jul-1997	jkf/acc	- added calls to check_math to avoid
    				  underflow messages in V5.0 on Win32 (NT).
    	Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/is_ieee_big.pro)


    MAX_ENTROPY

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	MAX_ENTROPY
    
     PURPOSE:
    	Deconvolution of data by Maximum Entropy analysis, given the PSF
     EXPLANATION:
    	Deconvolution of data by Maximum Entropy analysis, given the 
    	instrument point spread response function (spatially invariant psf).
    	Data can be an observed image or spectrum, result is always positive.
    	Default is convolutions using FFT (faster when image size = power of 2).
    
     CALLING SEQUENCE:
    	for i=1,Niter do begin
    	Max_Entropy, image_data, psf, image_deconv, multipliers, FT_PSF=psf_ft
    
     INPUTS:
    	data = observed image or spectrum, should be mostly positive,
    					with mean sky (background) near zero.
    	psf = Point Spread Function of instrument (response to point source,
    							must sum to unity).
    	deconv = result of previous call to Max_Entropy,
    	multipliers = the Lagrange multipliers of max.entropy theory
    		(on first call, set = 0, giving flat first result).
    
     OUTPUTS:
    	deconv = deconvolution result of one more iteration by Max_Entropy.
    	multipliers = the Lagrange multipliers saved for next iteration.
    
     OPTIONAL INPUT KEYWORDS:
    	FT_PSF = passes (out/in) the Fourier transform of the PSF,
    		so that it can be reused for the next time procedure is called,
          /NO_FT overrides the use of FFT, using the IDL function convol() instead.
          /LINEAR switches to Linear convergence mode, much slower than the
    		default Logarithmic convergence mode.
    	LOGMIN = minimum value constraint for taking Logarithms (default=1.e-9).
     EXTERNAL CALLS:
    	function convolve( image, psf ) for convolutions using FFT or otherwise.
     METHOD:
    	Iteration with PSF to maximize entropy of solution image with
    	constraint that the solution convolved with PSF fits data image.
    	Based on paper by Hollis, Dorband, Yusef-Zadeh, Ap.J. Feb.1992,
    	which refers to Agmon, Alhassid, Levine, J.Comp.Phys. 1979.
    
           A more elaborate image deconvolution program using maximum entropy is 
           available at 
           http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/image/image_deconvolve.pro
     HISTORY:  
    	written by Frank Varosi at NASA/GSFC, 1992.
    	Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/max_entropy.pro)


    MAX_LIKELIHOOD

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	MAX_LIKELIHOOD
    
     PURPOSE:
    	Maximum likelihood deconvolution of an image or a spectrum.
     EXPLANATION:
     	Deconvolution of an observed image (or spectrum) given the 
    	instrument point spread response function (spatially invariant psf).
    	Performs iteration based on the Maximum Likelihood solution for
    	the restoration of a blurred image (or spectrum) with additive noise.
    	Maximum Likelihood formulation can assume Poisson noise statistics
    	or Gaussian additive noise, yielding two types of iteration.
    
     CALLING SEQUENCE:
    	for i=1,Niter do Max_Likelihood, data, psf, deconv, FT_PSF=psf_ft
    
     INPUTS PARAMETERS:
    	data = observed image or spectrum, should be mostly positive,
    				with mean sky (background) near zero.
    	psf = Point Spread Function of the observing instrument,
    				(response to a point source, must sum to unity).
     INPUT/OUTPUT PARAMETERS:
    	deconv = as input: the result of previous call to Max_Likelihood,
    		(initial guess on first call, default = average of data),
    		as output: result of one more iteration by Max_Likelihood.
    	Re_conv = (optional) the current deconv image reconvolved with PSF
    		for use in next iteration and to check convergence.
    
     OPTIONAL INPUT KEYWORDS:
          /GAUSSIAN causes max-likelihood iteration for Gaussian additive noise
    		to be used,  otherwise the default is Poisson statistics.
    	FT_PSF = passes (out/in) the Fourier transform of the PSF,
    		so that it can be reused for the next time procedure is called,
          /NO_FT overrides the use of FFT, using the IDL function convol() instead.
    	POSITIVITY_EPS = value of epsilon passed to function positivity,
    			default = -1 which means no action (identity).
    	UNDERFLOW_ZERO = cutoff to consider as zero, if numbers less than this.
    
     EXTERNAL CALLS:
    	function convolve( image, psf ) for convolutions using FFT or otherwise.
    	function positivity( image, EPS= ) to make image positive.
    
     METHOD:
    	Maximum Likelihood solution is a fixed point of an iterative eq.
    	(derived by setting partial derivatives of Log(Likelihood) to zero).
    	Poisson noise case was derived by Richardson(1972) & Lucy(1974).
    	Gaussian noise case is similar with subtraction instead of division.
     HISTORY:
    	written: Frank Varosi at NASA/GSFC, 1992.
    	F.V. 1993, added optional arg. Re_conv (to avoid doing it twice).
    	Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/max_likelihood.pro)


    MKHDR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           MKHDR
     PURPOSE:
           Make a minimal primary (or IMAGE extension) FITS header
     EXPLANATION:
           If an array is supplied,  then the created FITS header will be 
           appropriate to the supplied array.  Otherwise, the user can specify 
           the dimensions and datatype.
    
     CALLING SEQUENCE:
           MKHDR, header                   ;Prompt for image size and type
                   or
           MKHDR, header, im, [ /IMAGE, /EXTEND ]
                   or
           MKHDR, header, type, naxisx, [/IMAGE, /EXTEND ]         
    
     OPTIONAL INPUTS:
           IM - If IM is a vector or array then the header will be made
                   appropriate to the size and type of IM.  IM does not have
                   to be the actual data; it can be a dummy array of the same
                   type and size as the data.    Set IM = '' to create a dummy
                   header with NAXIS = 0. 
           TYPE - If more than 2 parameters are supplied, then the second parameter
                   is interpreted as an integer giving the IDL datatype e.g. 
                   1 - LOGICAL*1, 2 - INTEGER*2, 4 - REAL*4, 3 - INTEGER*4
           NAXISX - Vector giving the size of each dimension (NAXIS1, NAXIS2, 
                   etc.).  
    
     OUTPUT:
           HEADER - image header, (string array) with required keywords
                   BITPIX, NAXIS, NAXIS1, ... Further keywords can be added
                   to the header with SXADDPAR. 
    
     OPTIONAL INPUT KEYWORDS:
           /IMAGE   = If set, then a minimal header for a FITS IMAGE extension
                   is created.    An IMAGE extension header is identical to
                   a primary FITS header except the first keyword is 
                   'XTENSION' = 'IMAGE' instead of 'SIMPLE  ' = 'T'
           /EXTEND  = If set, then the keyword EXTEND is inserted into the file,
                   with the value of "T" (true).    The EXTEND keyword must be
                   included in a primary header, if the FITS file contains 
                   extensions.
    
     RESTRICTIONS:
           (1)  MKHDR should not be used to make an STSDAS header or a FITS
                   ASCII or Binary Table extension header.   Instead use
    
                   SXHMAKE - to create a minimal STSDAS header
                   FXBHMAKE - to create a minimal FITS binary table header
                   FTCREATE - to create a minimal FITS ASCII table header
    
           (2)  Any data already in the header before calling MKHDR
                   will be destroyed.
     EXAMPLE:
           Create a minimal FITS header, Hdr, for a 30 x 40 x 50 INTEGER*2 array
    
                 IDL> mkhdr, Hdr, 2, [30,40,50]
    
           Alternatively, if the array already exists as an IDL variable, Array,
    
                  IDL> mkhdr, Hdr, Array
    
     PROCEDURES CALLED:
           SXADDPAR, GET_DATE
    
     REVISION HISTORY:
           Written November, 1988               W. Landsman
           May, 1990, Adapted for IDL Version 2.0, J. Isensee
           Aug, 1997, Use SYSTIME(), new DATE format  W. Landsman
           Converted to IDL V5.0   W. Landsman   September 1997
           Allow unsigned data types    W. Landsman   December 1999
           Set BZERO = 0 for unsigned integer data  W. Landsman January 2000
           EXTEND keyword must immediately follow last NAXISi W. Landsman Sep 2000
           Add FITS definition COMMENT to primary headers W. Landsman Oct. 2001
           Allow (nonstandard) 64 bit integers   W. Landsman  Feb. 2003
    

    (See ../pfidl/astro_lib/mkhdr.pro)


    MRDFITS

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
         MRDFITS
    
     PURPOSE:
         Read all standard FITS data types into arrays or structures.
    
     EXPLANATION:
          Further information on MRDFITS is available at
          http://idlastro.gsfc.nasa.gov/mrdfits.html 
    
     CALLING SEQUENCE:
          Result = MRDFITS( Filename/FileUnit,[Extension, Header],
                           /FSCALE , /DSCALE , /UNSIGNED,
                           ALIAS=strarr[2,n], /USE_COLNUM,
                           /NO_TDIM, /OLD_STRUCT, $
                           /POINTER_VAR, /FIXED_VAR,
                           RANGE=[a,b], COLUMNS=[a,b,...]), ERROR_ACTION=x,
                           COMPRESS=comp_prog, STATUS=status, /VERSION )
    
     INPUTS:
          Filename = String containing the name of the file to be read or
                     file number of an open unit.  If a unit is specified
                     if will be left open positioned to read the next HDU.
                     Note that the file name may be of the form
                     name.gz or name.Z on UNIX systems.  If so
                     the file will be dynamically decompressed.
          FiluUnit = An integer file unit which has already been
                     opened for input.  Data will be read from this
                     unit and the unit will be left pointing immediately
                     after the HDU that is read.  Thus to read a compressed
                     file with many HDU's a user might do something like:
                          lun=fxposit(filename, 3)  ; Skip the first three HDU's
                          repeat begin
                              thisHDU = mrdfits(lun, 0, hdr, status=status)
                              ... process the HDU ...
                          endrep until status lt 0
    
          Extension= Extension number to be read, 0 for primary array.
                     Assumed 0 if not specified.
                     If a unit rather than a filename
                     is specified in the first argument, this is
                     the number of HDU's to skip from the current position.
    
     OUTPUTS:
          Result = FITS data array or structure constructed from
                   the designated extension.  The format of result depends
                   upon the type of FITS data read.
                 Non-group primary array or IMAGE extension:
                   A simple multidimensional array is returned with the
                   dimensions given in the NAXISn keywords.
                 Grouped image data with PCOUNT=0.
                   As above but with GCOUNT treated as NAXIS(n+1).
                 Grouped image data with PCOUNT>0.
                   The data is returned as an array of structures.  Each
                   structure has two elements.  The first is a one-dimensional
                   array of the group parameters, the second is a multidimensional
                   array as given by the NAXIS2-n keywords.
                 ASCII and BINARY tables.
                   The data is returned as a structure with one column for
                   each field in the table.  The names of the columns are
                   normally taken from the TTYPE keywords (but see USE_COLNUM).
                   Bit field columns
                   are stored in byte arrays of the minimum necessary
                   length.  Column names are truncated to 15 characters
                   if longer, spaces are removed, and invalid characters
                   are replaced by underscores.
                   Columns specified as variable length columns are stored
                   with a dimension equal to the largest actual dimension
                   used.  Extra values in rows are filled with 0's or blanks.
                   If the size of the variable length column is not
                   a constant, then an additional column is created giving the 
                   size used in the current row.  This additional column will 
                   have a tag name of the form L#_"colname" where # is the column
                   number and colname is the column name of the variable length
                   column.   If the length of each element of a variable length 
                   column is 0 then the column is deleted.
    
                   Prior to V5.0, IDL structures were limited to 128 tags.
                   If the version is before V5.0, or the /OLD_STRUCT is set, then
                   for FITS files with more than 127 columns, data in the first
                   64 elements of the structure are stored in the primary
                   structure, the next 64 as a substructure of the 65th
                   element, the next 64 as a substructure of the 66th element
                   and so forth.
    
     OPTIONAL OUTPUT:
           Header = String array containing the header from the FITS extension.
    
     OPTIONAL INPUT KEYWORDS:
           ALIAS    The keyword allows the user to specify the column names
                    to be created when reading FITS data.  The value of
                    this keyword should be a 2xn string array.  The first
                    value of each pair of strings should be the desired
                    tag name for the IDL column.  The second should be
                    the FITS TTYPE value.  Note that there are restrictions
                    on valid tag names.  The order of the ALIAS keyword
                    is compatible with MWRFITS.
           COLUMNS - This keyword allows the user to specify that only a
                    subset of columns is to be returned.  The columns
                    may be specified either as number 1,... n or by
                    name or some combination of these two.
                    If USE_COLNUM is specified names should be C1,...Cn.
                    The use of this keyword will not save time or internal
                    memory since the extraction of specified columns
                    is done after all columns have been retrieved from the
                    FITS file.
           COMPRESS - This keyword allows the user to specify a
                    decompression program to use to decompress a file that
                    will not be automatically recognized based upon
                    the file name.
           /DSCALE - As with FSCALE except that the resulting data is
                    stored in doubles.
           ERROR_ACTION - Set the on_error action to this value (defaults
                    to 2).
           /FIXED_VAR- Translate variable length columns into fixed length columns
                    and provide a length column for truly varying columns.
                    This was only behavior prior to V2.5 or MRDFITS and remains
                    the default (see /POINTER_VAR)
           /FSCALE - If present and non-zero then scale data to float
                    numbers for arrays and columns which have either
                    non-zero offset or non-unity scale.
                    If scaling parameters are applied, then the corresponding
                    FITS scaling keywords will be modified.
           NO_TDIM  - Disable processing of TDIM keywords.  If NO_TDIM
                    is specified MRDFITS will ignore TDIM keywords in
                    binary tables.
           OLD_STRUCT- Use the recursive structures formats required
                    prior to IDL 5.0 for tables with more than 127 columns.
           /POINTER_VAR- Use pointer arrays for variable length columns.
                    In addition to changing the format in which
                    variable length arrays are stored, if the pointer_var
                    keyword is set to any value other than 1 this also disables
                    the deletion of variable length columns. (See /FIXED_VAR)
           RANGE  - A scalar or two element vector giving the start
                    and end rows to be retrieved.  For ASCII and BINARY
                    tables this specifies the row number.  For GROUPed data
                    this will specify the groups.  For array images, this
                    refers to the last non-unity index in the array.  E.g.,
                    for a 3 D image with NAXIS* values = [100,100,1], the
                    range may be specified as 0:99, since the last axis
                    is suppressed.  Note that the range uses IDL indexing
                    So that the first row is row 0.
                    If only a single value, x, is given in the range,
                    the range is assumed to be [0,x-1].
           /SILENT - Suppress informative messages.
           STRUCTYP - The structyp keyword specifies the name to be used
                    for the structure defined when reading ASCII or binary
                    tables.  Generally users will not be able to conveniently
                    combine data from multiple files unless the STRUCTYP
                    parameter is specified.  An error will occur if the
                    user specifies the same value for the STRUCTYP keyword
                    in calls to MRDFITS in the same IDL session for extensions
                    which have different structures.
           TEMPDIR - The tempdir keyword allows the user to specify
                    the directory where temporary files may be created.
                    This directory should be both in the IDL path
                    and writable by the user.    Generally only needed for IDL
           /UNSIGNED - For integer data with appropriate zero points and scales
                    read the data into unsigned integer arrays.
           /USE_COLNUM - When creating column names for binary and ASCII tables
                    MRDFITS attempts to use the appropriate TTYPE keyword
                    values.  If USE_COLNUM is specified and non-zero then
                    column names will be generated as 'C1, C2, ... 'Cn'
                    for the number of columns in the table.
           /VERSION Print the current version number
    
     OPTIONAL OUTPUT KEYWORDS:
           STATUS - A integer status indicating success or failure of
                    the request.  A status of >=0 indicates a successful read.
                    Currently
                        0 -> successful completion
                       -1 -> error
                       -2 -> end of file
    
     EXAMPLE:
           Read a FITS primary array:
                   a = mrdfits('TEST.FITS')    or
                   a = mrdfits('TEST.FITS', 0, header)
           The second example also retrieves header information.
    
           Read rows 10-100 of the second extension of a FITS file.
                   a = mrdfits('TEST.FITS', 2, header, range=[10,100])
    
           Read a table and ask that any scalings be applied and the
           scaled data be converted to doubles.  Use simple column names,
           suppress outputs.
                   a = mrdfits('TEST.FITS', 1, /dscale, /use_colnum, /silent)
    
     RESTRICTIONS:
           (1)     Cannot handle data in non-standard FITS formats.
           (2)     Doesn't do anything with BLANK or NULL values or
                   NaN's.  They are just read in.  They may be scaled
                   if scaling is applied.
     NOTES:
           This multiple format FITS reader is designed to provide a
           single, simple interface to reading all common types of FITS data.
           MRDFITS DOES NOT scale data by default.  The FSCALE or DSCALE
           parameters must be used.
    
           As of version 2.5 MRDFITS support 64 bit integer data types.
           These are not standard FITS.  64 bit data also requires
           IDL version 5.2 or greater.
        
    
     PROCEDURES USED:
           The following procedures are contained in the main MRDFITS program.
               MRD_IMAGE           -- Generate array/structure for images.
               MRD_READ_IMAGE      -- Read image data.
               MRD_ASCII           -- Generate structure for ASCII tables.
               MRD_READ_ASCII      -- Read an ASCII table.
               MRD_TABLE           -- Generate structure for Binary tables.
               MRD_READ_TABLE      -- Read binary table info.
               MRD_READ_HEAP       -- Read variable length record info.
               MRD_SCALE           -- Apply scaling to data.
               MRD_COLUMNS         -- Extract columns.
    
            Other ASTRON Library routines used
               FXPAR(), FXADDPAR, IEEE_TO_HOST, FXPOSIT, FXMOVE(), IS_IEEE_BIG()
               MRD_STRUCT(), MRD_SKIP
    
     MODIfICATION HISTORY:
           V1.0 November 9, 1994 ----  Initial release.
              Creator: Thomas A. McGlynn
           V1.1 January 20, 1995 T.A. McGlynn
              Fixed bug in variable length records.
              Added TDIM support -- new routine mrd_tdim in MRD_TABLE.
           V1.2
              Added support for dynamic decompression of files.
              Fixed further bugs in variable length record handling.
           V1.2a
              Added NO_TDIM keyword to turn off TDIM processing for
              those who don't want it.
              Bug fixes: Handle one row tables correctly, use BZERO rather than
                   BOFFSET.     Fix error in scaling of images.  
           V1.2b 
              Changed MRD_HREAD to handle null characters in headers.
           V2.0 April 1, 1996
              -Handles FITS tables with an arbitrary number of columns.
              -Substantial changes to MRD_STRUCT to allow the use of
              substructures when more than 127 columns are desired.
              -All references to table columns are now made through the
              functions MRD_GETC and MRD_PUTC.  See description above.
              -Use of SILENT will now eliminate compilation messages for
              temporary functions.
              -Bugs in handling of variable length columns with either
              a single row in the table or a maximum of a single element
              in the column fixed.
              -Added support for DCOMPLEX numbers in binary tables (M formats) for
              IDL versions above 4.0.  
              -Created regression test procedure to check in new versions.
              -Added error_action parameter to allow user to specify
              on_error action.  This should allow better interaction with
              new CHECK facility.  ON_ERROR statements deleted from
              most called routines.
              - Modified MRDFITS to read in headers containing null characters
              with a warning message printed.
           V2.0a April 16, 1996
              - Added IS_IEEE_BIG() checks (and routine) so that we don't
              worry about IEEE to host conversions if the machine's native
              format is IEEE Big-endian.
           V2.1 August 24, 1996
              - Use resolve_routine for dynamically defined functions
              for versions > 4.0
              - Fix some processing in random groups format.
              - Handle cases where the data segment is--legally--null.
              In this case MRDFITS returns a scalar 0.
              - Fix bugs with the values for BSCALE and BZERO (and PSCAL and
              PZERO) parameters set by MRDFITS.
           V2.1a April 24, 1997  Handle binary tables with zero length columns
           V2.1b May 13,1997 Remove whitespace from replicate structure definition
           V2.1c May 28,1997 Less strict parsing of XTENSION keyword
           V2.1d June 16, 1997 Fixed problem for >32767 entries introduced 24-Apr
           V2.1e Aug 12, 1997 Fixed problem handling double complex arrays
           V2.1f Oct 22, 1997 IDL reserved words can't be structure tag names
           Converted to IDL V5.0   W. Landsman  2-Nov-1997
           V2.1g Nov 24, 1997 Handle XTENSION keywords with extra blanks.
           V2.1h Jul 26, 1998 More flexible parsing of TFORM characters
           V2.2 Dec 14, 1998 Allow fields with longer names for
                            later versions of IDL.
                            Fix handling of arrays in scaling routines.
                            Allow >128 fields in structures for IDL >4.0
                            Use more efficient structure copying for
                            IDL>5.0
           V2.2b June 17, 1999 Fix bug in handling case where
                               all variable length columns are deleted
                               because they are empty.
           V2.3 March 7, 2000 Allow user to supply file handle rather
                              than file name.
                              Added status field.
                              Now needs FXMOVE routine
           V2.3b April 4, 2000
                              Added compress option (from D. Palmer)
           V2.4  July 4, 2000 Added STATUS=-1 for "File access error" (Zarro/GSFC)
           V2.4a May 2, 2001  Trim binary format string   (W. Landsman)
           V2.5 December 5, 2001 Add unsigned, alias, 64 bit integers. version, $
                               /pointer_val, /fixed_var.
           V2.5a Fix problem when both the first and the last character
                in a TTYPEnn value are invalid structure tag characters
           V2.6 February 15, 2002 Fix error in handling unsigned numbers, $
                               and 64 bit unsigneds. (Thanks to Stephane Beland)
           V2.6a September 2, 2002 Fix possible conflicting data structure for
                              variable length arrays (W. Landsman)
    
           Note to users of IDL prior to V5.0:  This version is compiled
           with the [] array syntax.  To convert this version to run under
           the earlier syntax you use W. Landsman's IDL5to4 routine
           at http://idlastro.gsfc.nasa.gov/ftp/contrib/landsman/v5.
           You need to change all array subscripts from the []
           to () but this cannot be done as a global replace since
           array initializations of the form x=[1,2] must be left unchanged.
           Subroutines called by this routine may need similar modification.
           Also the use of the pointer syntax (in versions 2.5 and above
           is not parseable by earlier version of IDL.
    

    (See ../pfidl/astro_lib/mrdfits.pro)


    MRD_HREAD

    [Previous Routine] [Next Routine] [List of Routines]
     NAME: 
         MRD_HREAD
    
     PURPOSE: 
         Reads a FITS header from an opened disk file or Unix pipe
     EXPLANATION:
         Like FXHREAD but also works with compressed Unix files
    
     CALLING SEQUENCE: 
         MRD_HREAD, UNIT, HEADER  [, STATUS, /SILENT ]
     INPUTS: 
         UNIT    = Logical unit number of an open FITS file
     OUTPUTS: 
         HEADER  = String array containing the FITS header.
     OPT. OUTPUTS: 
         STATUS  = Condition code giving the status of the read.  Normally, this
                     is zero, but is set to -1 if an error occurs, or if the
                     first byte of the header is zero (ASCII null).
     OPTIONAL KEYWORD INPUT:
          /SILENT - If set, then warning messages about any invalid characters in
                    the header are suppressed.
          /FIRSTBLOCK - If set, then only the first block (36 lines or less) of 
                    the FITS header are read into the output variable.   If only
                    size information (e.g. BITPIX, NAXIS) is needed from the
                    header, then the use of this keyword can save time.  The 
                    file pointer is still positioned at the end of the header,
                    even if the /FIRSTBLOCK keyword is supplied.
     RESTRICTIONS: 
          The file must already be positioned at the start of the header.  It
          must be a proper FITS file.
     SIDE EFFECTS: 
           The file ends by being positioned at the end of the FITS header, unless
           an error occurs.
     REVISION HISTORY:
          Written,  Thomas McGlynn                     August 1995
          Modified, Thomas McGlynn		     January 1996
             Changed MRD_HREAD to handle Headers which have null characters
              A warning message is printed out but the program continues.
              Previously MRD_HREAD would fail if the null characters were
              not in the last 2880 byte block of the header.  Note that
              such characters are illegal in the header but frequently
              are produced by poor FITS writers.
          Converted to IDL V5.0   W. Landsman   September 1997
          Added /SILENT keyword   W. Landsman   December 2000
          Added /FIRSTBLOCK keyword  W. Landsman   February 2003
    

    (See ../pfidl/astro_lib/mrd_hread.pro)


    MRD_SKIP

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           MRD_SKIP
     PURPOSE:
           Skip a number of bytes from the current location in a file or a pipe
     EXPLANATION:
           First tries using POINT_LUN and if this doesn't work, perhaps because
           the unit is a pipe, MRD_SKIP will just read in the requisite number 
           of bytes.    GZIP files opened with /COMPRESS (in V5.3 or later) are
           also read as a series of bytes, since this is faster than using 
           POINT_LUN when not at the beginning of a file. 
     CALLING SEQUENCE:
           MRD_SKIP, Unit, Nskip
    
     INPUTS:
           Unit - File unit for the file or pipe in question, integer scalar
           Nskip - Number of bytes to be skipped, positive integer
     NOTES:
           This routine should be used in place of POINT_LUN wherever a pipe
           may be the input unit (see the procedure FXPOSIT for an example).  
           Note that it assumes that it can only work with nskip >= 0 so it 
           doesn't even try for negative values.      
    
           For reading a pipe, MRD_SKIP currently uses a maximum buffer size
           of 8 MB.   This chunk value can be increased for improved efficiency
           (or decreased if you really have little memory.)
     REVISION HISTORY:
           Written, Thomas A. McGlynn    July 1995
    	Don't even try to skip bytes on a pipe with POINT_LUN, since this
    	might reset the current pointer     W. Landsman        April 1996
           Increase buffer size, check fstat.compress W. Landsman  Jan 2001
           Only a warning if trying read past EOF   W. Landsman   Sep 2001
    

    (See ../pfidl/astro_lib/mrd_skip.pro)


    MRD_STRUCT

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           MRD_STRUCT
     PURPOSE:
           Return a structure as defined in the names and values data.
     CALLING SEQUENCE:
           struct = MRD_STRUCT(NAMES, VALUES, NROW,                $
                       STRUCTYP=structyp,                          $
                       TEMPDIR=tempdir, /OLD_STRUCT)
     INPUT PARAMETERS:
           NAMES   = A string array of names of structure fields.
           VALUES  = A string array giving the values of the structure
                     fields.  See examples below.
           NROW    = The number of elements in the structure array.
           
     RETURNS:
           A structure as described in the parameters or 0 if an error
           is detected.
    
     OPTIONAL KEYWORD PARAMETERS:
           STRUCTYP = The structure type.  Since IDL does not allow the
                      redefinition of a named structure it is an error
                      to call MRD_STRUCT with different parameters but
                      the same STRUCTYP in the same session.  If this
                      keyword is not set an anonymous structure is created.
           TEMPDIR  = If the structure is more than modestly complex a
                      temporary file is created.  This file will be
                      created in the current directory unless the TEMPDIR
                      keyword is specified.  Note that the temporary directory
                      should also be in the IDL search path.
           OLD_STRUCT=Use old format structures.
     COMMON BLOCKS:
           MRD_COMMON
     SIDE EFFECTS:                                                            
           May create a temporary file if the structure definition is too long 
           for the EXECUTE function and using old style structures
    
     RESTRICTIONS:
           By default this program uses a series of execute
           commands and create_struct's to create the structure.
           If the old_struct keyword is set, then a program may
           be dynamically compiled.  The nominal maximum length
           of the execute string is 131 characters, but many systems
           seem to allow longer values.  This code may execute more
           efficiently with a longer execute buffer.
     PROCEDURE:
           A structure definition is created using the parameter values.
           MRD_NSTRUCT is called if the OLD_STRUCT keyword is not specified
           and generates the structure in pieces using the
           execute and create_struct keywords.
    
           If the old_struct flag is set, then the program tries to compile
           the structure with a single execute command.  If the structure
           definition is too long  MRD_FSTRUCT is called to write, compile and
           execute a function which will define the structure.
     EXAMPLES:
           str = mrd_struct(['fld1', 'fld2'], ['0','dblarr(10,10)'],3)
           print, str(0).fld2(3,3)
    
           str = mrd_struct(['a','b','c','d'],['1', '1.', '1.d0', "'1'"],1)
                   ; returns a structure with integer, float, double and string
                   ; fields.
     PROCEDURE CALLS:
           CONCAT_DIR - Used to concatenate temporary directory with filename
     MODIFICATION HISTORY:
           Created by T. McGlynn October, 1994.
           Modified by T. McGlynn September, 1995.
              Added capability to create substructures so that structure
              may contain up to 4096 distinct elements.  [This can be
              increased by futher iteration of the process used if needed.]
           Converted to IDL V5.0   W. Landsman   September 1997
           Removed V4.0 reference to common block  October 1997
           Allowed unlimited number of structure elements if the version
           is greater than 5.0.  Put back in code to handle prior versions.
           The [] will need to be translated back to () for this to
           work.  T. McGlynn December 15 1998.
           Add MRD_NSTRUCT since IDL has mysterious problems compiling
           very large structures.
    

    (See ../pfidl/astro_lib/mrd_struct.pro)


    PKFIT

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	PKFIT
     PURPOSE:
    	Subroutine of  GETPSF to perform a one-star least-squares fit 
     EXPLANATION:
    	Part of the DAOPHOT PSF photometry sequence
    
     CALLING SEQUENCE:
    	PKFIT, f, scale, x, y, sky, radius, ronois, phpadu, gauss, psf, 
    				errmag, chi, sharp, Niter, /DEBUG 
     INPUTS:
    	F      - NX by NY array containing actual picture data.           
    	X, Y   - the initial estimates of the centroid of the star relative
    		to the corner (0,0) of the subarray.  Upon return, the
    		final computed values of X and Y will be passed back to the
    		calling routine.
    	SKY  -   the local sky brightness value, as obtained from APER
    	RADIUS-  the fitting radius-- only pixels within RADIUS of the
    		instantaneous estimate of the star's centroid will be
    		included in the fit, scalar
    	RONOIS - readout noise per pixel, scalar
    	PHPADU - photons per analog digital unit, scalar
    	GAUSS -  vector containing the values of the five parameters defining
    		the analytic Gaussian which approximates the core of the PSF.
    	PSF   -  an NPSF by NPSF look-up table containing corrections from
    		the Gaussian approximation of the PSF to the true PSF.
    
     INPUT-OUTPUT:
    	SCALE  - the initial estimate of the brightness of the star,
    		expressed as a fraction of the brightness of the PSF.
    		Upon return, the final computed value of SCALE will be
    		passed back to the calling routine.
     OUTPUTS:
    	ERRMAG - the estimated standard error of the value of SCALE
    		returned by this routine.
    	CHI    - the estimated goodness-of-fit statistic:  the ratio
    		of the observed pixel-to-pixel mean absolute deviation from
    		the profile fit, to the value expected on the basis of the
    		noise as determined from Poisson statistics and the 
    		readout noise.
    	SHARP  - a goodness-of-fit statistic describing how much broader  
    		the actual profile of the object appears than the
    		profile of the PSF.
    	NITER -  the number of iterations the solution required to achieve
    		convergence.  If NITER = 25, the solution did not converge.
    		If for some reason a singular matrix occurs during the least-
    		squares solution, this will be flagged by setting NITER = -1.
    
     RESTRICTIONS:
    	No parameter checking is performed
     REVISON HISTORY:
    	Adapted from the official DAO version of 1985 January 25
    	Version 2.0 W. Landsman STX             November 1988
    	Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/pkfit.pro)


    POSITIVITY

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	POSITIVITY
     PURPOSE:
    	Map an image uniquely and smoothly into all positive values.
     EXPLANATION:
    	Take unconstrained x (usually an image), and map it uniquely and 
    	smoothly into positive values.   Negative values of x get mapped to 
    	interval ( 0, sqrt( epsilon )/2 ], positive values go to 
    	( sqrt( epsilon )/2, oo ) with deriv approaching 1.  Derivative is 
    	always 1/2 at x=0.   Derivative is used by the MRL deconvolution 
    	algorithm.
    
     CALLING SEQUENCE:
    	result = POSITIVITY( x, [ /DERIVATIVE, EPSILON = )
    
     INPUTS:
    	x - input array, unconstrained
    
     OUTPUT:
    	result =  output array = ((x + sqrt(x^2 + epsilon))/2
    		if the /DERIV keyword is set then instead the derivative of
    		the above expression with respect to X is returned
    
     OPTIONAL INPUT KEYWORDS:
    	DERIV -  if this keyword set, then the derivative of the positivity
    		mapping is returned, rather than the mapping itself
    	EPSILON - real scalar specifying the interval into which to map
    		negative values.    If EPSILON EQ 0 then the mapping reduces to 
    		positive truncation.   If EPSILON LT then the mapping reduces to
    		an identity (no change).  Default is EPSILON = 1e-9 
    
     REVISION HISTORY:
    	 F.Varosi NASA/GSFC 1992, as suggested by R.Pina UCSD.
    	Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/positivity.pro)


    PSF_GAUSSIAN

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           PSF_GAUSSIAN
    
     PURPOSE:
           Create a 1-d, 2-d, or 3-d Gaussian with specified FWHM, center 
     EXPLANATION:
           Return a point spread function having Gaussian profiles,
           as either a 1D vector, a 2D image, or 3D volumetric-data.
    
     CALLING SEQUENCE:
           psf = psf_Gaussian( NPIXEL=, FWHM= , CENTROID = 
                         [ /DOUBLE, /NORMALIZE, /ST_DEV,  NDIMEN= ] ) 
     or:
           psf = psf_Gaussian( parameters, NPIXEL = ,NDIMEN = )
    
     REQUIRED INPUT KEYWORD:
           NPIXEL = number pixels for each dimension, specify as an array,
                   or just one number to make all sizes equal.
    
     OPTIONAL KEYWORDS:
           CENTROID = floating scalar or vector giving position of  PSF center.    
                   default is exact center of requested vector/image/volume.
                   The number of elements in CENTROID should equal the number of
                   dimensions.    **The definition of Centroid was changed in
                   March 2002, and now an integer defines the center of a pixel.**
    
           /DOUBLE  = If set, then the output array is computed in double precision
                   the default is to return a floating point array.
    
           FWHM = the desired Full-Width Half-Max (pixels) in each dimension,
                   specify as an array, or single number to make all the same.
    
           NDIMEN = integer dimension of result: either 1 (vector), 2 (image), or 
                    3 (volume), default = 2 (an image result).
    
           /NORMALIZE causes resulting PSF to be normalized so Total( psf ) = 1.
    
           STDEV = optional way to specify width by standard deviation param.
    
           XY_CORREL = scalar between 0 and 1 specifying correlation coefficient
                   Use this keyword, for example, to specify an elliptical 
                   Gaussian oriented at an angle to the X,Y axis.   Only valid
                   for 2-dimensional case.
    
    
     INPUTS (optional):
    
           parameters = an NDIMEN by 3 array giving for each dimension:
                           [ maxval, center, stdev ],  overrides other keywords.
    
     EXAMPLE:
           (1) Create a 31 x 31 array containing a normalized centered Gaussian 
           with an X FWHM = 4.3 and a Y FWHM = 3.6
    
           IDL> array = PSF_GAUSSIAN( Npixel=31, FWHM=[4.3,3.6], /NORMAL )
    
           (2) Create a 50 pixel 1-d Gaussian vector with a maximum of 12, 
              centered at  pixel 23 with a sigma of 19.2
    
           IDL> psf = psf_gaussian([12,23,19.2],npixel=50)
     EXTERNAL CALLS:
           function Gaussian()
     NOTES:
           To improve speed, floating underflow exceptions are suppressed (using 
           the MASK=32  keyword of CHECK_MATH() rather than being flagged.
    
     HISTORY:
           Written, Frank Varosi NASA/GSFC 1991.
           Converted to IDL V5.0   W. Landsman   September 1997
           Suppress underflow messages, add DOUBLE keyword. **Modified centroid
           definition so integer position is pixel center** W. Landsman March 2002
    

    (See ../pfidl/astro_lib/psf_gaussian.pro)


    READFITS

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           READFITS
     PURPOSE:
           Read a FITS file into IDL data and header variables. 
     EXPLANATION:
           See http://idlastro.gsfc.nasa.gov/fitsio.html for other ways of
           reading FITS files with IDL.
    
     CALLING SEQUENCE:
           Result = READFITS( Filename/Fileunit,[ Header, heap, /NOSCALE, EXTEN_NO=,
                           NSLICE=, /SILENT, STARTROW =, NUMROW = , HBUFFER=,
                           /COMPRESS, /No_Unsigned ] )
    
     INPUTS:
           Filename = Scalar string containing the name of the FITS file  
                     (including extension) to be read.   If the filename has
                      a *.gz extension, it will be treated as a gzip compressed
                      file.   If it has a .Z extension, it will be treated as a
                      Unix compressed file.
                                       OR
           Fileunit - A scalar integer specifying the unit of an already opened
                      FITS file.  The unit will remain open after exiting 
                      READFITS().  There are two possible reasons for choosing 
                      to specify a unit number rather than a file name:
              (1) For a FITS file with many extensions, one can move to the 
                  desired extensions with FXPOSIT() and then use READFITS().  This
                  is more efficient that repeatedly starting at the beginning of 
                  the file.
              (2) For reading a FITS file across a Web http: address after opening
                  the unit with the SOCKET procedure (IDL V5.4 or later,
                  Unix and Windows only) 
     OUTPUTS:
           Result = FITS data array constructed from designated record.
                    If the specified file was not found, then Result = -1
    
     OPTIONAL OUTPUT:
           Header = String array containing the header from the FITS file.
                  If you don't need the header, then the speed may be improved by
                  not supplying this parameter.
           heap = For extensions, the optional heap area following the main
                  data array (e.g. for variable length binary extensions).
    
     OPTIONAL INPUT KEYWORDS:
           /COMPRESS - Signal that the file is gzip compressed.  By default, 
                   READFITS will assume that if the file name extension ends in 
                   '.gz' then the file is gzip compressed.   The /COMPRESS keyword
                   is required only if the the gzip compressed file name does not 
                   end in '.gz'.   Keyword only valid for IDL V5.3 or later.
    
           EXTEN_NO - positive scalar integer specifying the FITS extension to
                   read.  For example, specify EXTEN = 1 or /EXTEN to read the 
                   first FITS extension.   
    
           /NOSCALE - If present and non-zero, then the ouput data will not be
                    scaled using the optional BSCALE and BZERO keywords in the 
                    FITS header.   Default is to scale.
    
           /NO_UNSIGNED -By default, if the header indicates an unsigned integer 
                  (BITPIX = 16, BZERO=2^15, BSCALE=1) then FITS_READ will output 
                   an IDL unsigned integer data type (UINT).   But if /NO_UNSIGNED
                   is set, then the data is converted to type LONG.  
    
           NSLICE - Non-negative integer scalar specifying which N-1 dimensional 
                    slice of a N-dimensional array to read.   For example, if the 
                    primary image of a file 'wfpc.fits' contains a 800 x 800 x 4 
                    array, then 
    
                     IDL> im = readfits('wfpc.fits',h, nslice=2)
                               is equivalent to 
                     IDL> im = readfits('wfpc.fits',h)
                     IDL> im = im[*,*,2]
                     but the use of the NSLICE keyword is much more efficient.
    
           NUMROW -  Scalar non-negative integer specifying the number of rows 
                     of the image or table extension to read.   Useful when one 
                     does not want to read the entire image or table.    
    
           POINT_LUN  -  Position (in bytes) in the FITS file at which to start
                     reading.   Useful if READFITS is called by another procedure
                     which needs to directly read a FITS extension.    Should 
                     always be a multiple of 2880, and not be used with EXTEN_NO
                     keyword.
    
           /SILENT - Normally, READFITS will display the size the array at the
                     terminal.  The SILENT keyword will suppress this
    
            STARTROW - Non-negative integer scalar specifying the row
                   of the image or extension table at which to begin reading. 
                   Useful when one does not want to read the entire table.
    
            HBUFFER - Number of lines in the header, set this to slightly larger
                    than the expected number of lines in the FITS header, to 
                   improve performance when reading very large FITS headers. 
                   Should be a multiple of 36 -- otherwise it will be modified
                   to the next higher multiple of 36.   Default is 180
    
     EXAMPLE:
           Read a FITS file test.fits into an IDL image array, IM and FITS 
           header array, H.   Do not scale the data with BSCALE and BZERO.
    
                  IDL> im = READFITS( 'test.fits', h, /NOSCALE)
    
           If the file contains a FITS extension, it could be read with
    
                  IDL> tab = READFITS( 'test.fits', htab, /EXTEN )
    
           The function TBGET() can be used for further processing of a binary 
           table, and FTGET() for an ASCII table.
           To read only rows 100-149 of the FITS extension,
    
                  IDL> tab = READFITS( 'test.fits', htab, /EXTEN, 
                                       STARTR=100, NUMR = 50 )
    
           To read in a file that has been compressed:
    
                  IDL> tab = READFITS('test.fits.gz',h)
    
     ERROR HANDLING:
           If an error is encountered reading the FITS file, then 
                   (1) the system variable !ERROR is set (via the MESSAGE facility)
                   (2) the error message is displayed (unless /SILENT is set),
                       and the message is also stored in !ERR_STRING
                   (3) READFITS returns with a value of -1
     RESTRICTIONS:
           (1) Cannot handle random group FITS
    
     NOTES:
           (1) If data is stored as integer (BITPIX = 16 or 32), and BSCALE
           and/or BZERO keywords are present, then the output array is scaled to 
           floating point (unless /NOSCALE is present) using the values of BSCALE
           and BZERO.   In the header, the values of BSCALE and BZERO are then 
           reset to 1. and 0., while the original values are written into the 
           new keywords O_BSCALE and O_BZERO.     If the BLANK keyword was
           present, then any input integer values equal to BLANK in the input
           integer image are unchanged by BSCALE or BZERO
           
           (2) The use of the NSLICE keyword is incompatible with the NUMROW
           or STARTROW keywords.
    
           (3) READFITS() underwent a substantial rewrite in October 1998 to 
           eliminate recursive calls, and improve efficiency when reading
           extensions.
                1. The NUMROW and STARTROW keywords can now be used when reading
                  a primary image (extension = 0).
                2. There is no error check for moving past the end of file when
                   reading the data array.
    
           (4) On some Unix shells, one may get a "Broken pipe" message if reading
            a UNIX compressed file, and not reading to the end of the file (i.e. 
            the decompression has not gone to completion).     This is an 
            informative message only, and should not affect the output of 
            READFITS().  
    
     PROCEDURES USED:
           Functions:   SXPAR() 
           Procedures:  SXADDPAR, SXDELPAR
    
     MODIFICATION HISTORY:
           Original Version written in 1988, W.B. Landsman   Raytheon STX
           Revision History prior to October 1998 removed          
           Major rewrite to eliminate recursive calls when reading extensions
                      W.B. Landsman  Raytheon STX                    October 1998
           Add /binary modifier needed for Windows  W. Landsman    April 1999
           Read unsigned datatypes, added /no_unsigned   W. Landsman December 1999
           Output BZERO = 0 for unsigned data types   W. Landsman   January 2000
           Open with /swap_if_little_endian if since V5.1 W. Landsman February 2000
           Fixed logic error when using NSLICE keyword W. Landsman March 2000
           Fixed byte swapping problem for compressed files on little endian 
                 machines introduced in Feb 2000     W. Landsman       April 2000
           Fix error handling so FREE_LUN is called in case of READU error
    						W. Landsman N. Rich, Aug. 2000
           Assume since V5.1, remove NANvalue keyword  W. Landsman   July 2001 
           Support the unofficial 64bit integer format W. Landsman   September 2001
           Option to read a unit number rather than file name W.L    October 2001
           Fix byte swapping problem for compressed files again (sigh...) 
                    W. Landsman   March 2002
           Make sure gzip defined when using a unit number W. Landsman Oct. 2002 
           Assume V5.2 or later            W. Landsman        Jan. 2003
           Don't read entire header unless needed   W. Landsman  Jan. 2003
           Added HBUFFER keyword    W. Landsman   Feb. 2003
    

    (See ../pfidl/astro_lib/readfits.pro)


    STRN

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	STRN
     PURPOSE:
    	Convert a number to a string and remove padded blanks.
     EXPLANATION:
    	The main and original purpose of this procedure is to convert a number
    	to an unpadded string (i.e. with no blanks around it.)  However, it 
    	has been expanded to be a multi-purpose formatting tool.  You may 
    	specify a length for the output string; the returned string is either 
    	set to that length or padded to be that length.  You may specify 
    	characters to be used in padding and which side to be padded.  Finally,
    	you may also specify a format for the number.  NOTE that the input 
    	"number" need not be a number; it may be a string, or anything.  It is
    	converted to string.
    
     CALLING SEQEUNCE:
    	tmp = STRN( number, [ LENGTH=, PADTYPE=, PADCHAR=, FORMAT = ] )
    
     INPUT:
    	NUMBER    This is the input variable to be operated on.  Traditionally,
    		 it was a number, but it may be any scalar type.
    
     OPTIONAL INPUT:
    	LENGTH    This KEYWORD specifies the length of the returned string.  
    		If the output would have been longer, it is truncated.  If 
    		the output would have been shorter, it is padded to the right 
    		length.
    	PADTYPE   This KEYWORD specifies the type of padding to be used, if any.
    		0=Padded at End, 1=Padded at front, 2=Centered (pad front/end)
    		IF not specified, PADTYPE=1
    	PADCHAR   This KEYWORD specifies the character to be used when padding.
    		The default is a space (' ').
    	FORMAT    This keyword allows the FORTRAN type formatting of the input
    		number (e.g. '(f6.2)')
    
     OUTPUT:
    	tmp       The formatted string
    
     USEFUL EXAMPLES:
    	print,'Used ',strn(stars),' stars.'  ==> 'Used 22 stars.'
    	print,'Attempted ',strn(ret,leng=6,padt=1,padch='0'),' retries.'
    		==> 'Attempted 000043 retries.'
    	print,strn('M81 Star List',length=80,padtype=2)
    		==> an 80 character line with 'M81 Star List' centered.
    	print,'Error: ',strn(err,format='(f15.2)')
    		==> 'Error: 3.24'     or ==> 'Error: 323535.22'
    
     HISTORY:
    	03-JUL-90 Version 1 written by Eric W. Deutsch
    	10-JUL-90 Trimming and padding options added         (E. Deutsch)
    	29-JUL-91 Changed to keywords and header spiffed up     (E. Deutsch)
    	Ma7 92 Work correctly for byte values (W. Landsman)
    	19-NOV-92 Added Patch to work around IDL 2.4.0 bug which caused an
    	error when STRN('(123)') was encountered.            (E. Deutsch)
    	Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/strn.pro)


    SXADDPAR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           SXADDPAR
     PURPOSE:
           Add or modify a parameter in a FITS header array.
    
     CALLING SEQUENCE:
           SXADDPAR, Header, Name, Value, [ Comment,  Location, /SaveComment, 
                                   BEFORE =, AFTER = , FORMAT= , /PDU]
    
     INPUTS:
           Header = String array containing FITS or STSDAS header.    The
                   length of each element must be 80 characters.    If not 
                   defined, then SXADDPAR will create an empty FITS header array.
    
           Name = Name of parameter. If Name is already in the header the value 
                   and possibly comment fields are modified.  Otherwise a new 
                   record is added to the header.  If name is equal to 'COMMENT'
                   or 'HISTORY' or a blank string then the value will be added to 
                   the record without replacement.  For these cases, the comment 
                   parameter is ignored.
    
           Value = Value for parameter.  The value expression must be of the 
                   correct type, e.g. integer, floating or string.  String values
                    of 'T' or 'F' are considered logical values.
    
     OPTIONAL INPUT PARAMETERS:
           Comment = String field.  The '/' is added by this routine.  Added 
                   starting in position 31.    If not supplied, or set equal to 
                   '', or /SAVECOMMENT is set, then the previous comment field is 
                   retained (when found) 
    
           Location = Keyword string name.  The parameter will be placed before the
                   location of this keyword.    This parameter is identical to
                   the BEFORE keyword and is kept only for consistency with
                   earlier versions of SXADDPAR.
    
     OPTIONAL INPUT KEYWORD PARAMETERS:
           BEFORE  = Keyword string name.  The parameter will be placed before the
                   location of this keyword.  For example, if BEFORE='HISTORY'
                   then the parameter will be placed before the first history
                   location.  This applies only when adding a new keyword;
                   keywords already in the header are kept in the same position.
    
           AFTER   = Same as BEFORE, but the parameter will be placed after the
                   location of this keyword.  This keyword takes precedence over
                   BEFORE.
    
           FORMAT  = Specifies FORTRAN-like format for parameter, e.g. "F7.3".  A
                   scalar string should be used.  For complex numbers the format
                   should be defined so that it can be applied separately to the
                   real and imaginary parts.  If not supplied then the default is
                   'G19.12' for double precision, and 'G14.7' for floating point.
    
           /PDU    = specifies keyword is to be added to the primary data unit
                   header. If it already exists, it's current value is updated in
                   the current position and it is not moved.
           /SAVECOMMENT = if set, then any existing comment is retained, i.e. the
                   COMMENT parameter only has effect if the keyword did not 
                   previously exist in the header.
     OUTPUTS:
           Header = updated FITS header array.
    
     EXAMPLE:
           Add a keyword 'TELESCOP' with the value 'KPNO-4m' and comment 'Name
           of Telescope' to an existing FITS header h.
    
           IDL> sxaddpar, h, 'TELESCOPE','KPNO-4m','Name of Telescope'
     NOTES:
           The functions SXADDPAR() and FXADDPAR() are nearly identical, with the
           major difference being that FXADDPAR forces required FITS keywords
           BITPIX, NAXISi, EXTEND, PCOUNT, GCOUNT to appear in the required order
           in the header, and FXADDPAR supports the OGIP LongString convention.   
           There is no particular reason for having two nearly identical 
           procedures, but both are too widely used to drop either one.
    
           All HISTORY records are inserted in order at the end of the header.
    
           All COMMENT records are also inserted in order at the end of the header
           header, but before the HISTORY records.  The BEFORE and AFTER keywords
           can override this.
    
           All records with no keyword (blank) are inserted in order at the end of
           the header, but before the COMMENT and HISTORY records.  The BEFORE and
           AFTER keywords can override this.
    
     RESTRICTIONS:
           Warning -- Parameters and names are not checked
                   against valid FITS parameter names, values and types.
    
     MODIFICATION HISTORY:
           DMS, RSI, July, 1983.
           D. Lindler Oct. 86  Added longer string value capability
           Converted to NEWIDL  D. Lindler April 90
           Added Format keyword, J. Isensee, July, 1990
           Added keywords BEFORE and AFTER. K. Venkatakrishna, May '92
           Pad string values to at least 8 characters   W. Landsman  April 94
           Aug 95: added /PDU option and changed routine to update last occurence
                   of an existing keyword (the one SXPAR reads) instead of the
                   first occurence.
           Comment for string data can start after column 32 W. Landsman June 97
           Make sure closing quote supplied with string value  W. Landsman  June 98
           Converted to IDL V5.0    W. Landsman   June 98
           Increase precision of default formatting of double precision floating
                   point values.   C. Gehman, JPL  September 1998
           Mar 2000, D. Lindler, Modified to use capital E instead of lower case
                   e for exponential formats.
           Apr 2000, Make user-supplied format upper-case  W. Landsman 
           Oct 2001, Treat COMMENT or blank string like HISTORY keyword W. Landsman
           Jan 2002, Allow BEFORE, AFTER to apply to COMMENT keywords W. Landsman
           June 2003, Added SAVECOMMENT keyword    W. Landsman
           
    

    (See ../pfidl/astro_lib/sxaddpar.pro)


    SXDELPAR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	SXDELPAR
     PURPOSE:
    	Procedure to delete a keyword parameter(s) from a FITS header
    
     CALLING SEQUENCE:
    	sxdelpar, h, parname
    
     INPUTS:
    	h - FITS or STSDAS header, string array
    	parname - string or string array of keyword name(s) to delete
    
     OUTPUTS:
    	h - updated FITS header, If all lines are deleted from 
    		the header, then h is returned with a value of 0
    
     EXAMPLE:
    	Delete the astrometry keywords CDn_n from a FITS header, h
    
    	IDL> sxdelpar, h, ['CD1_1','CD1_2','CD2_1','CD2_2']
    
     NOTES:
    	(1)  No message is returned if the keyword to be deleted is not found
    	(2)  All appearances of a keyword in the header will be deleted
     HISTORY:
    	version 1  D. Lindler Feb. 1987
    	Converted to new IDL  April 1990 by D. Lindler
    	Test for case where all keywords are deleted    W. Landsman Aug 1995 
    	Converted to IDL V5.0   W. Landsman   September 1997
           Allow for headers with more than 32767 lines W. Landsman Jan. 2003
    

    (See ../pfidl/astro_lib/sxdelpar.pro)


    SXPAR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
          SXPAR
     PURPOSE:
          Obtain the value of a parameter in a FITS header
    
     CALLING SEQUENCE:
          result = SXPAR( Hdr, Name, [ Abort, COUNT=, COMMENT =, /NoCONTINUE  ])   
    
     INPUTS:
          Hdr =  FITS header array, (e.g. as returned by READFITS) 
                 string array, each element should have a length of 80 characters      
    
          Name = String name of the parameter to return.   If Name is of the
                 form 'keyword*' then an array is returned containing values of
                 keywordN where N is an integer.  The value of keywordN will be
                 placed in RESULT(N-1).  The data type of RESULT will be the
                 type of the first valid match of keywordN found.
    
     OPTIONAL INPUTS:
           ABORT - string specifying that SXPAR should do a RETALL
                   if a parameter is not found.  ABORT should contain
                   a string to be printed if the keyword parameter is not found.
                   If not supplied, SXPAR will return quietly with COUNT = 0
                   (and !ERR = -1) if a keyword is not found.
    
     OPTIONAL INPUT KEYWORDS: 
           /NOCONTINUE = If set, then continuation lines will not be read, even
                     if present in the header
           /SILENT - Set this keyword to suppress warning messages about duplicate
                     keywords in the FITS header.
    
     OPTIONAL OUTPUT KEYWORDS:
           COUNT - Optional keyword to return a value equal to the number of 
                   parameters found by SXPAR, integer scalar
    
           COMMENT - Array of comments associated with the returned values
    
     OUTPUTS:
           Function value = value of parameter in header.
                   If parameter is double precision, floating, long or string,
                   the result is of that type.  Apostrophes are stripped
                   from strings.  If the parameter is logical, 1b is
                   returned for T, and 0b is returned for F.
                   If Name was of form 'keyword*' then a vector of values
                   are returned.
    
     SIDE EFFECTS:
           !ERR is set to -1 if parameter not found, 0 for a scalar
           value returned.  If a vector is returned it is set to the
           number of keyword matches found.    The use of !ERR is deprecated, and
           instead the COUNT keyword is preferred
    
           If a keyword (except HISTORY or COMMENT) occurs more than once in a 
           header, a warning is given, and the *last* occurence is used.
    
     EXAMPLES:
           Given a FITS header, h, return the values of all the NAXISi values
           into a vector.    Then place the history records into a string vector.
    
           IDL> naxisi = sxpar( h ,'NAXIS*')         ; Extract NAXISi value
           IDL> history = sxpar( h, 'HISTORY' )      ; Extract HISTORY records
    
     PROCEDURE:
           The first 8 chacters of each element of Hdr are searched for a 
           match to Name.  The value from the last 20 characters is returned.  
           An error occurs if there is no parameter with the given name.
    
           If a numeric value has no decimal point it is returned as type
           LONG.   If it contains more than 8 numerals, or contains the 
           characters 'D' or 'E', then it is returned as type DOUBLE.  Otherwise
           it is returned as type FLOAT.    Very large integer values, outside
           the range of valid LONG, are returned as DOUBLE.
    
           If the value is too long for one line, it may be continued on to the
           the next input card, using the OGIP CONTINUE convention.  For more info,
           http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.html
    
           Complex numbers are recognized as two numbers separated by one or more
           space characters.
    
           If a numeric value has no decimal point (or E or D) it is returned as
           type LONG.  If it contains more than 8 numerals, or contains the
           character 'D', then it is returned as type DOUBLE.  Otherwise it is
           returned as type FLOAT.    If an integer is too large to be stored as
           type LONG, then it is returned as DOUBLE.
    
     NOTES:
           The functions SXPAR() and FXPAR() are nearly identical, although
           FXPAR() has slightly more sophisticated parsing.   There is no
           particular reason for having two nearly identical procedures, but
           both are too widely used to drop either one.
    
     PROCEDURES CALLED:
           GETTOK(), VALID_NUM()
     MODIFICATION HISTORY:
           DMS, May, 1983, STPAR Written.
           D. Lindler Jan 90 added ABORT input parameter
           J. Isensee Jul,90 added COUNT keyword
           W. Thompson, Feb. 1992, added support for FITS complex values.
           W. Thompson, May 1992, corrected problem with HISTORY/COMMENT/blank
                   keywords, and complex value error correction.
           W. Landsman, November 1994, fix case where NAME is an empty string 
           W. Landsman, March 1995,  Added COMMENT keyword, ability to read
                   values longer than 20 character
           W. Landsman, July 1995, Removed /NOZERO from MAKE_ARRAY call
           T. Beck May 1998, Return logical as type BYTE
           W. Landsman May 1998, Make sure integer values are within range of LONG
           Converted to IDL V5.0, May 1998
           W. Landsman Feb 1998, Recognize CONTINUE convention 
           W. Landsman Oct 1999, Recognize numbers such as 1E-10 as floating point
           W. Landsman Jan 2000, Only accept integer N values when name = keywordN
           W. Landsman Dec 2001, Optional /SILENT keyword to suppress warnings
           W. Landsman/D. Finkbeiner  Mar 2002  Make sure extracted vectors 
                 of mixed data type are returned with the highest type.
    

    (See ../pfidl/astro_lib/sxpar.pro)


    TEXTCLOSE

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	TEXTCLOSE                   
    
     PURPOSE:
    	Close a text outpu file previously opened with TEXTOPEN 
     EXPLANATION:
    	procedure to close file for text output as specifed
    	by the (non-standard) system variable !TEXTOUT. 
    
     CALLING SEQUENCE:
    	textclose, [ TEXTOUT = ]
    
     KEYWORDS:
    	textout - Indicates output device that was used by
    		TEXTOPEN
    
     SIDE EFFECTS:
    	if !textout is not equal to 5 and the textunit is
    	opened.   Then unit !textunit is closed and released
    
     HISTORY:
    	D. Lindler  Dec. 1986  (Replaces PRTOPEN)
    	Test if TEXTOUT is a scalar string   W. Landsman   August 1993
     Can't close unit -1 (Standard Output) I. Freedman  April  1994
    	Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/textclose.pro)


    TEXTOPEN

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           TEXTOPEN
     PURPOSE:
           Open a device specified by TEXTOUT with unit !TEXTUNIT 
     EXPLANATION:
           Procedure to open file for text output.   The type of output 
           device (disk file or terminal screen) is specified by the 
           TEXTOUT keyword or the (nonstandard) system variable !TEXTOUT.
    
     CALLING SEQUENCE:
           textopen, program, [ TEXTOUT =, /STDOUT, /SILENT, MORE_SET= ]
    
     INPUTS:
           program - scalar string giving name of program calling textopen
    
     OPTIONAL INPUT KEYWORDS:
           TEXTOUT - Integer scalar (0-7) specifying output file/device to be 
                   opened (see below) or scalar string giving name of output file.
                   If TEXTOUT is not supplied, then the (non-standard) system 
                   variable !TEXTOUT is used.
           /SILENT - By default, TEXTOPEN prints an informational message when
                    opening a file for hardcopy output.   Set /SILENT (or !QUIET)
                    to suppress this message.
           /STDOUT - if this keyword is set and non-zero, then the standard output
                   (unit = -1) is used for TEXTOUT=1 or TEXTOUT=2.   The use
                   of STDOUT has  2 possible advantages:
                   (1) the output will appear in a journal file
                   (2) Many Unix machines print spurious control characters when
                   printing to /dev/tty.   These characters are eliminated by 
                   setting /STDOUT
    
                   The disadvantage of /STDOUT is that the /MORE option is not
                   available.
    
     OPTIONAL OUTPUT KEYWORD:
           MORE_SET - Returns 1 if the output unit was opened with /MORE.   This
                   occurs if (1) TEXTOUT = 1 and (2) the device is a tty, and 
                   (3) /STDOUT is not set.      User can use the returned value
                    of MORE_SET to determine whether to end output when user
                    presses 'Q'.
     SIDE EFFECTS:
           The following dev/file is opened for output.    Different effects
           occur depending whether the standard output is a GUI (Macintosh,
           Windows, Unix/IDLTool) or a TTY
    
                   textout=0       Nowhere
                   textout=1       if a TTY then TERMINAL using /more option
                                       otherwise standard (Unit=-1) output
                   textout=2       if a TTY then TERMINAL without /more option
                                       otherwise standard (Unit=-1) output
                   textout=3       .prt
                   textout=4       laser.tmp
                   textout=5      user must open file
                   textout=7      same as 3 but text is appended to .prt
                                   file if it already exists.
                   textout = filename (default extension of .prt)
    
           The unit to be opened is obtained with the procedure GET_LUN
           unless !TEXTOUT=5.  The unit number is placed in system variable 
           !TEXTUNIT.  For !TEXTOUT=5 the user must set !TEXTUNIT to the 
           appropriate unit number.
    
     NOTES:
           When printing to a TTY terminal, the output will *not* appear in an 
           IDL JOURNAL session, unlike text printed with the PRINT command.
    
     NON-STANDARD SYSTEM VARIABLES:
           TEXTOPEN will automatically define the following system variables if
           they are not previously defined:
    
           DEFSYSV,'!TEXTOUT',1
           DEFSYSV,'!TEXTUNIT',0
     HISTORY:
           D. Lindler  Dec. 1986  
           Keyword textout added, J. Isensee, July, 1990
           Made transportable, D. Neill, April, 1991
           Trim input PROGRAM string W. Landsman  Feb 1993
           Don't modify TEXTOUT value   W. Landsman   Aug 1993
           Modified for MacOS  I. Freedman April 1994
           Modified for output terminals without a TTY  W. Landsman  August 1995
           Added /STDOUT keyword   W. Landsman    April 1996
           added textout=7 option, D. Lindler, July, 1996
           Converted to IDL V5.0   W. Landsman   September 1997
           Exit with RETURN instead of RETALL  W. Landsman  June 1999
           In IDL V5.4 filepath(/TERMINAL) not allowed in the IDLDE WL August 2001
           Added MORE_SET output keyword   W.Landsman   January 2002
           Added /SILENT keyword  W. Landsman  June 2002  
    	Define !TEXTOUT and !TEXTUNIT if needed.  R. Sterner, 2002 Aug 27
           Return Calling Sequence if no parameters supplied W.Landsman Nov 2002
    

    (See ../pfidl/astro_lib/textopen.pro)


    T_GETPSF

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           T_GETPSF
     PURPOSE:
           Driver procedure (for GETPSF) to generate a PSF from isolate stars.
     EXPLANATION:
           Generates a point-spread function from one or more isolated stars.
           List of stars is read from the FITS ASCII table output of T_APER.
           PSF is represented as a sum of a Gaussian plus residuals.
           Ouput residuals are written to a FITS image file.
    
     CALLING SEQUENCE:
           T_GETPSF, image, fitsfile, [ idpsf, psfrad, fitrad, psfname, 
                                           /DEBUG, NEWTABLE =]
    
     INPUTS:
           IMAGE - image array
           FITSFILE  - scalar string giving name of disk FITS ASCII table.  Must 
                   contain the keywords 'X','Y' (from T_FIND) and 'AP1_MAG','SKY'
                   (from T_APER).
    
     OPTIONAL INPUTS:
           IDPSF - vector of stellar ID indices indicating which stars are to be 
                   used to create the PSF.    Not that the PSF star should be 
                   specified *not* by its STAR_ID value, but rather by the its 
                   row number (starting with 0) in the FITS table
           PSFRAD - the radius for which the PSF will be defined
           FITRAD - fitting radius, always smaller than PSFRAD
           PSFNAME - name of FITS image file to contain PSF residuals,
                   scalar string
           GETPSF will prompt for all the above values if not supplied.
    
     OPTIONAL KEYWORD INPUT
           NEWTABLE - scalar string specifying the name of the output FITS ASCII
                   table.   If not supplied, then the input table is updated with
                   the keyword PSF_CODE, specifying which stars were used for the
                   PSF.
           DEBUG - if this keyword is set and non-zero, then the result of each
                   fitting iteration will be displayed.
    
     PROMPTS:
           T_GETPSF will prompt for the readout noise (in data numbers), and
           the gain (in photons or electrons per data number) so that pixels can
           be weighted during the PSF fit.   To avoid the prompt, add the 
           keywords RONOIS and PHPADU to the FITS ASCII table header.     
    
     PROCEDURES USED:
           FTADDCOL, FTGET(), FTPUT, GETPSF, READFITS(), SXADDHIST, SXADDPAR, 
           SXPAR(), WRITEFITS, ZPARCHECK
     REVISION HISTORY:
           Written  W. Landsman     STX           May, 1988
           Update PSF_CODE to indicate PSF stars in order used, W. Landsman Mar 96
           I/O to FITS ASCII disk files  W. Landsman    May 96
           Converted to IDL V5.0   W. Landsman   September 1997
           Update for new FTINFO call   W. Landsman   May 2000
    

    (See ../pfidl/astro_lib/t_getpsf.pro)


    VALID_NUM

    [Previous Routine] [Next Routine] [List of Routines]
     NAME: 
         VALID_NUM
     PURPOSE:               
         Check if a string is a valid number representation.
     EXPLANATION:              
         The input string is parsed for characters that may possibly
         form a valid number.  It is more robust than simply checking
         for an IDL conversion error because that allows strings such
         as '22.3qwert' to be returned as the valid number 22.3
         See also the original NUM_CHK which returns the status in 
         the opposite sense.
    
     CALLING SEQUENCE: 
         IDL> status = valid_num(string  [,value]  [,/integer])
        
     Inputs      : string  -  the string to be tested
                   
     Opt. Inputs : None
                   
     Outputs     : The function returns 1 for valid, 0 for invalid number
                   
     Opt. Outputs: value	- The value the string decodes to.  This will be
    			  returned as a double precision number unless /INTEGER
    			  is present, in which case a long integer is returned.
                   
     Keywords    : Integer   -  if present code checks specifically for an integer.
    
     Calls       : None
                   
     Restrictions: None
                   
     Category    : Utilities, Numerical
                   
     Prev. Hist. : Small changes from NUM_CHK by Andrew Bowen, 
                                                 Tessella Support Services, 8/3/93
    
     Written     : CDS version by C D Pike, RAL, 24-May-93
                   
     Modified    : Version 1, C D Pike, RAL, 24-May-93
    		Version 2, William Thompson, GSFC, 14 October 1994
    			Added optional output parameter VALUE to allow
    			VALID_NUM to replace STRNUMBER in FITS routines.
    
     Version     : Version 1  24-May-93
    	Converted to IDL V5.0   W. Landsman   September 1997
    

    (See ../pfidl/astro_lib/valid_num.pro)


    WRITEFITS

    [Previous Routine] [List of Routines]
     NAME:
           WRITEFITS
     PURPOSE:
           Write IDL array and header variables to a disk FITS file.    
    
     EXPLANATION:
           A minimal FITS header is created if not supplied.
           WRITEFITS works for all types of FITS files except random groups
    
     CALLING SEQUENCE:
           WRITEFITS, filename, data [, header, /APPEND, /CHECKSUM] 
    
     INPUTS:
           FILENAME = String containing the name of the file to be written.
    
           DATA = Image array to be written to FITS file.    If DATA is 
                  undefined or a scalar, then only the FITS header (which
                  must have NAXIS = 0) will be written to disk
    
     OPTIONAL INPUT:
           HEADER = String array containing the header for the FITS file.
                    If the variable HEADER is not supplied, the program will 
                    generate a minimal FITS header.
    
     OPTIONAL INPUT KEYWORD:
           /APPEND - If this keyword is set then the supplied header and data
                    array are assumed to be an extension and are appended onto
                    the end of an existing FITS file.    If the file does not 
                    exist, then WRITEFITS will create one with a minimal primary
                    header (and /EXTEND keyword) and then append the supplied
                    extension header and array.     Note that the primary
                    header in an existing file must already have an EXTEND
                    keyword to indicate the presence of an FITS extension.
          /Checksum - If set, then the CHECKSUM keywords to monitor data integrity
                     will be included in the FITS header.    For more info, see
                      http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html
           NaNvalue - Value in the data array which represents missing pixels.
    		 This keyword is only used when missing pixels are not
    		 represented by NaN values in the input array.
     OUTPUTS:
           None
    
     RESTRICTIONS:
           (1) It recommended that BSCALE and BZERO not be used (or set equal
               to 1. and 0) with REAL*4 or REAL*8 data.
           (2) WRITEFITS will remove any group parameters from the FITS header
    
     EXAMPLE:
           Write a randomn 50 x 50 array as a FITS file creating a minimal header.
    
           IDL> im = randomn(seed, 50, 50)        ;Create array
           IDL> writefits, 'test', im             ;Write to a FITS file "test"
    
     PROCEDURES USED:
           CHECK_FITS, FITS_ADD_CHECKSUM, MKHDR, MRD_HREAD, SXDELPAR, SXADDPAR, 
           SXPAR()
    
     MODIFICATION HISTORY:
           WRITTEN, Jim Wofford, January, 29 1989
           MODIFIED, Wayne Landsman, added BITPIX = -32,-64 support for UNIX
           Use new BYTEODER keywords 22-Feb-92
           Modify OPENW for V3.0.0   W. Landsman       Dec 92
           Work for "windows"   R. Isaacman            Jan 93
           More checks for null data                   Mar 94
           Work for Linux  W. Landsman                 Sep 95
           Added call to IS_IEEE_BIG()  W. Landsman  Apr 96
           Make sure SIMPLE is written in first line of header  W. Landsman Jun 97
           Use SYSTIME() instead of !STIME    W. Landsman  July 97
           Create a default image extension header if needed W. Landsman June 98
           Converted to IDL V5.0   W. Landsman         June 98
           Write unsigned data types W. Landsman       December 1999
           Correct BZERO value for unsigned data  W. Landsman   July 2000
           Assume at least V5.1 remove NANValue keyword W. Landsman July 2001
           Use FILE_SEARCH for V5.5 or later     W. Landsman    April 2002
           Create the file if not already present and /APPEND is set
                                                 W. Landsman    September 2002
           Fix MRD_HREAD call if /APPEND is set  W. Landsman    December 2002
           Added /CHECKSUM keyword              W. Landsman     December 2002
    	Restored NANvalue keyword, William Thompson,	     October 2003
    

    (See ../pfidl/astro_lib/writefits.pro)