; data = fread(fn, iRow)
; or
; id = fopen(fn)
; data = fread(id, iRow)
; fclose, id
;
; Read a row of a FITS file
;
; Input Keywords
;
; iColRange: column range, def: [0, nCol-1]
; nRows: specify the number of rows to read, def: 1
; used only if read all the columns
;
; useComplex: flag, if set will return a complex array instead of
; a float array (mapping float(0,1) -> real,imag)
;
; littleEndian: see fopen()
;
; ---------------------------------------------------------------------------
; <- Last updated: Sun Feb 3 18:25:55 2013 -> SGK
; 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 intepreted 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:
; HDR - 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).
;
; RESTRICTIONS:
; (1) MKHDR should not be used to make an STSDAS header or a FITS
; ASCII or Binary Table header. Instead use
;
; SXHMAKE - to create a minimal STSDAS header
; FXHMAKE - 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
; NAME:
; READFITS
; PURPOSE:
; Read a FITS file into IDL data and header variables.
; EXPLANATION:
; Under Unix, READFITS() can also read gzip or Unix compressed FITS files.
;
; CALLING SEQUENCE:
; Result = READFITS( Filename,[ Header, heap, /NOSCALE, EXTEN_NO=,
; NSLICE=, /VERBOSE , NaNVALUE =, STARTROW =, NUMROW = ] )
;
; 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.
;
; 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.
; heap = For extensions, the optional heap area following the main
; data array (e.g. for variable length binary extensions).
;
; OPTIONAL INPUT KEYWORDS:
;
; EXTEN_NO - scalar integer specify the FITS extension to read. For
; example, specify EXTEN = 1 or /EXTEN to read the first
; FITS extension. Extensions are read using recursive
; calls to READFITS.
;
; NaNVALUE - This scalar is only needed on architectures (such as VMS
; prior to IDL V5.1) that do not recognize the IEEE "not a number"
; (NaN) convention. It specifies the value to translate any IEEE
; NAN values in the FITS data array. In addition, if the data is
; stored as integer (BITPIX = 16 or 32), and BSCALE is present,
; then NaNValue gives the values to pixels assigned with the
; BLANK keyword.
;
; 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.
;
; NSLICE - An 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 - This keyword only applies when reading a FITS extension.
; If specifies the number of rows (scalar integer) of the
; extension table to read. Useful when one does not want to
; read the entire 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.
;
; /VERBOSE - if set, READFITS will display the size the array at the
; terminal.
;
; STARTROW - This keyword only applies when reading a FITS extension
; It specifies the row (scalar integer) of the extension table at
; which to begin reading. Useful when one does not want to read
; the entire table.
;
; /NOIMAGE - reads only the header, return -1
;
; 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 contain 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)
; IDL> tab = READFITS('test.fits.fz', h, exten_no = X)
;
; 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 (if /VERBOSE 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 scaled to NaN (or the value of the NaNValue
; keyword) after the scaling to floating point.
;
; (2) The procedure FXREAD can be used as an alternative to READFITS.
; FXREAD has the option of reading an arbitary subsection of the
; primary FITS data.
;
; (3) The use of the NSLICE keyword is incompatible with the NUMROW
; or STARTROW keywords.
;
; PROCEDURES USED:
; Functions: SXPAR(), WHERENAN()
; Procedures: FDECOMP, IEEE_TO_HOST, SXADDPAR, SXDELPAR
;
; USES ALSO:
; zcat and unfpack for reading compressed files;
;
; MODIFICATION HISTORY:
; MODIFIED, Wayne Landsman October, 1991
; Added call to TEMPORARY function to speed processing Feb-92
; Added STARTROW and NUMROW keywords for FITS tables Jul-92
; Work under "windows" R. Isaacman Jan-93
; Check for SIMPLE keyword in first 8 characters Feb-93
; Removed EOF function for DECNET access Aug-93
; Work under "alpha" Sep-93
; Null array processing fixed: quotes in a message
; properly nested, return added. Affected case when
; readfits called from another procedure. R.S.Hill Jul-94
; Correct size of variable length binary tables W.Landsman Dec-94
; To read in compressed files on Unix systems. J. Bloch Jan-95
; Check that file is a multiple of 2880 bytes Aug-95
; Added FINDFILE check for file existence K.Feggans Oct-95
; Consistent Error Handling W. Landsman Nov-95
; Handle gzip image extensions W. Landsman Apr-96
; Fixed bug reading 1-d data introduced Apr-96 W. Landsman Jun-96
; Don't use FINDFILE (too slow), & check for Blank values WBL Oct-96
; !VALUES wasn't compatible with IDL V3.6 WBL Jan-97
; Added ability to read Unix compressed (.Z) files WBL Jan-97
; Changed a FIX to LONG to handle very large tables WBL Apr-97
; Force use of /bin/sh shell with gzip WBL Apr-97
; Recognize BSCALE, BZERO in IMAGE extensions WBL Jun-97
; Added NSLICE keyword WBL Jul-97
; Added ability to read heap area after extensions WBL Aug-97
; Suppress *all* nonfatal messages with /VERBOSE WBL Dec-97
; Converted to IDL V5.0 WBL Dec-1997
; Fix NaN assignment for int data C. Gehman/JPL Mar-98
; Fix bug with NaNvalue = 0.0 C. Gehman/JPL Mar-98
; Replaced !ERR by !ERROR_STATE.CODE for IDL 5.1 Jan 13 1999 SGK
; Replaced /SILENT by /VERBOSE Jan 13 1999 SGK
; added support for complex*4 (bitpix=64) Jan 17 2003 SGK
; added support for rice-compressed files (.fz) -E 1 Dec 5 2013 SGK
; rice-compressed files (.fz) -E exten_no, not just -E 1 Dec 14 2016 SGK
; fznmethod=0 or 1: use funpack 2x or 1x & /tmp,
; but gets from time to time cat: write error: Broken pipe for fzmethod=1
; niomage added Jan 25 2017 SGK
; NAME:
; READFITS
; PURPOSE:
; Read a FITS file into IDL data and header variables.
; EXPLANATION:
; Under Unix, READFITS() can also read gzip or Unix compressed FITS files.
;
; CALLING SEQUENCE:
; Result = READFITS( Filename,[ Header, heap, /NOSCALE, EXTEN_NO=,
; NSLICE=, /VERBOSE , NaNVALUE =, STARTROW =, NUMROW = ] )
;
; 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.
;
; 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.
; heap = For extensions, the optional heap area following the main
; data array (e.g. for variable length binary extensions).
;
; OPTIONAL INPUT KEYWORDS:
;
; EXTEN_NO - scalar integer specify the FITS extension to read. For
; example, specify EXTEN = 1 or /EXTEN to read the first
; FITS extension. Extensions are read using recursive
; calls to READFITS.
;
; NaNVALUE - This scalar is only needed on architectures (such as VMS
; prior to IDL V5.1) that do not recognize the IEEE "not a number"
; (NaN) convention. It specifies the value to translate any IEEE
; NAN values in the FITS data array. In addition, if the data is
; stored as integer (BITPIX = 16 or 32), and BSCALE is present,
; then NaNValue gives the values to pixels assigned with the
; BLANK keyword.
;
; 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.
;
; NSLICE - An 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 - This keyword only applies when reading a FITS extension.
; If specifies the number of rows (scalar integer) of the
; extension table to read. Useful when one does not want to
; read the entire 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.
;
; /VERBOSE - if set, READFITS will display the size the array at the
; terminal.
;
; STARTROW - This keyword only applies when reading a FITS extension
; It specifies the row (scalar integer) of the extension table at
; which to begin reading. Useful when one does not want to read
; the entire table.
;
; /NOIMAGE - reads only the header, return -1
;
; 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 contain 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)
; IDL> tab = READFITS('test.fits.fz', h, exten_no = X)
;
; 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 (if /VERBOSE 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 scaled to NaN (or the value of the NaNValue
; keyword) after the scaling to floating point.
;
; (2) The procedure FXREAD can be used as an alternative to READFITS.
; FXREAD has the option of reading an arbitary subsection of the
; primary FITS data.
;
; (3) The use of the NSLICE keyword is incompatible with the NUMROW
; or STARTROW keywords.
;
; PROCEDURES USED:
; Functions: SXPAR(), WHERENAN()
; Procedures: FDECOMP, IEEE_TO_HOST, SXADDPAR, SXDELPAR
;
; USES ALSO:
; zcat and unfpack for reading compressed files;
;
; MODIFICATION HISTORY:
; MODIFIED, Wayne Landsman October, 1991
; Added call to TEMPORARY function to speed processing Feb-92
; Added STARTROW and NUMROW keywords for FITS tables Jul-92
; Work under "windows" R. Isaacman Jan-93
; Check for SIMPLE keyword in first 8 characters Feb-93
; Removed EOF function for DECNET access Aug-93
; Work under "alpha" Sep-93
; Null array processing fixed: quotes in a message
; properly nested, return added. Affected case when
; readfits called from another procedure. R.S.Hill Jul-94
; Correct size of variable length binary tables W.Landsman Dec-94
; To read in compressed files on Unix systems. J. Bloch Jan-95
; Check that file is a multiple of 2880 bytes Aug-95
; Added FINDFILE check for file existence K.Feggans Oct-95
; Consistent Error Handling W. Landsman Nov-95
; Handle gzip image extensions W. Landsman Apr-96
; Fixed bug reading 1-d data introduced Apr-96 W. Landsman Jun-96
; Don't use FINDFILE (too slow), & check for Blank values WBL Oct-96
; !VALUES wasn't compatible with IDL V3.6 WBL Jan-97
; Added ability to read Unix compressed (.Z) files WBL Jan-97
; Changed a FIX to LONG to handle very large tables WBL Apr-97
; Force use of /bin/sh shell with gzip WBL Apr-97
; Recognize BSCALE, BZERO in IMAGE extensions WBL Jun-97
; Added NSLICE keyword WBL Jul-97
; Added ability to read heap area after extensions WBL Aug-97
; Suppress *all* nonfatal messages with /VERBOSE WBL Dec-97
; Converted to IDL V5.0 WBL Dec-1997
; Fix NaN assignment for int data C. Gehman/JPL Mar-98
; Fix bug with NaNvalue = 0.0 C. Gehman/JPL Mar-98
; Replaced !ERR by !ERROR_STATE.CODE for IDL 5.1 Jan 13 1999 SGK
; Replaced /SILENT by /VERBOSE Jan 13 1999 SGK
; added support for complex*4 (bitpix=64) Jan 17 2003 SGK
; added support for rice-compressed files (.fz) -E 1 Dec 5 2013 SGK
; rice-compressed files (.fz) -E exten_no, not just -E 1 Dec 14 2016 SGK
; fznmethod=0 or 1: use funpack 2x or 1x & /tmp,
; but gets from time to time cat: write error: Broken pipe for fzmethod=1
; niomage added Jan 25 2017 SGK
; NAME:
; SXADDPAR
; PURPOSE:
; Add or modify a parameter in a FITS header array.
;
; CALLING SEQUENCE:
; sxaddpar, Header, Name, Value, [ Comment, Location,
; 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 = '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.
;
; OPTIONAL INPUT PARAMETERS:
; Comment = String field. The '/' is added by this routine. Added
; starting in position 31. If not supplied, or set equal to
; '', 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.
; /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.
; OUTPUTS:
; Header = updated FITS header array.
;
; 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
;
; 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
; NAME:
; SXPAR
; PURPOSE:
; Obtain the value of a parameter in a FITS header
;
; CALLING SEQUENCE:
; result = SXPAR( Hdr, Name, [ Abort, COUNT=, COMMENT = ])
;
; 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 with a negative
; !err if a keyword is not found.
;
; 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:
; !ERROR_STATE.CODE 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.
;
; 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
; character 'D', 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.
;
; 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(), STRNUMBER()
; 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
; 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, NaNvalue = , /APPEND]
;
; 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 variable HEADER is not given, the program will generate
; a minimal FITS header.
;
; OPTIONAL INPUT KEYWORD:
; NaNvalue - Value in the data array to be set to the IEEE NaN
; condition. This is the FITS representation of undefined
; values
; 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. Note that the primary
; header in the existing file must already have an EXTEND
; keyword to indicate the presence of an FITS extension.
;
; 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, HEADFITS(), HOST_TO_IEEE, IS_IEEE_BIG(), MKHDR, 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
; Sep 22 2005 SGKL: FINDFILE() -> FILE_SEARCH()