next_inactive up previous contents
Up: XIMAGE User's Guide Previous: 8. Commands S-Z   Contents

Subsections

9. Data formats

9.1 Input

Input

XIMAGE accepts two type of FITS file as input : an image or an event file. It also seven different types of files containing image, spectral and timing data. These files can all be read in by command read_image

9.1.1 FITS

FITS - FITS image and event files

A FITS image is an array stored in the primary array or an image extension. By default XIMAGE reads the first array in the primary header.

An event file is a FITS binary table where each row describes quantities associated with an event. These typically are coordinates in detector or sky, energy channels, and time. An event file can be read within XIMAGE provided that at least two columns exist, representing x and y for an image.

9.1.2 EXOSAT

EXOSAT - EXOSAT image files

These are simply integer*2 binary files with record length equal to the number of image pixels in the X dimension. The image header takes 64 bytes and is stored in the first record of the file if the record length is greater or equal to 64,bytes or in as many initial records as necessary if the record length is less than 64 bytes. As many data records as the number of pixels in the Y direction follow.

9.2 Output

Output

9.2.1 EXOSAT Images

EXOSAT Images

EXOSAT image files (.IMG) are produced by command write/exo filename. These binary files are operating system dependent (so don't ftp them!).

9.2.2 FITS image

FITS Images

A FITS image file (.FITS) is produced by the command write/fits filename. These files are operating system independent.

9.3 Ximage-Specific Files

9.3.1 Color Table

Color tables are text files (usually ending with .tab) where each line defines a color which has a Red value of the first row, a Green value of the second row and a Blue value of the third row. RGB values can range from 0.0 to 1.0

For example, this table goes from black to white. XIMAGE will calculate intermediate colors to fill in the necessary number of colors, which depends on the number of levels set.

      CCT [color table]          - Loads existing color table
      CCT/OUTFILE=[color table]  - Writes out color table

    !
    !  Black to white color table
    !
    0. 0. 0.
    1. 1. 1.

9.3.2 Levels

XIMAGE levels files contain a level value on each line. For example, the following levels file contains 16 levels.

      LEVELS/LOAD [levels file]  - Loads levels file
      LEVELS/SAVE [levels file]  - Writes out levels file

    !
    !  Calculated levels
    !  Total number: 16
    !
    0
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    13
    15
    18
    49

9.3.3 Viewport Configuration

Viewport configuration files (usually ending with .vpc) contain a line for each viewport. A viewport is defined by four columns, v1=left edge, v2=right edge, v3=bottom edge, and v4=top edge. Viewport coordinate number the device from 0.0 to 1.0 from left to right and 0.0 to 1.0 from bottom to top.

      VIEWPORT [configuration file]  - Loads vpc file

    !
    !  Viewport configuration file (2x1)
    !
    !        -------------
    !        |     |     |
    !        |  1  |  2  |
    !        |     |     |
    !        -------------
    !
    !v1  v2  v3  v4
    !-- --- --- ---
    0.1 0.5 0.2 0.8
    0.5 0.9 0.2 0.8

9.3.4 Header Template

Header template files (usually ending with .hdr) define the keywords from the internal header that are to be written out to the screen in the case of CHHEADER [template file] and to a file in the case of, for example, WRITE_IMAGE/TEMPLATE=[template file].

These files contain a line for each keyword of the form:

    OUTKEYWD = *INKEYWD / COMMENT

The OUTKEYWD and COMMENT values are used without modification in XIMAGE's FITS writer, while the *INKEYWD field contains information on what type the keyword value is and which internal header key is to be accessed. The symbol before INKEYWD represents the keyword type, which can be: ! = integer, $ = string, # = real, ? = unknown (XIMAGE figures it out by the internal header definition). If INKEYWD is left blank, the value for OUTKEYWD is assumed as well as a ? type.

INKEYWD can also be a quoted value which is independent of internal header values by preceding the the value with a $\backslash$ character. If no type character is given, string is assumed. The ? is not a valid type for a quoted value. If is is necessary to quote a string, the $\backslash$ or type indicator must be the first character inside the quotes (e.g. '$\backslash$text phrase').

Since the addition of a wcsid, the coordinates defined in the wcs data structure can be more expressive than the internal header. Consequently, one cannot tweak the coordinate system by manipulating the internal header as the contents of the wcs structure will override any modifications. The wcs information, however, can be suppressed with any of the following '$\backslash$wcs' directives.

    \wcs nowrite         / Omit image WCS info keys
    \wcs history         / Write image WCS info as HISTORY keys
    \wcs comment         / Write image WCS info as COMMENT keys

The internal header consists of the following keywords:

    #
    #  Template for displaying all of internal XIMAGE header
    #
    #  !,$,# are used here to document types of all header keywords
    #  ! = integer, $ = string, # = double (Also, see hdr.doc)
    #
    MAPPTR   = !         / Internal map pointer
    MAPTYPE  = $         / Map data type (I=integer R=real)
    MAPCODES = $         / Map manipulation codes (See map command)
    MAPCOPY  = $         / Map copy list (keeps track of identical maps)
    EXMAPID  = $         / Associated exposure map
    EXPMAP   = !         / Whether map is loaded exposure map (0/1)
    LOADED   = !         / Whether map is loaded (0/1 = yes/no)
    VIGNAPP  = !         / Whether vignetting correction is applied (0/1)
    WCSID    = $         / Associated wcs id (refers to AstFrameSet)
    FILE     = $         / Filename
    ROOT     = $         / File root
    SZX      = !         / Size in x direction
    SZY      = !         / Size in y direction
    XIMZERO  = #         / Offset XIMAGE has applied to original image
    XIMSCALE = #         / Scaling factor applied to original image
    BZERO    = #         / Offset
    BSCALE   = #         / Scaling factor
    BUNIT    = $         / Units of image array
    OBJECT   = $         / Field identification
    TELESCOP = $         / Telescope
    INSTRUME = $         / Instrument
    DETNAM   = $         / Detector name
    FILTER   = $         / Filter
    ZMX      = #         / Zoom in x direction
    ZMY      = #         / Zoom in y direction
    EQUINOX  = #         / Image equinox
    CTYPE1   = $         / Coordinate system
    CTYPE2   = $         / Coordinate system
    CUNIT1   = $         / Unit axis 1
    CUNIT2   = $         / Unit axis 2
    CRVAL1   = #         / Reference point axis 1
    CRVAL2   = #         / Reference point axis 2
    CRPIX1   = #         / Reference point pixel location axis 1
    CRPIX2   = #         / Reference point pixel location axis 2
    DRPIX1   = #         / Reference point of axis 1 in det coords
    DRPIX2   = #         / Reference point of axis 2 in det coords
    CDELT1   = #         / Pixel size along axis 1
    CDELT2   = #         / Pixel size along axis 2
    DDELT1   = #         / Pixel size along axis 1 in det coords
    DDELT2   = #         / Pixel size along axis 2 in det coords
    OCRPIX1  = #         / Original reference pixel axis 1
    OCRPIX2  = #         / Original reference pixel axis 2
    OCRVAL1  = #         / Original reference value axis 1
    OCRVAL2  = #         / Original reference value axis 2
    CROTA2   = #         / Rotation angle (degrees)
    XIMNORTH = #         / North angle
    EXPOSURE = #         / Exposure time (sec)
    DTIME    = #         / Dead time correction
    DATE-OBS = $         / Date of observation begin
    DATE-END = $         / Date of observation end
    DATAMIN  = #         / Minimum in array
    DATAMAX  = #         / Maximum in array
    EMIN     = !         / Minimum energy channel
    EMAX     = !         / Maximum energy channel

9.3.5 Mission Database File

The mission database defines the defaults used for specified missions. The installed mdb file ximage.mdb is loaded at XIMAGE startup.

      CHMDB/OUTFILE=[mdb file]  - Writes out mdb file
      CHMDB/INFILE=[mdb file]   - Inputs an mdb file

    !
    !  XIMAGE mission database files have the following syntax:
    !
    !  TELESCOP : INSTRUME : DETNAM {
    !      KEYWORD = VALUE
    !  }
    !
    !  DETNAM is optional.  The following is also valid:
    !
    !  TELESCOP : INSTRUME {
    !      KEYWORD = VALUE
    !  }
    !
    !  Defined keywords
    !
    !  DEFSZX   = Default image size in x
    !  DEFSZY   = Default image size in y
    !             Used by event reader if SIZE or SZX/Y not given
    !             Note: If DEFSZY not set, DEFSZY=DEFSZX and vice versa
    !
    !  DEFZOOM  = Default image zoom
    !             Used by event reader if REBIN not given
    !
    !  XCOL     = X column                  [=X, if omitted]
    !             Used by event reader if XCOL not given
    !
    !  YCOL     = Y column                  [=Y, if omitted]
    !             Used by event reader if YCOL not given
    !
    !  ECOL     = Energy column (PI/PHA)    [=PHA, if omitted]
    !  EMIN     = Minimum energy channel
    !  EMAX     = Maximum energy channel
    !             Used by event reader if ECOL, EMIN, EMAX not given
    !
    !  ENUM     = Number of energy channels
    !             Used by extract to allocate spectrum buffer
    !
    !  DRPIX1   = Detector center in x
    !  DRPIX2   = Detector center in y
    !             Used by image reader to assign detector coordinates
    !             if DRPIX1/2 not in FITS header
    !
    !  PIXSIZE  = Pixel size in arcsecs
    !             Used by PSF and vignetting if function or PSF file
    !             needs units of arc
    !
    !  DOPTIC1  = Optical axis in x
    !  DOPTIC2  = Optical axis in y
    !             Used by detect (PSF, vignetting, etc.) when offaxis
    !             is calculated
    !
    !  ERRRAD   = Error radius
    !             Used in detect for error radius
    !
    !  DETBOX   = Default detect box size    [=8, if omitted]
    !             Used as detect box size if SOURCE_BOX_SIZE not set
    !
    !  EXCHAN   = Default energy channels list used in EXTRACT
    !             Format - "c1,c2,c3,c4" Used for extract color file
    !             if C1,C2,C3,C4 qualifiers not set
    !
    !  ENGFILE  = Energy input file (spectrum used by internal vign or psf)
    !             Used to specify spectrum for energy-dependent psf and
    !             vignetting functions which overrides the default file in
    !             the cal directory
    !
    !  PSFFILE  = PSF input file (overrides internal calculation)
    !             PSF file which overrides default PSF file from cal
    !             directory or PSF function
    !
    !  VIGNFILE = Vignetting fits image (overrides internal calculation)
    !             Vignetting FITS image which overrides default from cal
    !             directory or vignetting function
    !
    !  GTIEXT = GTI extension expression (overrides default READ/GTIEXT=*GTI*)
    !
    !  CHMDB/INFILE [mdb file]   - Loads mdb file
    !  CHMDB/OUTFILE [mdb file]  - Writes out mdb file
    !
    EXTEL : EXINST {
       DEFSZX = 512  DEFZOOM=8
    }

9.3.6 Psf File

A PSF calibration file is generated with the psf/multpsffile=[filename] command. This output can be used to set the psffile key in the mdb (e.g. chmdb/key=psffile/val=[filename]). Subsequent PSF calculations will use that PSF calibration file.

The PSF calibration file can include several columns. The first column is the distance from centroid of the source and can be expressed in arcmin or unrebinned pixels. The remaining columns contain the fractional PSF at a different offaxis distance, indicated by the OFFAXISn keywords.

    !
    !  PSF calibration file for use as PSFFILE
    !
    !FILE    = 'filename.fits'      / Filename
    !OBJECT  = 'field name'         / Field identification
    !TELESCOP= 'EXTEL   '           / Telescope
    !INSTRUME= 'EXINST  '           / Instrument
    !
    !  Column 1: Distance from source center (det coords)
    !  Columns 2+: Fractional psf
    !
    $echo UNITTYPE=                    1 / Unit for OFFAXIS (1=pix, 2=arcmin)
    $echo OFFAXIS2=            3260.2703 / Offaxis distance for column 2
    $echo OFFAXIS3=            1240.3722 / Offaxis distance for column 3
    !
    7.5 8.5764946E-3 0.1945632
    23.5 2.8332831E-2 0.4073279
    39.5 8.8323012E-2 0.6626034
    55.5 0.1579828 0.7455482
    71.5 0.2537213 0.7772189
    87.5 0.3439038 0.7928265
    103.5 0.4605596 0.8055947
    119.5 0.5861865 0.81647
    135.5 0.6675338 0.8242607
    151.5 0.7392796 0.8362666
    167.5 0.8021447 0.8393251
    183.5 0.8378382 0.8413145
    199.5 0.8699709 0.8336555
    215.5 0.8889965 0.8479223
    231.5 0.9007197 0.8534872
    247.5 0.9042383 0.8599985
    263.5 0.9081515 0.8605246

9.3.7 Energy File

If an energy-dependent psf routine is available within ximage for a particular mission, the energy dependence can be calculated using a spectral file, created by using the extract/engfile=[filename] command. In order for an energy file to be used in the psf calculation, it must be set with chmdb/key=engfile/val=[filename].

    ! EXTEL EXINST
    ! filename.fits
    !
    !  Energy data file for use as ENGFILE
    !
    !  TELESCOP = EXTEL
    !  INSTRUME = EXINST
    !
    $echo BINNING =  8              /  Spectrum binning factor
    $echo ESTEP =    0.01           /  Energy step between bins (keV)
    $echo EOFFSET = -0.05           /  Energy value of first bin (keV)
    !
    ! Total channels:    408
    !
               0
               0
               0
               0
               8
             132
             695
             886
             926
               .
               .
               .
               0
               1

next_inactive up previous contents
Up: XIMAGE User's Guide Previous: 8. Commands S-Z   Contents
Alex Padgett 2010-03-25