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


  >  Docs Center  >  Libraries  >  ASTROLIB  >  MWRFITS

MWRFITS

MWRFITS

Name


      MWRFITS

Purpose


      Write all standard FITS data types from input arrays or structures.

Explanation


      Must be used with a post-September 2009 version of FXADDPAR.

Calling Sequence


      MWRFITS, Input, Filename, [Header],
                      /LSCALE , /ISCALE, /BSCALE,
                      /USE_COLNUM, /Silent, /Create, /No_comment, /Version, $
                      Alias=, /ASCII, Separator=, Terminator=, Null=,
                      /Logical_cols, /Bit_cols, /Nbit_cols,
                      Group=, Pscale=, Pzero=, Status=

Inputs


      Input = Array or structure to be written to FITS file.
              -When writing FITS primary data or image extensions
                input should be an array.
              --If data is to be grouped
                the Group keyword should be specified to point to
                a two dimensional array. The first dimension of the
                Group array will be PCOUNT while the second dimension
                should be the same as the last dimension of Input.
              --If Input is undefined, then a dummy primary dataset
                or Image extension is created [This might be done, e.g.,
                to put appropriate keywords in a dummy primary
                HDU].
              -When writing an ASCII table extension, Input should
                be a structure array where no element of the structure
                is a structure or array (except see below).
              --A byte array will be written as A field. No checking
                is done to ensure that the values in the byte field
                are valid ASCII.
              --Complex numbers are written to two columns with '_R' and
                '_I' appended to the TTYPE fields (if present). The
                complex number is enclosed in square brackets in the output.
              --Strings are written to fields with the length adjusted
                to accommodate the largest string. Shorter strings are
                blank padded to the right.
              -When writing a binary table extension, the input should
                be a structure array with no element of the structure
                being a substructure.
              If a structure is specified on input and the output
              file does not exist or the /CREATE keyword is specified
              a dummy primary HDU is created.
      Filename = String containing the name of the file to be written.
                By default MWRFITS appends a new extension to existing
                files which are assumed to be valid FITS. The /CREATE
                keyword can be used to ensure that a new FITS file
                is created even if the file already exists.

Outputs


Optional Inputs


      Header = Header should be a string array. Each element of the
                array is added as a row in the FITS header. No
                parsing is done of this data. MWRFITS will prepend
                required structural (and, if specified, scaling)
                keywords before the rows specified in Header.
                Rows describing columns in the table will be appended
                to the contents of Header.
                Header lines will be extended or truncated to
                80 characters as necessary.
                If Header is specified then on return Header will have
                the header generated for the specified extension.

Optional Input Keywords


      ALias= Set up aliases to convert from the IDL structure
                to the FITS column name. The value should be
                a STRARR(2,*) value where the first element of
                each pair of values corresponds to a column
                in the structure and the second is the name
                to be used in the FITS file.
                The order of the alias keyword is compatible with
                use in MRDFITS.
      ASCII - Creates an ASCII table rather than a binary table.
                This keyword may be specified as:
                /ASCII - Use default formats for columns.
                ASCII='format_string' allows the user to specify
                  the format of various data types such using the following
                  syntax 'column_type:format, column_type:format'. E.g.,
                ASCII='A:A1,I:I6,L:I10,B:I4,F:G15.9,D:G23.17,C:G15.9,M:G23.17'
                gives the default formats used for each type. The TFORM
                fields for the real and complex types indicate will use corresponding
                E and D formats when a G format is specified.
                Note that the length of the field for ASCII strings and
                byte arrays is automatically determined for each column.
      BIT_COLS= An array of indices of the bit columns. The data should
                comprise a byte array with the appropriate dimensions.
                If the number of bits per row (see NBIT_COLS)
                is greater than 8, then the first dimension of the array
                should match the number of input bytes per row.
      BSCALE Scale floats, longs, or shorts to unsigned bytes (see LSCALE)
      /CREATE If this keyword is non-zero, then a new FITS file will
                be created regardless of whether the file currently
                exists. Otherwise when the file already exists,
                a FITS extension will be appended to the existing file
                which is assumed to be a valid FITS file.
      GROUP= This keyword indicates that GROUPed FITS data is to
                be generated.
                Group should be a 2-D array of the appropriate output type.
                The first dimension will set the number of group parameters.
                The second dimension must agree with the last dimension
                of the Input array.
      ISCALE Scale floats or longs to short integer (see LSCALE)
      LOGICAL_COLS= An array of indices of the logical column numbers.
                These should start with the first column having index *1*.
                The structure element should either be an array of characters
                with the values 'T' or 'F', or an array of bytes having the
                values byte('T')=84b, byte('F')=70b or 0b. The use of bytes
                allows the specification of undefined values (0b).
      LSCALE Scale floating point numbers to long integers.
                This keyword may be specified in three ways.
                /LSCALE (or LSCALE=1) asks for scaling to be automatically
                determined. LSCALE=value divides the input by value.
                I.e., BSCALE=value, BZERO=0. Numbers out of range are
                given the value of NULL if specified, otherwise they are given
                the appropriate extremum value. LSCALE=(value,value)
                uses the first value as BSCALE and the second as BZERO
                (or TSCALE and TZERO for tables).
      NBIT_COLS= The number of bits actually used in the bit array.
                This argument must point to an array of the same dimension
                as BIT_COLS.
      /NO_COPY = By default, MWRFITS makes a copy of the input variable
                before any modifications necessary to write it to a FITS
                file. If you have a large array/structure, and don't
                require it for subsequent processing, then /NO_COPY will
                save memory.
      NO_TYPES If the NO_TYPES keyword is specified, then no TTYPE
                keywords will be created for ASCII and BINARY tables.
      No_comment Do not write comment keywords in the header
      NULL= Value to be written for integers/strings which are
                undefined or unwritable.
      PSCALE= An array giving scaling parameters for the group keywords.
                It should have the same dimension as the first dimension
                of Group.
      PZERO= An array giving offset parameters for the group keywords.
                It should have the same dimension as the first dimension
                of Group.
      Separator= This keyword can be specified as a string which will
                be used to separate fields in ASCII tables. By default
                fields are separated by a blank.
      /SILENT Suppress informative messages. Errors will still
                be reported.
      Terminator= This keyword can be specified to provide a string which
                will be placed at the end of each row of an ASCII table.
                No terminator is used when not specified.
                If a non-string terminator is specified (including
                when the /terminator form is used), a new line terminator
                is appended.
      USE_COLNUM When creating column names for binary and ASCII tables
                MWRFITS attempts to use structure field name
                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 version number of MWRFITS.

Optional Output Keyword


      Status - 0 if FITS file is successfully written, -1 if there is a
                a problem (e.g. nonexistent directory, or no write permission)

Example


      Write a simple array:
            a=fltarr(20,20)
            mwrfits,a,'test.fits'
      Append a 3 column, 2 row, binary table extension to file just created.
            a={name:'M31', coords:(30., 20.), distance:2}
            a=replicate(a, 2);
            mwrfits,a,'test.fits'
      Now add on an image extension:
            a=lonarr(10,10,10)
            hdr=("COMMENT This is a comment line to put in the header", $
                "MYKEY = "Some desired keyword value")
            mwrfits,a,'test.fits',hdr

Restrictions


      (1) Variable length columns are not supported for anything
              other than simple types (byte, int, long, float, double).
      (2) Empty strings are converted to 1 element blank strings (because
              IDL refuses to write an empty string (0b) from a structure)

Notes


      This multiple format FITS writer is designed to provide a
      single, simple interface to writing all common types of FITS data.
      Given the number of options within the program and the
      variety of IDL systems available it is likely that a number
      of bugs are yet to be uncovered.

Procedures Used


      FXPAR(), FXADDPAR

Modification History


      Version 0.9: By T. McGlynn 1997-07-23
              Initial beta release.
      Dec 1, 1997, Lindler, Modified to work under VMS.
      Version 0.91: T. McGlynn 1998-03-09
              Fixed problem in handling null primary arrays.
      Version 0.92: T. McGlynn 1998-09-09
              Add no_comment flag and keep user comments on fields.
              Fix handling of bit fields.
      Version 0.93: T. McGlynn 1999-03-10
              Fix table appends on VMS.
      Version 0.93a W. Landsman/D. Schlegel
              Update keyword values in chk_and_upd if data type has changed
      Version 0.94: T. McGlynn 2000-02-02
              Efficient processing of ASCII tables.
              Use G rather than E formats as defaults for ASCII tables
                and make the default precision long enough that transformations
                binary to/from ASCII are invertible.
              Some loop indices made long.
              Fixed some ends to match block beginnings.
      Version 0.95: T. McGlynn 2000-11-06
              Several fixes to scaling. Thanks to David Sahnow for
              documenting the problems.
              Added PCOUNT,GCOUNT keywords to Image extensions.
              Version numbers shown in SIMPLE/XTENSION comments
      Version 0.96: T. McGlynn 2001-04-06
              Changed how files are opened to handle ~ consistently
      Version 1.0: T. McGlynn 2001-12-04
              Unsigned integers,
              64 bit integers.
              Aliases
              Variable length arrays
              Some code cleanup
      Version 1.1: T. McGlynn 2002-2-18
              Fixed major bug in processing of unsigned integers.
              (Thanks to Stephane Beland)
      Version 1.2: Stephane Beland 2003-03-17
              Fixed problem in creating dummy dataset when passing undefined
              data, caused by an update to FXADDPAR routine.
      Version 1.2.1 Stephane Beland 2003-09-10
              Exit gracefully if write privileges unavailable
      Version 1.3 Wayne Landsman 2003-10-24
              Don't use EXECUTE() statement if on a virtual machine
      Version 1.3a Wayne Landsman 2004-5-21
              Fix for variable type arrays
      Version 1.4 Wayne Landsman 2004-07-16
              Use STRUCT_ASSIGN when modifying structure with pointer tags
      Version 1.4a Wayne Landsman 2005-01-03
              Fix writing of empty strings in binary tables
      Version 1.4b Wayne Landsman 2006-02-23
              Propagate /SILENT keyword to mwr_tablehdr
      Version 1.5 Wayne Landsman 2006-05-24
              Open file using /SWAP_IF_LITTLE_ENDIAN keyword
              Convert empty strings to 1 element blank strings before writing
      Version 1.5a Wayne Landsman 2006-06-29
              Fix problem introduced 2006-05-24 with multidimensional strings
      Version 1.5b K. Tolbert 2006-06-29
              Make V1.5a fix work pre-V6.0
      Version 1.5c I.Evans/W.Landsman 2006-08-08
              Allow logical columns to be specified as bytes
      Version 1,5d K. Tolbert 2006-08-11
              Make V1.5a fix work for scalar empty string
      Version 1.6 W. Landsman 2006-09-22
              Assume since V5.5, remove VMS support
      Version 1.6a W. Landsman 2006-09-22
              Don't right-justify strings
      Version 1.7 W. Landsman 2009-01-12
              Added STATUS output keyword
      Version 1.7a W. Landsman 2009-04-10
              Since V6.4 strings are no longer limited to 1024
              elements
      Version 1.8 Pierre Chanial 2009-06-23
              trim alias, implement logical TFORM 'L', don't
              add space after tform key.
      Version 1.9 W. Landsman 2009-07-20
              Suppress compilation messages of supporting routines
      Version 1.10 W. Landsman 2009-09-30
              Allow TTYPE values of 'T' and 'F', fix USE_COLNUM for bin tables
      Version 1.11 W. Landsman 2010-11-18
              Allow LONG64 number of bytes, use V6.0 notation
      Version 1.11a W. Landsman 2012-08-12
              Better documentation, error checking for logical columns
      Version 1.11b M. Haffner/W.L. 2012-10-12
              Added /No_COPY keyword, fix problem with 32 bit overflow
      Version 1.12 W. Landsman 2014-04-23
      Version 1.12a W.Landsman/M. Fossati 2014-10-14
              Fix LONG overflow for very large files



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