fits_open.pro

basic median filter simulation

pro fits_open,filename,fcb,write=write,append=append,update=update, $
                 no_abort=no_abort,message=message,hprint=hprint
;+
; NAME:
;       FITS_OPEN
;
; PURPOSE:
;       Opens a FITS (Flexible Image Transport System) data file.
;
; EXPLANATION:
;       FITS_OPEN was modified in Sep 2006 to open with /SWAP_IF_LITTLE_ENDIAN
;       It must be used with post-Sep 2006 versions of FITS_READ, FITS_WRITE
;       and MODFITS.
;
;*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*, 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
;               FITS_CLOSE and MODFITS.
;
; 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 quietly return to calling program when an I/O error  
;               is encountered, and return  a non-null string
;               (containing the error message) in the keyword MESSAGE.    
;               If /NO_ABORT not set, then FITS_OPEN will display the error 
;               message and return to the calling program.
;       /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
;       Fix gzip compress for V5.4 and earlier  W.Landsman/M.Fitzgerald Dec 2003 
;       Assume since V5.3 (STRSPLIT, OPENR,/COMPRESS) W. Landsman Feb 2004
;       Treat FTZ extension as gzip compressed W. Landsman Sep 2004
;       Assume since V5.4 fstat.compress available W. Landsman Apr 2006
;       FCB.Filename  now expands any wildcards W. Landsman July 2006
;       Make ndata 64bit for very large files B. Garwood/W. Landsman Sep 2006
;       Open with /SWAP_IF_LITTLE_ENDIAN, remove obsolete keywords to OPEN
;                W. Landsman  Sep 2006
;       Warn that one cannot open a compressed file for update W.L. April 2007
;-
;--------------------------------------------------------------------
      compile_opt idl2
; if no parameters supplied, print calling sequence
;
       if N_params() LT 1 then begin
          print,'Syntax - FITS_OPEN, filename, fcb'
          print,' Input Keywords:  /Append, /Hprint, /No_abort, /Update, /Write'
          print,' Output Keyword:  Message= '
          return
       endif
;
; set default keyword parameters
;

        message = ''
        open_for_read = 1
        open_for_update = 0
        open_for_write = 0
        open_for_overwrite = 0
        if keyword_set(write) then begin
                open_for_read = 0
                open_for_update = 0
                open_for_write = 1
                open_for_overwrite = 0
        end
        if keyword_set(append) then begin
                open_for_read = 0
                open_for_write = 0
                open_for_update = 1
                open_for_overwrite = 0
        end     
        if keyword_set(update) then begin
                open_for_read = 1 
                open_for_write = 0
                open_for_update = 0 
                open_for_overwrite = 1 
        end     
;
; on I/O errors goto statement ioerror:
;
        on_ioerror,ioerror
;
; open file
;
        docompress = 0
        len = strlen(filename)
        ext = strlowcase(strmid(filename, len-3, 3))
        docompress = (ext EQ '.gz') or (ext EQ 'ftz') 
        if docompress and open_for_overwrite then begin 
            message = 'Compressed FITS files cannot be open for update'
            if not keyword_set(no_abort) then $
                   message,' ERROR: '+message,/CON
            return
       endif   
 ;
; open file
;
        get_lun,unit
       if docompress then $
                openr,unit,filename, /compress,/swap_if_little else begin
       case 1 of
                keyword_set(append): openu,unit,filename,/swap_if_little
                keyword_set(update): openu,unit,filename,/swap_if_little
                keyword_set(write) : openw,unit,filename,/swap_if_little
                else               : openr,unit,filename,/swap_if_little
        endcase
        endelse

        file = fstat(unit)
        fname = file.name          ;In case the user input a wildcard
        docompress = file.compress

; Need to spawn to "gzip -l" to get the number of uncompressed bytes in a gzip
; compressed file.    I'm not sure how independent this code is with different
; shells and OS's.

        if docompress then begin 
             spawn,'gzip -l ' + fname, output
             output = strtrim(output,2)
             g = where(strmid(output,0,8) EQ 'compress')
             nbytes_in_file = long64((strsplit(output[g[0]+1],/extract))[1])
        endif else nbytes_in_file = file.size
;
; create vectors needed to store header information for each extension