File Formats

Information on the following file formats are available:

FITS
FITS Mosaic
Data Array
External Format Support
External Analysis Support
Region Files
Color Lookup Table
WCS
Preference File
TCL

FITS

DS9 supports  FITS images, FITS bin tables and FITS ascii tables. See FITS Standard for more information. At load time, the user may provide just a filename or a filename along with FITS extension name or number, and columns names for FITS bin tables. FITS extension names and columns names are case insensitive.
Syntax:
filename
filename [ext]
filename [bin]
filename [filter]
filename [ext][bin]
filename [ext][filter]
filename [bin][filter]
filename [ext][bin][filter]
filename [ext, bin]
filename [bin, filter]
filename [ext, bin, filter]
where ext
name
number
and bin
bin=colx,coly # bin counts
bin colx,coly # bin counts
bin=colx,coly,colz # bin on colz
bin colx,coly,colz # bin on colz
bin=colz # bin cols 'x', 'y', and colz
key=colx,coly
binkey=colx,coly
and filter (see Introduction to Filtering for more infomation)
any filter expression


Example:
$ds9 foo.fits # default load
$ds9 foo.fits[1] # load first extension, image or bin table
$ds9 foo.fits[BCKGRD] # load extension named 'BCKGRD'
$ds9 foo.fits[bin=detx,dety] # load FITS bin table, bin on detx,dety
$ds9 foo.fits[2][bin=rawx,rawy] # load FITS bin table, ext 2, cols rawx,rawy
$ds9 foo.fits[bg_events,bin=rawx,rawy] # load FITS bin table
$ds9 foo.fits[bin=rawx,rawy,pi] # load FITS bin table, bin on rawx,rawy,pi
$ds9 foo.fits[bin=pi] # load FITS bin table, bin on x,y,pi
$ds9 foo.fits[events][pha>5,pi<2] # load extension 'events' and filter

The shell environment variable DS9_BINKEY may be used to specify default bin cols for FITS bin tables. Example:
$export DS9_BINKEY='[bin=rawx,rawy]'
$ds9 foo.fits # load FITS bin table, bin on rawx, rawy

The following algorithm is used to locate and to load the FITS image if no additional information is provide:

Look for FITS image in primary HDU.
If no image is found, examine each extension HDU
If image, load
if bin table, load if the following is true
extension name is EVENTS or STDEVT
column names X and Y are present
If DS9 traverses the entire FITS file without satisfying one of the above, an error is generated.


FITS keyword inheritance is supported. All valid FITS BITPIX values are supported, along with -16, for UNSIGNED SHORT. The following FITS keywords are supported:

• OBJECT
• BSCALE / BZERO
• BLANK
• LTV / LTM  for physical coords
• DTV / DTM  for detector coords
• ATV / ATM  for amplifier coords
• WCS keywords

FITS Mosaic

DS9 supports NOAO IRAF Mosaic Data Structures  A FITS mosaic image may exist as a series of FITS files, or as one FITS file with many extensions. To be a valid mosaic, it must contain the DETSEC and DETSIZE keywords. FITS mosaic may be loaded all a one time, or by the segment. Once loaded, the multiple FITS images are treated as one FITS image.

Data Array

Raw data arrays are supported. To load an array, the user must provide the dimensions, pixel depth, and optional header size and architecture type.
Syntax:

filename [options]
options are:

xdim=value
ydim=value
dim=value
dims=value
bitpix=[8|16|-16|32|-32|-64]
skip=value # must be even, most must be factor of 4
arch=[bigendian | littleendian]
Example:
$ds9 bar.arr[xdim=512,ydim=512,bitpix=16] # load 512x512 short
$ds9 bar.arr[dim=256,bitpix=-32,skip=4] # load 256x256 float with 4 byte head
$ds9 bar.arr[dim=512,bitpix=32,arch=littleendian] # load 512x512 long, intel

or alternate format:

filename [array(<type><dim><:skip><endian>)]
type:

'b' 8 -bit unsigned char
's' 16-bit short int
'u' 16-bit unsigned short int
'i' 32-bit int
'r' 32-bit float
'f' 32-bit float
'd' 64-bit float
dim:
int     # x,y dim
int.int # x,y dim
skip:
int     # number of bytes to skip
endian:
'l' little endian
'b' big endian
Example:
$ds9 bar.arr[array(s512)]   # load 512x512 short
$ds9 bar.arr[array(r256:4)] # load 256x256 float with 4 byte head
$ds9 bar.arr[array(i512l)]  # load 512x512 long, intel

The shell environment variable DS9_ARRAY may be used to specify default array parameters. Example:
$export DS9_ARRAY='[dim=256,bitpix=-32]'
$ds9 -array foo.arr # load 256x256 float

External File Support

DS9 supports external file formats via an ASCII description file. When loading a file into DS9, these descriptions are referenced for instructions for loading the file, based on the file extension. If found, the command is executed and the result, a FITS image or FITS Binary Table, is read into DS9 via stdin.

At start-up, DS9 first searches for the ASCII file, named .ds9.file, in the local directory, then in the users home directory.

The file command first is macro-expanded to fill in user-defined arguments and then is executed externally.

The ASCII file that defines the known image files consists of one or more file descriptors, each of
which has the following format:

Help description

A space-separated list of templates

A space-separated list of file types (not currently used)

The command line for the loading this file type

Note that blank lines separate the file descriptions and should not be used as part of a description.
Also, the '#' character is a comment character.

The following macros are suported:
 

Macro	Description
filename	insert current full file name

For Example:

#
# File access descriptions:
#       help explanation
#       file template
#       file type
#       access command

IRAF IMH files
*.imh
IMH
i2f -s $filename

External Analysis Support

For more information about external analysis support files, see Analysis.

Region Files

DS9 can read and write a number of region file formats. See Regions documentation for more information.
• DS9
• FUNTools
• Ciao
• FTools
• SAOimage
• IRAF PROS
• FITS REGION Binary Table

Color Lookup Table

DS9 has a number of default colormaps available to the user. DS9 also supports reading and writing color lookup table formats from the following programs:
• SAOimage
• SAOtng
• XImtool
• Skycat

WCS

A new WCS specification can be loaded and used by the current image regardless of the WCS that was contained in the image file. WCS specification can be sent to DS9 as an ASCII file via XPA. The format of the specification is a set of valid FITS keywords that describe a WCS.
Example:
    CRPIX1  =               257.75
    CRPIX2  =               258.93
    CRVAL1  =      -201.94541667302
    CRVAL2  =             -47.45444
    CDELT1  =        -2.1277777E-4
    CDELT2  =         2.1277777E-4
    CTYPE1  = 'RA---TAN'
    CTYPE2  = 'DEC--TAN'
Note that the WCS definitions can contain standard FITS 80-character WCS card images, as shown above, or free-form name/value pairs without the intervening "=" sign:
    CRPIX1    257.75
    CRPIX2    258.93
    CRVAL1    -201.94541667302
    CRVAL2    -47.45444
    CDELT1    -2.1277777E-4
    CDELT2    2.1277777E-4
    CTYPE1   'RA---TAN'
    CTYPE2   'DEC--TAN'

Preference File

A preference file is a valid tcl script generated by DS9 to save the current preference items. See Preferences for more information.

TCL

TCL/TK script file. Users may customize the appearance and enhance the capabilities of DS9 by sourceing their own TCL scripts.