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 infomation)
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 -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 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.
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.