Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


  >  Docs Center  >  Libraries  >  ASTROLIB  >  FITS_OPEN

FITS_OPEN

FITS_OPEN

Name


      FITS_OPEN

Purpose


      Opens a FITS (Flexible Image Transport System) data file.

Explanation


      Used by FITS_READ and FITS_WRITE

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) files or Unix
                  compressed files *for reading only*, although there is a
                  performance penalty. FPACK (
                  http://heasarc.gsfc.nasa.gov/fitsio/fpack/ )
                  compressed FITS files can be read provided that the FPACK
                  software is installed.

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.
      /FPACK - Signal that the file is compressed with the FPACK software.
              http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) By default,
              FITS_OPEN assumes that if the file name extension ends in
              .fz that it is fpack compressed. The FPACK software must
              be installed on the system
      /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
              .FCOMPRESS - 1 if unit is a FPACK compressed file opened with
                    a pipe to SPAWN
              .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


      GET_PIPE_FILESIZE (for Fcompress'ed files) 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
      Use post-V6.0 notation W.L. October 2010
      Support FPACK compressed files, new .FCOMPRESS tag to FCB structure
              W.L. December 2010
      Read gzip'ed files even if gzip is not installed W.L. October 2012
      Handle axis sizes requiring 64 integer W.L. April 2014
      Support for .Z compressed files M. Zechmeister/W.L. April 2014
      Wrap filenames in "" when spawning subprocesses, to handle paths
      with spaces or other atypical characters. M. Perrin Nov 2014



© 2018 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us