FITS
FITS Image
FITS Binary Table
FITS Data Cube
FITS Multiple Extension Data Cube
FITS Multiple Extension Multiple Frames
FITS Mosaic
FITS Mosaic Data Cube
FITS RGB
Split FITS
Data Array
External Format Support
External Analysis Support
Region Files
Color Lookup Table
WCS
Preference File
Startup File
TCL
DS9 supports FITS images and FITS binary tables. The following algorithm is used to locate and to load the FITS image or table 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# keywordsAt load time, the user may provide just a filename or a filename along with FITS extension name or number. FITS extension names are case insensitive. When specifying an extention, be sure to quote strings correctly to pass both the shell and DS9 parser.
Syntax:
filename
filename[<name>|#]
Example:
$ds9 foo.fits # default load
$ds9 foo.fits[1] # load first extension
$ds9 foo.fits[BCKGRD] # load extension named 'BCKGRD'At load time, the user may provide just a filename or a filename along with FITS extension name or number, and columns names. FITS extension names and columns names are case insensitive. When specifying a filter, be sure to quote strings correctly to pass both the shell and ds9 parser.
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]
ext [<name> | #]
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
(see Introduction to Filtering for more information)
Example:
$ds9 foo.fits # default load
$ds9 foo.fits[1] # load first extension
$ds9 foo.fits[BCKGRD] # load extension named 'BCKGRD'
$ds9 foo.fits[bin=detx,dety] # bin on detx,dety
$ds9 foo.fits[2][bin=rawx,rawy] # load ext 2, cols rawx,rawy
$ds9 foo.fits[bg_events,bin=rawx,rawy] # load ext bg_events, cols rawx,rawy
$ds9 foo.fits[bin=x,y,pha] # bin on x,y,pi
$ds9 foo.fits[bin=pi] # bin on x,y,pi
$ds9 'foo.fits[ccd_id==3&&energy>4000]' # quoted filter
$ds9 '"foo.fits[ccd_id==3 && energy>4000]"' # double quoted filter
$ds9 'foo.fits[events][pha>5,pi<2]' # load extension 'events' and filterThe 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, rawyA FITS Data Cube is a FITS image which contains more than 2 axes (NAXES>2). DS9 will automatically detect if a data cube is present and will load all additional images. At the same time, DS9 will display the DataCube dialog box which allows the user to select which 2 image to be displayed.
FITS Multiple Extension as Data Cube
A FITS Multiple Extension Data Cube file is a FITS file with one or more extensions, that is to be displayed as a data cube. Each image does not have to be the same size, however, only the coordinate systems from the first extension will be used for contours and grids.
Example:
$ds9 -medatacube foo.fits # load multiple extension fits file as data cubeFITS Multiple Extension as Multiple Frames
Load a multiple extension FITS file into multiple frames. Please note that files loaded via standard-in or the xpa fits command can not be displayed using this method.
Example:
$ds9 -multiframe foo.fits # load multiple extension fits file as multiple framesA FITS mosaic image may exist as a series of FITS files, or as one FITS file with many extensions. A 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:
Example:
IRAF
contains the DETSEC and DETSIZE keywords.
See NOAO IRAF Mosaic Data Structures
WCS
each FITS image contains a valid WCS.
HST WFPC2
valid HST WFPC2 data cube, consisting of 4 planes, along with a fits ascii table containing wcs information.
$ds9 -mosaicimageiraf foo.fits # load mosaic iraf from one fits file with multiple exts
$ds9 -mosaiciraf foo.fits bar.fits wow.fits # load mosaic iraf from 3 files
$ds9 -mosaicimagewcs foo.fits # load mosaic wcs from one fits file with multiple exts
$ds9 -mosaicimagenext wcs foo.fits # load mosaic wcs from one fits file with multiple exts
$ds9 -mosaicwcs foo.fits bar.fits wow.fits # load mosaic wcs from 3 files
$ds9 -mosaicimagewfpc2 bar.fits # load wfpc2 mosaic
$ds9 -mosaic foo.fits bar.fits wow.fits # load mosaic (iraf or wcs) from 3 files
A FITS Mosaic Data Cube is a FITS mosaic image which contains more than 2 axes (NAXES>2). DS9 will automatically detect if a mosaic data cube is present and will load all additional images. At the same time, DS9 will display the DataCube dialog box which allows the user to select which 2 image to be displayed.
A FITS RGB image may exist as three of FITS images, one FITS file with three extensions, or as a FITS 3D Data cube, with three slices, each representing the red, green, and blue channel. A FITS RGB image may be loaded all a one time, or by the channel. Once loaded, the multiple FITS images are treated as one FITS image.
Example:
$ds9 -rgbimage rgb.fits # load rgb image consisting of one fits file with 3 image exts
$ds9 -rgbcube cube.fits # load rgb image consisting of one fits data cube
$ds9 -rgb -red foo.fits -green bar.fits -blue wow.fits # rgb image from 3 fits images
A split fits is a valid fits file in which two files contain the header and data segments.
Raw data arrays are supported. To load an array, the user must providethe dimensions, pixel depth, and optional header size and architecture type.
Syntax:
filename[options]
options are:
xdim=value
ydim=value
zdim=value # default is a depth of 1
dim=value
dims=value
bitpix=[8|16|-16|32|64|-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,zdim=1,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 chardim:
's' 16-bit short int
'u' 16-bit unsigned short int
'i' 32-bit int
'l' 64-bit int
'r' 32-bit float
'f' 32-bit float
'd' 64-bit floatint # x,y dimskip:
int.int # x,y dim
int.int.int # x,y,z dim
int # number of bytes to skipendian:l' little endianExample:
'b' big endian
$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, intelThe 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 floatDS9 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.filin 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: $filename
For Example:
# File access descriptions:
# help explanation
# file template
# file type
# access command
IRAF IMH files
*.imh
IMH
i2f -s $filenameFor more information about external analysis support files, see Analysis.
DS9 can read and write a number of region file formats. See Regions documentation for more information.
DS9
FUNTools
Ciao
SAOimage
IRAF PROS
FITS REGION Binary Table
X YDS9 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
DS9 uses the file extension to determine the color table format:
Ext Format .lut XImtool, SAOtng .lasc Skycat .sao DS9, SAOimage any other DS9 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'A preference file is a valid tcl script generated by DS9 to save the current preference items. See Preferences for more information.
If a startup file ds9.ini is available, it is sourced as the last step in initialization. The following directories are searched in order: ./, $HOME, /usr/local/lib, /opt/local/lib.
TCL/TK script file. Users may customize the appearance and enhance the capabilities of DS9 by sourcing their own TCL scripts.