MRDFITS

     Read all standard FITS data types into arrays or structures.

      Further information on MRDFITS is available at
      http://idlastro.gsfc.nasa.gov/mrdfits.html

      Result = MRDFITS( Filename/FileUnit,[Extension, Header],
                       /FSCALE , /DSCALE , /UNSIGNED,
                       ALIAS=strarr[2,n], /USE_COLNUM,
                       /NO_TDIM, ROWS = [a,b,...], $
                       /POINTER_VAR, /FIXED_VAR,
                       RANGE=[a,b], COLUMNS=[a,b,...]), ERROR_ACTION=x,
                       COMPRESS=comp_prog, STATUS=status, /VERSION )

      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.

      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.  Spaces and invalid characters are replaced by
               underscores, and other invalid tag names are converted using
               the IDL_VALIDNAME(/CONVERT_ALL) function.
               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.

       Header = String array containing the header from the FITS extension.

       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 for 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.
       /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)
                Note that because pointers may be present in the output
                structure, the user is responsible for memory management
                when deleting or reassigning the structure (e.g. use HEAP_FREE
                first).
       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].
       ROWS -  A scalar or vector specifying a  specific row or rows to read
               (first row is 0).   For example to read rows 0,
               12 and 23 only, set ROWS=[0,12,23].   Valid for images, ASCII
               and binary tables, but not GROUPed data.   For images
               the row numbers refer to the last non-unity index in the array.
               Cannot be used at the same time as the RANGE keyword
       /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.
       /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

       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

       (1) Read a FITS primary array:
               a = mrdfits('TEST.FITS')    or
               a = mrdfits('TEST.FITS', 0, header)
       The second example also retrieves header information.
       (2) Read rows 10-100 of the second extension of a FITS file.
               a = mrdfits('TEST.FITS', 2, header, range=[10,100])
       (3) 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)
       (4) Read rows 3, 34 and 52 of a binary table and request that
           variable length columns be stored as a pointer variable in the
           output structure
              a = mrdfits('TEST.FITS',1,rows=[3,34,52],/POINTER)

       (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.

       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.

       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

       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)
       V2.7 July, 2003  Added Rows keyword (W. Landsman)
       V2.7a September  2003 Convert dimensions to long64 to handle huge files
       V2.8 October 2003 Use IDL_VALIDNAME() function to ensure valid tag names
                         Removed OLD_STRUCT and TEMPDIR keywords W. Landsman
       V2.9 February 2004 Added internal MRD_FXPAR procedure for faster
                     processing of binary table headers E. Sheldon
       V2.9a March 2004 Restore ability to read empty binary table W. Landsman
             Swallow binary tables with more columns than given in TFIELDS
       V2.9b Fix to ensure order of TFORMn doesn't matter
       V2.9c Check if extra degenerate NAXISn keyword are present W.L. Oct 2004
       V2.9d Propagate /SILENT to MRD_HREAD, more LONG64 casting W. L. Dec 2004
       V2.9e Add typarr[good] to fix a problem reading zero-length columns
             A.Csillaghy, csillag@ssl.berkeley.edu (RHESSI)
       V2.9f Fix problem with string variable binary tables, possible math
             overflow on non-IEEE machines  WL Feb. 2005
       V2.9g Fix problem when setting /USE_COLNUM   WL Feb. 2005

[Home Page] [Software, Documentation] [IDL Documentation] [Quick Reference] [Feedback]