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
Startup 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
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 information)
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=x,y,pha] # load FITS bin table, bin on x,y,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 or RAYEVENT
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
-
DATASEC
-
LTV / LTM for physical coords
-
DTV / DTM for detector coords
-
ATV / ATM for amplifier coords
-
WCS keywords
-
WCS# keywords
FITS Mosaic
A FITS mosaic image may exist as a series of FITS files, or as one FITS
file with many extensions. 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.
DS9 supports three forms of mosaics:
-
IRAF
contains the DETSEC and DETSIZE keywords. See
NOAO
IRAF Mosaic Data Structures
-
WCS
each FITS image or FITS bin table must contain a vaild equatorial wcs.
-
HST WFPC2
valid HST WFPC2 data cube, consisting of 4 planes, along with a fits
ascii table containing wcs information.
DS9 by default will first try to load as an IRAF mosaic. If the
IRAF keywords are not present, DS9 will then try to load as a WCS mosaic,
then as a HST WFPC2 image. This behavior can be modified to force either
IRAF, WCS, or HST WFPC2 from the preference
menu.
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 -array bar.arr[xdim=512,ydim=512,bitpix=16] # load 512x512
short
$ds9 -array bar.arr[dim=256,bitpix=-32,skip=4] # load 256x256 float
with 4 byte head
$ds9 -array 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 -array bar.arr[array(s512)] # load 512x512 short
$ds9 -array bar.arr[array(r256:4)] # load 256x256 float with 4
byte head
$ds9 -array 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.fil,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 supported:
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.
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:
DS9 uses the file extension to determine the color table format:
Ext
|
Format
|
.lut |
XImtool, SAOtng |
.lasc |
Skycat |
.sao |
DS9, SAOimage |
any other |
DS9 |
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.
Startup File
If a startup file is available, ~/.ds9.ini
or .ds9.ini for
windows, it is sourced as the last step in initialization.
TCL
TCL/TK script file. Users may customize the appearance and enhance the
capabilities of DS9 by sourceing their own TCL scripts.