SAMP

SAMP is a messaging protocol that enables astronomy software tools to interoperate and communicate. Broadly speaking, SAMP is an abstract framework for loosely-coupled, asynchronous, RPC-like and/or event-based communication, based on a central service providing multi-directional publish/subscribe message brokering. The message semantics are extensible and use structured but weakly-typed data. For more information on SAMP, please click here.

The samp implementation for DS9 is based on the XPA model with 2 private calls:

ds9.get
    Arguments
        cmd (string) required
        url (string) optional
    Returned value
        OK (samp.result map)
            value (string) optional
                url (string) optional
        ERROR (samp.error map)
            samp.errortxt (string)
 
ds9.set
    Arguments
        cmd (string) required
        url (string) optional
    Returned value
        OK
        ERROR (samp.error map)
            samp.errortxt (string)

ds9.set maybe called via notification, call and call/wait. ds9.get can only be called via call and call/wait. Most of the ds9.get calls return a value string, but a few will return a url instead.

2mass
3d
about
analysis
array
background
backup
bin
blink
block
catalog
cd
cmap
colorbar
console
contour
crop
crosshair
cube
cursor
data
dsssao
dsseso
dssstsci
envi
exit
export
file
fits
frame
gif
grid
header
height
iconify
iexam
iis
jpeg
lock
lower
magnifier
mask
match
mecube
minmax
mode
mosaic
mosaicimage
movie
multiframe
nameserver
nan
nrrd
nvss
orient
pagesetup
pan
pixeltable
plot
png
precision
prefs
preserve
psprint
print
quit
raise
regions
restore
rgb
rgbarray
rgbcube
rgbimage
rotate
samp
save
saveimage
scale
shm
sia
single
skyview
sleep
smooth
source
tcl
threads
tiff
tile
update
url
version
view
vla
vlss
vo
wcs
web
width
zscale
zoom

2mass

Support for 2MASS Digital Sky Survey.

Syntax:
2mass []
      [<object>]
      [name <object>|clear]
      [<ra> <dec>] # in wcs fk5
      [size <width> <height> degrees|arcmin|arcsec]
      [save yes|no]
      [frame new|current]
      [update frame|crosshair]
      [survey j|h|k]
      [open|close]
 
Example:
string value = ds9.get(string cmd)
2mass name
2mass coord
2mass size
2mass save
2mass frame
2mass survey
ds9.set(string cmd)
2mass
2mass m31
2mass name m31
2mass name clear
2mass 00:42:44.404 +41:16:08.78
2mass size 60 60 arcmin
2mass save yes
2mass frame current
2mass update frame
2mass survey j
2mass open
2mass close

3d

Support for 3D frame.

Syntax:
3d []
   [view <az> <el>]
   [az <az>]
   [el <el>]
   [scale <scale>]
   [method mip|aip]
   [background none|azimuth|elevation]
   [border yes|no]
   [border color <color>]
   [highlite yes|no]
   [hightlite color <color>]
   [compass yes|no]
   [compass color <color>]
   [match]
   [lock [yes|no]]
   [open|close]
 
Example:
string value = ds9.get(string cmd)
3d view
3d az
3d el
3d scale
3d method
3d background
3d border
3d border color
3d highlite
3d highlite color
3d compass
3d compass color
3d lock
ds9.set(string cmd)
3d # create new 3D frame
3d view 45 30
3d az 45
3d el 30
3d scale 10
3d method mip
3d background azimuth
3d border yes
3d border color red
3d highlite yes
3d highlite color red
3d compass yes
3d compass color red
3d match
3d lock yes
3d open
3d close

about

Get DS9 credits.

Syntax:
about
 
Example:
string value = ds9.get(string cmd)
about

align

Controls the World Coordinate System alignment for the current frame.

Syntax:
align []
      [yes|no]
 
Example:
string value = ds9.get(string cmd)
align
ds9.set(string cmd)
align yes

analysis

Control external analysis tasks. Tasks are numbered as they are loaded, starting with 0. Can also be used to display a message and display text in the text dialog window.

Syntax:
analysis [<task number>]
         [<filename>]
         [task <task number>|<task name>]
         [load <filename>]
         [clear]
         [clear][load <filename>]
         [message ok|okcancel|yesno <message>]
         [entry <message>]
         [text]
 
Example:
string value = ds9.get(string cmd)
analysis
analysis task
analysis entry {Please enter something}
analysis entry okcancel {Hello World}
ds9.set(string cmd)
analysis 0 # invoke first analysis task
analysis task 0
analysis task foobar
analysis task {foo bar}
analysis my.ans
analysis load my.ans
analysis clear
analysis clear load my.ans
analysis message {This is a message}
analysis text {this is text}
ds9.set(string cmd, string url)
analysis load
analysis text

array

Load raw data array into current frame.

Syntax:
array [native|little|big]
array [new|mask] [[xdim=<x>,ydim=<y>|dim=<dim>],zdim=<z>,bitpix=<b>,skip=<s>,endian=[little|big]]
 
Example:
string url = ds9.get(string cmd)
array
array little
ds9.set(string command, string url)
array foo.arr[dim=512,bitpix=-32,endian=little]
array new foo.arr[dim=512,bitpix=-32,endian=little]
array mask foo.arr[dim=512,bitpix=-32,endian=little]

bg
background

Set image background color.

Syntax:
bg <color>
 
Example:
string url = ds9.get(string cmd)
bg
ds9.set(string cmd)
bg red
bg red

backup

Create a backup save set.

Syntax:
backup <filename>
 
Example:
ds9.set(string cmd)
backup ds9.bck

bin

Controls binning factor, binning buffer size, and  binning function for binning FITS bin tables. The access point blocking is provided for backward compatibility.

Syntax:
bin [about <x> <y>]
    [about center]
    [buffersize <value>]
    [cols <x> <y>]
    [colsz <x> <y> <z>]
    [factor <value> [<vector>]]
    [depth <value>]
    [filter <string>]
    [filter clear]
    [function average|sum]
    [in]
    [out]
    [to fit]
    [match]
    [lock [yes|no]]
    [open|close]
 
Example:
string value = ds9.get(string cmd)
bin about
bin buffersize
bin cols
bin factor
bin depth
bin filter
bin function
bin smooth
bin smooth function
bin smooth radius
bin lock
ds9.set(string cmd)
bin about 4096 4096
bin about center
bin buffersize 512
bin cols detx dety
bin colsz detx dety time
bin factor 4
bin factor 4 2
bin depth 10
bin filter 'pha > 5'
bin filter clear
bin function sum
bin in
bin out
bin to fit
bin match
bin lock yes
bin open
bin close

blink

Blink mode parameters. Interval is in seconds.

Syntax:
blink []
      [yes|no]
      [interval <value>]
 
Example:
string value = ds9.get(string cmd)
blink
blink interval
ds9.set(string cmd)
blink
blink yes
blink interval 1

block

Controls blocking parameters.

Syntax:
block [<value>]
      [<value> <value>]
      [to <value>]
      [to <value> <value>]
      [in]
      [out]
      [to fit]
      [match]
      [lock [yes|no]]
      [open|close]
 
Example:
string value = ds9.get(string cmd)
block
block lock
ds9.set(string cmd)
block 4
block 4 2
block to 4
block to 4 2
block in
block out
block to fit
block match
block lock yes
block open
block close

catalog
cat

Support for catalogs. The first three commands will create a new catalog search. All other commands operated on the last search created, unless indicated otherwise.

Syntax:
catalog [new]
        [ned|simbad|denis|skybot]
        [aavso|ac|ascss|cmc|gaia|gsc1|gsc2|gsc3|nomad|ppmx|sao|sdss5|sdss6|sdss7|sdss8|sdss9|tycho]
        [ua2|ub1|ucac2|ucac2sup|ucac3|ucac4|urat1]
        [2mass|iras]
        [csc|xmm|rosat]
        [first|nvss]
        [chandralog|cfhtlog|esolog|stlog|xmmlog]
        [cds <catalogname>]
        [cds <catalogid>]

        [load <filename>]
        [import sb|tsv <filename>]

        [<ref>] [<ra> <dec> <coordsys>]
        [<ref>] [allcols]
        [<ref>] [allrows]
        [<ref>] [cancel]
        [<ref>] [clear]
        [<ref>] [close]
        [<ref>] [crosshair]
        [<ref>] [dec <col>]
        [<ref>] [edit yes|no]
        [<ref>] [export sb|tsv <filename>]
        [<ref>] [filter <string>]
        [<ref>] [filter load <filename>]
        [<ref>] [header]
        [<ref>] [location <code>]
        [<ref>] [match]
        [<ref>] [match <ref> <ref>]
        [<ref>] [match error <value> degrees|arcmin|arcsec]
        [<ref>] [match function 1and2|1not2|2not1]
        [<ref>] [match return 1and2|1only|2only]
        [<ref>] [match unique yes|no]
        [<ref>] [maxrows <number>]
        [<ref>] [name <object>]
        [<ref>] [panto yes|no]
        [<ref>] [plot <xcol> <ycol> <xerrcol> <yerrcol>]
        [<ref>] [print]
        [<ref>] [psky <skyframe>]
        [<ref>] [psystem <coordsys>]
        [<ref>] [ra <col>]
        [<ref>] [regions]
        [<ref>] [retrieve]
        [<ref>] [samp]
        [<ref>] [samp broadcast]
        [<ref>] [samp send <application>]
        [<ref>] [save <filename>]
        [<ref>] [server cds|adac|cadc|cambridge|sao|ukirt|iucaa|bejing|saao]
        [<ref>] [show yes|no]
        [<ref>] [radius <value> degrees|arcmin|arcsec]
        [<ref>] [sky <skyframe>]
        [<ref>] [skyformat <skyformat>]
        [<ref>] [sort <col> incr|decr]
        [<ref>] [symbol [#] condition|shape|color|text|font|fontsize|fontweight|fontslant <value>]
        [<ref>] [symbol [#] text|size|size2|units|angle <value>]
        [<ref>] [symbol shape circle|ellipse|box|text|point]
        [<ref>] [symbol shape circle point|box point|diamond point|cross point|x point|arrow point|boxcircle point]
        [<ref>] [symbol add| [#] remove]
        [<ref>] [symbol save|load <filename>]
        [<ref>] [system <coordsys>]
        [<ref>] [update]
        [<ref>] [x <col>]
        [<ref>] [y <col>]
 
Example:
string value = ds9.get(string cmd)
catalog
catalog header

ds9.set(string cmd)
catalog new
catalog 2mass
catalog cds 2mass
catalog cds {I/252}

catalog load foo.xml
catalog import tsv foo.tsv

catalog allrows
catalog allcols
catalog cancel
catalog clear
catalog close
catalog coordinate 202.48 47.21 fk5
catalog crosshair
catalog dec DEC
catalog edit yes
catalog export tsv bar.tsv
catalog filter {$Jmag>10}
catalog filter load foo.flt
catalog header
catalog location 500
catalog match error 2 arcsec
catalog match function 1and2
catalog match unique no
catalog match return 1only
catalog match # last two catalogs loaded
catalog match 2mass csc
catalog maxrows 2000
catalog name m51
catalog panto no
catalog plot {$Jmag} {$Hmag} {$e_Jmag} {$e_Hmag}
catalog print
catalog psky fk5
catalog psystem wcs
catalog ra RA
catalog regions
catalog retrieve
catalog samp broadcast
catalog samp send aladin
catalog save foo.xml
catalog server sao
catalog show yes
catalog radius 1 degrees
catalog symbol condition {$Jmag>15}
catalog symbol 2 shape {boxcircle point}
catalog symbol color red
catalog symbol font times
catalog symbol fontsize 14
catalog symbol fontweight bold
catalog symbol fontslant italic
catalog symbol add
catalog symbol 2 remove
catalog symbol load foo.sym
catalog symbol save bar.sym
catalog sky fk5
catalog skyformat degrees
catalog sort {Jmag} incr
catalog system wcs
catalog update
catalog x RA
catalog y DEC

cd

Sets/Returns the current working directory.

Syntax:
cd [<directory>]
 
Example:
string value = ds9.get(string cmd)
cd
ds9.set(string cmd)
cd /home/mrbill

cmap

Controls the colormap for the current frame. The colormap name is not case sensitive. A valid contrast value is  from 0 to 10 and bias value from 0 to 1.

Syntax:
cmap [<colormap>]
     [file]
     [load <filename>]
     [save <filename>]
     [invert yes|no]
     [<constrast> <bias>]
     [tag [load|save] <filename>]
     [tag delete]
     [open|close]
 
Example:
string value = ds9.get(string cmd)
cmap
cmap file
cmap invert
cmap value
cmap lock
ds9.set(string cmd)
cmap Heat
cmap load foo.sao
cmap save bar.sao
cmap invert yes
cmap 5 .5
cmap tag load foo.tag
cmap tag save foo.tag
cmap tag delete
cmap open
cmap close

colorbar

Controls colorbar parameters.

Syntax:
colorbar []
         [yes|no]
         [orientation]
         [horizontal|vertical]
         [numerics yes|no]
         [space value|distance]
         [font times|helvetica|courier]
         [fontsize <value>]
         [fontweight normal|bold]
         [fontslant roman|italic]
         [size]
         [ticks]
         [match]
         [lock [yes|no]]
 
Example:
string value = ds9.get(string cmd)
colorbar
colorbar orientation
colorbar numerics
colorbar space
colorbar font
colorbar fontsize
colorbar fontweight
colorbar fontslant
colorbar size
colorbar ticks
ds9.set(string cmd)
colorbar yes
colorbar vertical
colorbar numerics yes
colorbar space value
colorbar font times
colorbar fontsize 14
colorbar fontwieght bold
colorbar fontslant italic
colorbar size 20
colorbar ticks 11
colorbar match
colorbar lock yes

console

Display tcl console window.

Syntax:
-console
 
Example:
ds9.set(string cmd)
console

contour

Controls contours in the current frame.

Syntax:
contour []
        [yes|no]
        [<coordsys> [<skyframe>]]
        [clear]
        [generate]
        [load <filename>]
        [save <filename> [<coordsys> <skyframe>]]
        [convert]
        [load levels <filename>]
        [save levels <filename>]
        [copy]
        [paste [<coordsys> <color> <width> yes|no]]
        [color <color>]
        [width <width>]
        [dash yes|no]
        [smooth <smooth>]
        [method block|smooth]
        [nlevels <number of levels>]
        [scale linear|log|pow|squared|sqrt|asinh|sinh|histequ]
        ]scale log exp <value>]
        [mode minmax|<value>|zscale|zmax]
        [scope global|local]
        [limits <min> <max>]
        [levels <value value value...>]
        [open|close]
 
Example:
string value = ds9.get(string cmd)
contour
contour color
contour width
contour dash
contour smooth
contour method
contour nlevels
contour scale
contour log exp
contour mode
contour scope
contour limits
contour levels
string url = ds9.get(string cmd)
contour wcs fk5
ds9.set(string cmd)
contour
contour yes
contour clear
contour generate
contour load ds9.ctr
contour save ds9.con
contour save ds9.con wcs fk5
contour convert
contour load levels ds9.ctr
contour save levels ds9.lev
contour copy
contour paste
contour paste wcs red 2 no
contour color yellow
contour width 2
contour dash yes
contour smooth 5
contour method smooth
contour nlevels 10
contour scale sqrt
contour log exp 1000
contour mode zscale
contour scope local
contour limits 1 100
contour levels {1 10 100 1000}
contour open
contour close

crop

Set current image display area.

Syntax:
crop [<x> <y> <width> <height> [<coordsys>][<skyframe>][degrees|arcmin|arcsec]
      [match <coordsys>]
      [lock <coordsys>|none]
      [reset]
      [3d zmin zmax <coordsys>]
      [open|close]
 
Example:
string value = ds9.get(string cmd)
crop # get crop in physical coords
crop wcs galactic sexagesimal arcsec
crop lock
ds9.set(string cmd)
crop 40 30 10 20 # set crop in physical coords
crop +104:51:06.915 +68:33:40.761  28.144405 22.000204 wcs galactic arcsec
crop match wcs
crop lock wcs
crop reset
crop 3d .25 .5 wcs
crop open
crop close

crosshair

Controls the current position of the crosshair in the current frame. DS9 is placed in crosshair mode when the crosshair is set.

Syntax:
crosshair [<x> <y> <coordsys> [<skyframe>]]
          [match <coordsys>]
          [lock <coordsys>|none]
 
Example:
string value = ds9.get(string cmd)
crosshair # get crosshair in physical coords
crosshair wcs fk4 sexagesimal # get crosshair in wcs coords
crosshair lock
ds9.set(string cmd)
crosshair 100 100 physical # set crosshair in physical
crosshair 345 58.8 wcs fk5 # set crosshair in wcs coords
crosshair 23:01:00 +58:52:51 wcs fk5
crosshair match wcs
crosshair lock wcs

cube

Controls FITS cube.

Syntax:
cube []
     [play|stop|next|prev|first|last]
     [<slice> [<coordsys>][<axis>]]
     [interval <numeric>]
     [match <coordsys>]
     [lock <coordsys>|none]
     [order 123|132|213|231|312|321]
     [axes lock [yes|no]]
     [open|close]
 
Example:
string value = ds9.get(string cmd)
cube
cube interval
cube lock
cube order
cube axes lock
ds9.set(string cmd)
cube
cube play
cube last
cube 3
cube 4.5 wcs 3
cube interval 2
cube match wcs
cube lock wcs
cube order 123
cube axes lock yes
cube open
cube close

cursor

Move mouse pointer or crosshair in image pixels in the current frame. Note, this will move selected Regions also.

Syntax:
cursor [<x> <y>]
 
Example:
ds9.set(string cmd)
cursor 10 10

data

Return an array of data values given a lower left corner and a width and height in specified coordinate system. The last argument of yes indicates to strip the coordinates from the output and just list the data values. The default is yes.

Syntax:
data [<coordsys> [<skyframe>] <x> <y> <width> <height> [yes|no]]
 
Example:
string url = ds9.get(string cmd)
data image 450 520 3 3 yes
data physical 899 1039 6 6 no
data fk5 202.47091 47.196811 0.00016516669 0.00016516669 no
data wcs fk5 13:29:53.018 +47:11:48.52 0.00016516669 0.00016516669 no

dsssao
dss

Support for Digital Sky Survey at SAO.

Syntax:
dsssao []
       [<object>]
       [name <object>|clear]
       [<ra> <dec>] # in wcs fk5
       [size <width> <height> degrees|arcmin|arcsec]
       [save yes|no]
       [frame new|current]
       [update frame|crosshair]
       [open|close]
 
Example:
string value = ds9.get(string cmd)
dsssao name
dsssao coord
dsssao size
dsssao save
dsssao frame
ds9.set(string cmd)
dsssao
dsssao m31
dsssao name m31
dsssao name clear
dsssao 00:42:44.404 +41:16:08.78
dsssao size 60 60 arcmin
dsssao save yes
dsssao frame current
dsssao update frame
dsssao open
dsssao close

dsseso

Support for Digital Sky Survey at ESO.

Syntax:
dsseso []
       [<object>]
       [name <object>|clear]
       [<ra> <dec>] # in wcs fk5
       [size <width> <height> degrees|arcmin|arcsec]
       [save yes|no]
       [frame new|current]
       [update frame|crosshair]
       [survey DSS1|DSS2-red|DSS2-blue|DSS2-infrared]
       [open|close]
 
Example:
string value = ds9.get(string cmd)
dsseso name
dsseso coord
dsseso size
dsseso save
dsseso frame
dsseso survey
ds9.set(string cmd)
dsseso
dsseso m31
dsseso name m31
dsseso name clear
dsseso 00:42:44.404 +41:16:08.78
dsseso size 60 60 arcmin
dsseso save yes
dsseso frame current
dsseso update frame
dsseso survey DSS2-red
dsseso open
dsseso close

dssstsci

Support for Digital Sky Survey at STSCI.

Syntax:
dssstsci []
         [<object>]
         [name <object>|clear]
         [<ra> <dec>] # in wcs fk5
         [size <width> <height> degrees|arcmin|arcsec]
         [save yes|no]
         [frame new|current]
         [update frame|crosshair]
         [survey poss2ukstu_red|poss2ukstu_ir|poss2ukstu_blue]
         [survey poss1_blue|poss1_red]
         [survey all|quickv|phase2_gsc2|phase2_gsc1]
         [open|close]
 
Example:
string value = ds9.get(string cmd)
dssstsci name
dssstsci coord
dssstsci size
dssstsci save
dssstsci frame
dssstsci survey
ds9.set(string cmd)
dssstsci
dssstsci m31
dssstsci name m31
dssstsci name clear
dssstsci 00:42:44.404 +41:16:08.78
dssstsci size 60 60 arcmin
dssstsci save yes
dssstsci frame current
dssstsci update frame
dssstsci survey all
dssstsci open
dssstsci close

envi

Load an ENVI header and file. Optional parameter: array endian.

Syntax:
envi [new] <header> [<filename>]
 
Example:
envi foo.hdr
envi new foo.hdr
envi foo.hdr foo.bsq

exit

quit

Quits DS9.

Syntax:
exit
quit
 
Example:
ds9.set(string cmd)
exit

export

Export loaded image data of current frame in specified image format. Optional parameters: array endian, nrrd endian, jpeg quality (1-100) and tiff compression method.

Syntax:
export [array|nrrd|envi|gif|tiff|jpeg|png] <filename>
export array <filename> [big|little|native]
export nrrd <filename> [big|little|native]
export envi <header> [<filename>] [big|little|native]
export jpeg <filename> [1-100]
export tiff <filename> [none|jpeg|packbits|deflate]
 
Example:
ds9.set (string cmd)
export array foo.arr little
export nrrd foo.nrrd little
export envi foo.hdr little
export envi foo.hdr foo.bsq little
export tiff foo.tiff jpeg
export jpeg foo.jpeg 75
export png foo.png

file

Query currently loaded file information.

Syntax:
file
 
Example:
string value = ds9.get(string cmd)
file

fits

Load a FITS image into the current frame or query the currently loaded image.

Syntax:
fits [new|mask|slice] [<filename>]
     [width|height|depth|bitpix|type]
     [size [wcs|wcsa...wcsz] [fk4|fk5|icrs|galactic|ecliptic] [degrees|arcmin|arcsecs]]
     [header [<ext>] [keyword <string>]]
     [image|table|slice]
 
Example:
string value = ds9.get(string cmd)
fits
fits width
fits height
fits depth
fits bitpix
fits type
fits size
fits size wcs fk5 arcmin
fits header # primary
fits header 2 # hdu 2
fits header -2 # hdu 2 with inherit
fits header keyword BITPIX
fits header 1 keyword BITPIX
fits image
fits table
fits slice
ds9.set(string cmd, string url)
fits foo.fits
fits new foo.fits
fits bar.fits[bin=detx,dety]
fits slice foo.fits
fits mask foo.fits
fits
fits new
fits -[bin=detx,dety]
fits slice
fits mask

Syntax:

fits [new|mask|slice] [<filename>]
     [width|height|depth|bitpix]
     [size [wcs|wcsa...wcsz] [fk4|fk5|icrs|galactic|ecliptic] [degrees|arcmin|arcsecs]]
     [header [<ext>] [keyword <string>]]
     [image|table|slice]
 
Example:
string value = ds9.get(string cmd)
fits width
fits height
fits depth
fits bitpix
fits size
fits size wcs fk5 arcmin
fits header # primary
fits header 2 # hdu 2
fits header -2 # hdu 2 with inherit
fits header keyword BITPIX
fits header 1 keyword BITPIX
fits
fits image
fits table
fits slice
ds9.set(string cmd, string url)
fits foo.fits
fits new foo.fits
fits bar.fits[bin=detx,dety]
fits slice foo.fits
fits mask foo.fits

frame

Controls frame functions. Frames may be created, deleted, reset, and centered. While return the current frame number. If you goto a frame that does not exists, it will be created. If the frame is hidden, it will be shown. The 'frameno' option is available for backward compatibility.

Syntax:
frame [center [#|all]]
      [clear [#|all]]
      [new [rgb|3d]]
      [delete [#|all]]
      [reset [#|all]]
      [refresh [#|all]]
      [hide [#|all]]
      [show [#|all]]
      [move first]
      [move back]
      [move forward]
      [move last]
      [first]
      [prev]
      [next]
      [last]
      [frameno #]
      [#]
      [match <coordsys>]
      [lock <coordsys>|none]
      [has [amplifier|datamin|datasec|detector|grid|iis|irafmin|physical|smooth]]
      [has contour [aux]]]
      [has fits [ |bin|cube|mosaic]]
      [has marker [highlite|paste|select|undo]]
      [has system <coordsys>]
      [has wcs [<wcssys>]]
      [has wcs celestial [<wcssys>]]
      [has wcs linear [<wcssys>]]
 
Example:
string value = ds9.get(string cmd)
frame # returns the id of the current frame
frame frameno # returns the id of the current frame
frame all # returns the id of all frames
frame active # returns the id of all active frames
frame lock
frame has amplifier
frame has datamin
frame has datasec
frame has detector
frame has grid
frame has iis
frame has irafmin
frame has physical
frame has smooth
frame has contour
frame has contour aux
frame has fits
frame has fits bin
frame has fits cube
frame has fits mosaic
frame has marker highlite
frame has marker paste
frame has marker select
frame has marker undo
frame has system physical
frame has wcs wcsa
frame has wcs celestial wcsa
frame has wcs linear wcsa
ds9.set(string cmd)
frame center # center current frame
frame center 1 # center 'Frame1'
frame center all # center all frames
frame clear # clear current frame
frame new # create new frame
frame new rgb # create new rgb frame
frame delete # delete current frame
frame reset # reset current frame
frame refresh # refresh current frame
frame hide # hide current frame
frame show 1 # show frame 'Frame1'
frame move first # move frame to first in order
frame move back # move frame back in order
frame move forward # move frame forward in order
frame move last # move frame to last in order
frame first # goto first frame
frame prev # goto prev frame
frame next # goto next frame
frame last # goto last frame
frame frameno 4 # goto frame 'Frame4', create if needed
frame 3 # goto frame 'Frame3', create if needed
frame match wcs
frame lock wcs

gif

Load GIF image into current frame.

Syntax:
gif [new|slice] [<filename>]
 
Example:
string value = ds9.get(string cmd)
gif
ds9.set(string cmd)
gif foo.gif
gif new foo.gif
gif slice foo.gif
gif
gif new
gif slice

grid

Controls coordinate grid. For grid numeric format syntax,  click here.

Syntax:
grid  []
      [yes|no]
      [type analysis|publication]
      [system <coordsys>]
      [sky <skyframe>]
      [skyformat <skyformat>]
      [grid yes|no]
      [grid color <color>]
      [grid width <value>]
      [grid dash yes|no]
      [grid gap1 <value>]
      [grid gap2 <value>]
      [grid gap3 <value>]
      [axes yes|no]
      [axes color <color>]
      [axes width <value>]
      [axes dash yes|no]
      [axes type interior|exterior]
      [axes origin lll|llu|lul|luu|ull|ulu|uul|uuu]
      [format1 <format>]
      [format2 <format>]
      [tickmarks yes|no]
      [tickmarks color <color>]
      [tickmarks width <value>]
      [tickmarks dash yes|no]
      [border yes|no]
      [border color <color>]
      [border width <value>]
      [border dash yes|no]
      [numerics yes|no]
      [numerics font times|helvetica|courier]
      [numerics fontsize <value>]
      [numerics fontweight normal|bold]
      [numerics fontslant roman|italic]
      [numerics color <color>]
      [numerics gap1 <value>]
      [numerics gap2 <value>]
      [numerics gap3 <value>]
      [numerics type interior|exterior]
      [numerics vertical yes|no]
      [title yes|no]
      [title text <text>]
      [title def yes|no]
      [title gap <value>]
      [title font times|helvetica|courier]
      [title fontsize <value>]
      [title fontweight normal|bold]
      [title fontslant roman|italic]
      [title color <color>]
      [labels yes|no]
      [labels text1 <text>]
      [labels text2 <text>]
      [labels def1 yes|no]
      [labels def2 yes|no]
      [labels gap1 <value>]
      [labels gap2 <value>]
      [labels font times|helvetica|courier]
      [labels fontsize <value>]
      [labels fontweight normal|bold]
      [labels fontslant roman|italic]
      [labels color <color>]
      [reset]
      [load <filename>]
      [save <filename>]
      [open|close]

Example:
string value = ds9.get(string cmd)
grid
grid type
grid system
grid sky
grid skyformat
grid grid
grid grid color
grid grid width
grid grid dash
grid grid gap1
grid grid gap2
grid grid gap3
grid axes
grid axes color
grid axes width
grid axes dash
grid axes type
grid axes origin
grid format1
grid format2
grid tickmarks
grid tickmarks color
grid tickmarks width
grid tickmarks dash
grid border
grid border color
grid border width
grid border dash
grid numerics
grid numerics font
grid numerics fontsize
grid numerics fontweight
grid numerics fontslant
grid numerics color
grid numerics gap1
grid numerics gap2
grid numerics gap3
grid numerics type
grid numerics vertical
grid title
grid title text
grid title def
grid title gap
grid title font
grid title fontsize
grid title fontweight
grid title fontslant
grid title color
grid labels
grid labels text1
grid labels text2
grid labels def1
grid labels def2
grid labels gap1
grid labels gap2
grid labels font
grid labels fontsize
grid labels fontweight
grid labels fontslant
grid labels color
ds9.set(string cmd)
grid
grid yes
grid type analysis
grid system wcs
grid sky fk5
grid skyformat degrees
grid grid yes
grid grid color red
grid grid width 2
grid grid dash yes
grid grid gap1 10
grid grid gap2 10
grid grid gap3 10
grid axes yes
grid axes color red
grid axes width 2
grid axes dash yes
grid axes type exterior
grid axes origin lll
grid format1 d.2
grid format2 d.2
grid tickmarks yes
grid tickmarks color red
grid tickmarks width 2
grid tickmarks dash yes
grid border yes
grid border color red
grid border width 2
grid border dash yes
grid numerics yes
grid numerics font courier
grid numerics fontsize 12
grid numerics fontweight bold
grid numerics fontslant italic
grid numerics color red
grid numerics gap1 10
grid numerics gap2 10
grid numerics gap3 10
grid numerics type exterior
grid numerics vertical yes
grid title yes
grid title text {Hello World}
grid title def yes
grid title gap 10
grid title fontsize 12
grid title font courier
grid title fontweight bold
grid title fontslant italic
grid title color red
grid labels yes
grid labels text1 {Hello World}
grid labels text2 {Hello World}
grid labels def1 yes
grid labels def2 yes
grid labels gap1 10
grid labels gap2 10
grid labels font courier
grid labels fontsize 12
grid labels fontweight bold
grid labels fontslant italic
grid labels color red
grid reset
grid load foo.grd
grid save foo.grd
grid open
grid close

header

Display current fits header dialog. Optional extension number maybe specified. Please note, this differs from samp fits header.

Syntax:
header [<ext>]
       [close [<ext>]]
       [save [<ext>] <filename>]
 
Example:
string value = ds9.get(string cmd)
header
header 2
header close

height

Set the height of the image display window.

Syntax:
height [<value>]
 
Example:
string value = ds9.get(string cmd)
height
ds9.set(string cmd)
height 512

iconify

Toggles iconification.

Syntax:
iconify []
        [yes|no]
 
Example:
string value = ds9.get(string cmd)
iconify
ds9.set(string cmd)
iconify
iconify yes

iexam

Interactive examine function. A blinking cursor will indicate to the user to click on a point on an image. The specified information will be returned at that time. The default event is button. In the last form, the following macros will be expanded if present: $width, $height, $depth, $bitpix, $filename, $regions, $filename[$regions], $env, $pan, $value, $x, $y, $z. See Analysis Macros for more information.

Syntax:
iexam []
      [[]|button|key|any] coordinate <coordsys> [<skyframe>] [<skyformat>]
      [[]|button|key|any] data [width][height]
      [[]|button|key|any] <macro string>]
 
Example:
string value = ds9.get(string cmd)
iexam
iexam coordinate image
iexam key coordinate image # return coordinate and key event
iexam coordinate wcs fk5 degrees
iexam coordinate wcs galactic sexagesimal
iexam coordinate fk5
iexam data # return data value
iexam key data # return data value and key event
iexam data 3 3 # return all data in 3x3 box about selected point
iexam {'Click at $x,$y in file $filename'}

iis

Set/Get IIS Filename. Optional mosaic number maybe supplied.

Syntax:
iis [filename <filename> [#]]
 
Example:
string value = ds9.get(string cmd)
iis filename
iis filename 4
ds9.set(string cmd)
iis filename foo.fits
iis filename bar.fits 4

jpeg

Load JPEG image into current frame. Optional parameters: jpeg quality (1-100)

Syntax:
jpeg [new|slice] [<filename>] [1-100]
 
Example:
string value = ds9.get(string cmd)
jpeg
jpeg 100
ds9.set(string cmd)
jpeg foo.jpeg
jpeg new foo.jpeg
jpeg slice foo.jpeg
jpeg
jpeg new
jpeg slice

lock

Lock all other frames to the current frame.

Syntax:
lock [frame <coordsys>|none]
     [crosshair <coordsys>|none]
     [crop <coordsys>|none]
     [slice <coordsys>|none]
     [bin [yes|no]]
     [axes [yes|no]]
     [scale [yes|no]]
     [scalelimits [yes|no]]
     [colorbar [yes|no]]
     [block [yes|no]]
     [smooth [yes|no]]
     [3d [yes|no]]
 
Example:
string value = ds9.get(string cmd)
lock frame
lock crosshair
lock crop
lock slice
lock bin
lock axes
lock scale
lock scalelimits
lock colorbar
lock block
lock smooth
lock 3d
ds9.set(string cmd)
lock frame wcs
lock crosshair wcs
lock crop wcs
lock slice wcs
lock bin yes
lock axes yes
lock scale yes
lock scalelimits yes
lock colorbar yes
lock block yes
lock smooth yes
lock 3d yes

lower

Lower in the window stacking order.

Syntax:
lower
 
Example:
ds9.set(string cmd)
lower

magnifier

Controls the magnifier settings.

Syntax:
magnifier [color <color>]
          [zoom <value>]
          [cursor yes|no]
          [region yes|no]
 
Example:
string value = ds9.get(string cmd)
magnifier color
magnifier zoom
magnifier cursor
magnifier region
ds9.set(string cmd)
magnifier color yellow
magnifier zoom 2
magnifier cursor no
magnifier region no

mask

Controls mask parameters.

Syntax:
mask [color <color>]
     [mark 1|0]
     [transparency <value>]
     [clear]
     [open|close]
 
Example:
string value = ds9.get(string cmd)
mask color
mask mark
mask transparency
ds9.set(string cmd)
mask color red
mask mark 0
mask transparency 50
mask clear
mask open
mask close

match

Match all other frames to the current frame.

Syntax:
match [frame <coordsys>]
      [crosshair <coordsys>]
      [crop <coordsys>]
      [slice <coordsys>]
      [bin]
      [axes]
      [scale]
      [scalelimits]
      [colorbar]
      [block]
      [smooth]
      [3d]
 
Example:
ds9.set(string cmd)
match frame wcs
match crosshair wcs
match crop wcs
match slice wcs
match bin
match axes
match scale
match scalelimits
match colorbar
match block
match smooth
match 3d

mecube

Load FITS multiple extension file as data cube.

Syntax:
mecube [new] [<filename>]
 
Example:
string value = ds9.get(string cmd)
mecube
ds9.set(string cmd)
mecube foo.fits
mecube new foo.fits
mecube
mecube new

minmax

This is how DS9 determines  the min and max data values from the data. SCAN will scan all data.

Syntax:
minmax [scan|sample|datamin|irafmin]
       [mode scan|sample|datamin|irafmin]
       [interval #]
 
Example:
string value = ds9.get(string cmd)
minmax mode
minmax sample
ds9.set(string cmd)
minmax scan
minmax mode scan
minmax interval 100

mode

Controls the first mouse button mode.

Syntax:
mode [none|region|crosshair|colorbar|pan|zoom|rotate|catalog|examine]
 
Example:
string value = ds9.get(string cmd)
mode
ds9.set(string cmd)
mode crosshair

mosaic

Load FITS mosaic segment into current frame.

Syntax:
mosaic [wcs|wcsa...wcsz|iraf] [new|mask] [<filename>]
 
Example:
string value = ds9.get(string cmd)
mosaic
ds9.set(string cmd)
mosaic foo.fits
mosaic wcs foo.fits
mosaic wcs new foo.fits
mosaic wcs mask foo.fits
mosaic
mosaic wcs
mosaic wcs new
mosaic wcs mask

mosaicimage

Load FITS mosaic image into current frame.

Syntax:
mosaicimage [wcs|wcsa...wcsz|iraf|wfpc2] [new|mask] [<filename>]
 
Example:
string value = ds9.get(string cmd)
mosaicimage
ds9.set(string cmd)
mosaicimage foo.fits
mosaicimage wcs foo.fits
mosaicimage wcs new foo.fits
mosaicimage wcs mask foo.fits
mosaicimage
mosaicimage wcs
mosaicimage wcs new
mosaicimage wcs mask

movie

Create mpeg1 movie from snap shots of the DS9 window. A slice movie cycles though all slices of a cube. A frame movie cycles through all active frames. A 3d movie cycles through specified viewing angles. The default is frame. Optional parameters for 3d: number of frames, azimuth from/to, elevation from/to, slice from/to, oscillate/repeat times.

Syntax:
movie [slice|frame|3d] <filename>
movie 3d <filename> [number|azfrom|azto|elfrom|elto|slfrom|slto|oscillate|repeat <#>]
 
Example:
ds9.set(string cmd)
movie slice ds9.mpg
movie 3d ds9.mpg number 10 azfrom -60 azto 60 oscillate 1

multiframe

Load FITS multiple extension file as multiple images.

Syntax:
multiframe [<filename>]
 
Example:
ds9.set(string cmd)
multiframe foo.fits
multiframe

nameserver

Support Name Server functions. Coordinates are in fk5.

Syntax:
nameserver [<object>]
           [name <object>]
           [server ned-sao|ned-cds|simbad-sao|simbad-cds|vizier-sao|vizier-cds]
           [skyformat degrees|sexagesimal]
           [pan]
           [crosshair]
           [close]
 
Example:
string value = ds9.get(string cmd)
nameserver
nameserver server
nameserver skyformat
nameserver m31
ds9.set(string cmd)
nameserver m31
nameserver name m31
nameserver server ned-sao
nameserver skyformat sexagesimal
nameserver pan
nameserver crosshair
nameserver open
nameserver close

nan

Set image not-a-number color.

Syntax:
nan <color>
 
Example:
string value = ds9.get(string cmd)
nan
ds9.set(string cmd)
nan red

nrrd

Load an NRRD (Nearly Raw Raster Data) file. Optional parameter: array endian.

Syntax:
nrrd [native|little|big]
nrrd [new|mask] [<filename>]
 
Example:
string value = ds9.get(string cmd)
nrrd
nrrd big
ds9.set(string cmd, string url)
nrrd foo.nrrd
nrrd new foo.nrrd
nrrd mask foo.nrrd
nrrd
nrrd new
nrrd mask

nvss

Support for NRAO VLA Sky Survey.

Syntax:
nvss []
     [<object>]
     [name <object>|clear]
     [<ra> <dec>] # in wcs fk5
     [size <width> <height> degrees|arcmin|arcsec]
     [save yes|no]
     [frame new|current]
     [update frame|crosshair]
     [open|close]
 
Example:
string value = ds9.get(string cmd)
nvss name
nvss coord
nvss size
nvss save
nvss frame
ds9.set(string cmd)
nvss
nvss m31
nvss name m31
nvss name clear
nvss 00:42:44.404 +41:16:08.78
nvss size 60 60 arcmin
nvss save yes
nvss frame current
nvss update frame
nvss open
nvss close

orient

Controls the orientation of the current frame.

Syntax:
orient [none|x|y|xy]
       [open|close]
 
Example:
string value = ds9.get(string cmd)
orient
ds9.set(string cmd)
orient xy
orient open
orient close

pagesetup

Controls Page Setup options.

Syntax:
pagesetup [orient portrait|landscape]
          [scale <numeric>]
          [size letter|legal|tabloid|poster|a4]
 
Example:
string value = ds9.get(string cmd)
pagesetup orient
pagesetup scale
pagesetup size
ds9.set(string cmd)
pagesetup orient portrait
pagesetup scale 50
pagesetup size poster

pan

Controls the current image cursor location for the current frame.

Syntax:
pan [<x> <y> <coordsys> [<skyframe>][<skyformat>]] # relative
    [to <x> <y> <coordsys> [<skyframe>][<skyformat>] # absolute
    [open|close]
    [close]
 
Example:
string value = ds9.get(string cmd)
pan # get current image coords
pan wcs fk4 sexagesimal # get current wcs coords
ds9.set(string cmd)
pan 200 200 image # pan relative
pan to 400 400 physical # pan to physical coords
pan to 13:29:55 47:11:50 wcs fk5 # pan to wcs coords
pan open
pan close

pixeltable

Display/Hide the pixel table.

Syntax:
pixeltable []
           [yes|open]
           [no|close]
 
Example:
string url = ds9.get(string cmd)
pixeltable
ds9.set(string cmd)
pixeltable
pixeltable yes
pixeltable open
pixeltable close

plot

Display and configure data plots. All plot commands take an optional second command, the plot name. If no plot name is specified, the last plot created is assumed. Plot data is assumed to be a pair of coordinates, with optional error values. The follow are valid data descriptions:

xy        x and y coordinates
xyex      x,y coordinates with x errors
xyey      x,y coordinates with y errors
xyexey    x,y coordinates with  x and y errors

To create a new plot, use the plot new command.

Syntax:
# create new empty plot window
plot []
     [line|bar|scatter]
     [new]
     [new line|bar|scatter]
     [new name <plotname>]
     [new name <plotname> line|bar|scatter]

# load data into existing plot from stdin
plot [[<plotname>] data xy|xyex|xyey|xyexey]

# existing plot
plot [[<plotname>] load <filename> xy|xyex|xyey|xyexey]
     [[<plotname>] save <filename>]
     [[<plotname>] clear]
     [[<plotname>] duplicate [#]]
     [[<plotname>] stats yes|no]
     [[<plotname>] list yes|no]
     [[<plotname>] loadconfig <filename>]
     [[<plotname>] saveconfig <filename>]
     [[<plotname>] pagesetup orient portrait|landscape]
     [[<plotname>] pagesetup size letter|legal|tabloid|poster|a4]
     [[<plotname>] print]
     [[<plotname>] print destination printer|file]
     [[<plotname>] print command <command>]
     [[<plotname>] print filename <filename>]
     [[<plotname>] print color rgb|gray]
     [[<plotname>] close]
     [[<plotname>] mode pointer|zoom]

# configure graph
plot [[<plotname>] axis x|y grid yes|no]
     [[<plotname>] axis x|y log yes|no]
     [[<plotname>] axis x|y flip yes|no]
     [[<plotname>] axis x|y auto yes|no]
     [[<plotname>] axis x|y min <value>]
     [[<plotname>] axis x|y max <value>]
     [[<plotname>] axis x|y format <string>]
     [[<plotname>] legend yes|no]
     [[<plotname>] legend position right|left|top|bottom]
     [[<plotname>] font title|labels|numbers font times|helvetica|courier]
     [[<plotname>] font title|labels|numbers size <value>]
     [[<plotname>] font title|labels|numbers weight normal|bold]
     [[<plotname>] font title|labels|numbers slant roman|italic]
     [[<plotname>] title <string>]
     [[<plotname>] title x|y <string>]
     [[<plotname>] barmode normal|stacked|aligned|overlap]

# configure current dataset
plot [[<plotname>] show yes|no]
     [[<plotname>] shape circle|square|diamond|plus|splus|scross|triangle|arrow]
     [[<plotname>] shape fill yes|no]
     [[<plotname>] shape color <value>]
     [[<plotname>] smooth step|linear|cubic|quadratic|catrom]
     [[<plotname>] color <value>]
     [[<plotname>] width <value>]
     [[<plotname>] dash yes|no]
     [[<plotname>] error yes|no]
     [[<plotname>] error color <value>]
     [[<plotname>] color <value>]
     [[<plotname>] error width <value>]
     [[<plotname>] name <string>]

# select current dataset
plot [[<plotname>] select <value>]
 
Example:
# return all plotnames
string value = ds9.get(string cmd)
plot

# create new empty plot window
ds9.set(string cmd)
plot
plot bar
plot new
plot new bar
plot new name foo
plot new name foo bar

# load additional dataset into an existing plot
ds9.set(string cmd, string url)
plot data xy # plot additional data
plot foo data xy # plot additional data

string value = ds9.get(string cmd)
plot stats
plot list
ds9.set(string cmd)
plot load foo.dat xy
plot save foo.dat
plot clear
plot duplicate 1
plot stats yes
plot list yes
plot loadconfig foo.plt
plot saveconfig foo.plt
plot pagesetup orient portrait
plot pagesetup size letter
plot print
plot print destination file
plot print command lp
plot print filename foo.ps
plot print color rgb
plot close

string value = ds9.get(string cmd)
plot mode
ds9.set(string cmd)
plot mode pointer

# configure plot
string value = ds9.get(string cmd)
plot axis x grid
plot axis x log
plot axis x flip
plot axis x auto
plot axis x min
plot axis x max
plot axis x format
plot legend
plot legend position
plot font numbers font
plot font numbers size
plot font numbers weight
plot font numbers slant
plot title
plot title x
plot barmode
ds9.set(string cmd)
plot axis x grid yes
plot axis x log yes
plot axis x flip yes
plot axis x auto no
plot axis x min 0
plot axis x max 100
plot axis x format "%f"

string value = ds9.get(string cmd)
plot legend
plot legend position
ds9.set(string cmd)
plot legend yes
plot legend position left

string value = ds9.get(string cmd)
plot font numbers font
plot font numbers size
plot font numbers weight
plot font numbers slant
ds9.set(string cmd)
plot font numbers font times
plot font numbers size 12
plot font numbers weight bold
plot font numbers slant italic

string value = ds9.get(string cmd)
plot title
plot title xaxis
plot title yaxis
ds9.set(string cmd)
plot title "This is a Title"
plot title x "X Axis"
plot title y "Y Axis"
plot title legend "This is the Legend"

string value = ds9.get(string cmd)
plot barmode
ds9.set(string cmd)
plot barmode aligned

# configure current dataset
string value = ds9.get(string cmd)
plot show
plot shape
plot shape fill
plot shape color
plot smooth
plot color
plot width
plot dash
plot error
plot error color
plot error width
plot name
ds9.set(string cmd)
plot show yes
plot shape circle
plot shape fill no
plot shape color cyan
plot smooth step
plot color red
plot width 2
plot dash yes
plot error yes
plot error color red
plot error width 2
plot name "My Data"

# select current dataset
string value = ds9.get(string cmd)
plot select
ds9.set(string cmd)
plot select 2

png

Load PNG image into current frame.

Syntax:
png [new|slice] [<filename>]
 
Example:
string value = ds9.get(string cmd)
png
ds9.set(string cmd)
png foo.png
png new foo.png
png slice foo.png
png
png new
png slice

precision

Set region and coordinate output format precision.

Syntax:
precision <linear> <degree> <hms> <dms> <arcmin> <arcsec>

Example:
string value = ds9.get(string cmd)
precision
ds9.set(string cmd)
precision 8 10 4 3 5 3

prefs

Controls various preference settings.

Syntax:
prefs [clear]
      [irafalign yes|no]
 
Example:
string value = ds9.get(string cmd)
prefs irafalign
ds9.set(string cmd)
prefs clear
prefs irafalign

preserve

Preserve the follow attributes while loading a new image.

Syntax:
preserve [pan yes|no]
         [regions yes|no]
 
Example:
string value = ds9.get(string cmd)
preserve pan
preserve regions
ds9.set(string cmd)
preserve pan yes
preserve regions yes

psprint

Invokes postscript printing. Please see print for further details.

print

Controls printing. Use print option to set printing options.

Syntax:
print [destination printer|file]
      [command <command>]
      [filename <filename>]
      [color rgb|cmyk|gray]
      [level 1|2]
      [resolution 53|72|75|150|300|600]
 
Example:
string value = ds9.get(string cmd)
print destination
print command
print filename
print color
print level
print resolution
ds9.set(string cmd)
print
print destination file
print command lp
print filename foo.ps
print color cmyk
print level 2
print resolution 75

raise

Raise in the window stacking order.

Syntax:
raise
 
Example:
ds9.set(string cmd)
raise

regions

Controls regions in the current frame.

Syntax:
regions [<filename>]
        [load [all] <filename>]
        [save <filename>]
        [list [close]]
        [epsilon <integer>]
        [show yes|no]
        [showtext yes|no]
        [centroid]
        [centroid auto yes|no]
        [centroid radius <value>|iteration <value>]
        [getinfo]
        [move front]
        [move back]
        [select all]
        [select none]
        [select invert]
        [delete all]
        [delete select]
        [format ds9|xml|ciao|saotng|saoimage|pros|xy]
        [system image|physical|wcs|wcsa...wcsz]
        [sky fk4|fk5|icrs|galactic|ecliptic]
        [skyformat degrees|sexagesimal]
        [strip yes|no]
        [shape <shape>]
        [color &ltcolor>]
        [width <width>]
        [fixed|edit|rotate|delete yes|no]
        [include|exclude|source|background]
        [command <marker command>]
        [composite]
        [dissolve]
        [template <filename>]
        [template <filename> at <ra> <dec> <coordsys> <skyframe>]
        [savetemplate <filename>]
        [groups]
        [group new]
        [group <tag> new]
        [group <tag> update]
        [group <tag> select]
        [group <tag> color <color>]
        [group <tag> copy]
        [group <tag> delete]
        [group <tag> cut]
        [group <tag> font <font>]
        [group <tag> move <int> <int>]
        [group <tag> movefront]
        [group <tag> moveback]
        [group <tag> property <property> yes|no]
        [copy]
        [cut]
        [paste image|physical|wcs|wcsa...wcsz]
        [undo]
        [include|exclude|source|background|selected]
        [-format ds9|ciao|saotng|saoimage|pros|xy]
        [-system image|physical|wcs|wcsa...wcsz]
        [-sky fk4|fk5|icrs|galactic|ecliptic]
        [-skyformat degrees|sexagesimal]
        [-prop select|edit|move|rotate|delete|fixed|include|source 1|0]
        [-group <tag>]
        [-strip yes|no]
        [-wcs yes|no]
 
Example:
string url = ds9.get(string cmd)
regions
regions -format ds9 -system wcs -sky fk5 -skyformat sexagesimal -prop edit 1 -group foo
string value = ds9.get(string cmd)
regions epsilon
regions show
regions showtext
regions centroid
regions centroid auto
regions centroid radius
regions centroid iteration
regions selected
regions format
regions system
regions sky
regions skyformat
regions strip
regions shape
regions color
regions width
regions source
regions background
regions include
regions exclude
regions selected
regions groups
ds9.set(string cmd, string url)
regions -format xy -system wcs -sky fk5
regions -format ds9
ds9.set(string cmd)
regions foo.reg
regions -format ciao bar.reg # load as ciao format
regions foo.fits # FITS regions files do not need a format specification
regions load foo.reg # load foo.reg into current frame
regions load all foo.reg # load foo.reg into all frames
regions load *.reg# expand *.reg and load into current frame
regions load all *.reg # expand *.reg and load into all frames
regions save foo.reg
regions list
regions list close
regions epsilon 5
regions show yes
regions showtext no
regions centroid
regions centroid auto yes
regions centroid radius 10
regions centroid iteration 20
regions getinfo
regions move back
regions move front
regions select all
regions select none
regions select invert
regions delete all
regions delete select
regions format ds9
regions system wcs
regions sky fk5
regions skyformat degrees
regions strip yes
regions shape ellipse
regions color red
regions width 3
regions edit yes
regions include
regions command "circle 100 100 20 # color=red"
regions composite
regions dissolve
regions template foo.tpl
regions template foo.tpl at 13:29:55.92 +47:12:48.02 fk5
regions savetemplate foo.tpl
regions group new
regions group foo new
regions group foo update
regions group foo select
regions group foo color red
regions group foo copy
regions group foo delete
regions group foo cut
regions group foo font 'times 14 bold'
regions group foo move 100 100
regions group foo movefront
regions group foo moveback
regions group foo property delete no
regions copy
regions cut
regions paste wcs
regions undo

restore

Restore DS9 to a previous state from a backup save set.

Syntax:
restore <filename>
 
Example:
restore ds9.bck

rgb

Create RGB frame and control RGB frame parameters.

Syntax:
rgb  []
     [red|green|blue]
     [channel [red|green|blue]]
     [view [red|green|blue] [yes|no]]
     [system <coordsys>]
     [lock wcs|crop|slice|bin|scale|scalelimits|colorbar|block|smooth [yes|no]]
     [open|close]
 
Example:
string value = ds9.get(string cmd)
rgb channel
rgb lock wcs
rgb lock crop
rgb lock slice
rgb lock bin
rgb lock scale
rgb lock scalelimits
rgb lock colorbar
rgb lock block
rgb lock smooth
rgb system
rgb view red
rgb view green
rgb view blue
ds9.set(string cmd)
rgb # create new rgb frame
rgb red # set current channel to red
rgb channel red # set current channel to red
rgb view blue no # turn off blue channel
rgb system wcs # set rgb coordinate system
rgb lock wcs yes
rgb lock crop yes
rgb lock slice yes
rgb lock bin yes
rgb lock scale yes
rgb lock scalelimits yes
rgb lock colorbar yes
rgb lock block yes
rgb lock smooth yes
rgb open
rgb close

rgbarray

Load raw data array cube into rgb frame.

Syntax:
rgbarray [native|big|little]
rgbarray [new] [[xdim=<x>,ydim=<y>|dim=<dim>],[zdim=3],bitpix=<b>,skip=<s>,endian=[little|big]]
 
Example:
string value = ds9.get(string cmd)
rgbarray
rgbarray little
ds9.set(string cmd)
rgbarray foo.arr[dim=512,zdim=3,bitpix=-32,endian=little]
rgbarray new foo.arr[dim=512,zdim=3,bitpix=-32,endian=little]

rgbcube

Load FITS rgbcube into rgb frame.

Syntax:
rgbcube [new] [<filename>]
 
Example:
string value = ds9.get(string cmd)
rgbcube
ds9.set(string cmd)
rgbcube foo.fits
rgbcube new foo.fits
rgbcube
rgbcube new

rgbimage

Load FITS rgbimage into rgb frame.

Syntax:
rgbimage [new] [<filename>]
 
Example:
string value = ds9.get(string cmd)
rgbimage
ds9.set(string cmd)
rgbimage foo.fits
rgbimage new foo.fits
rgbimage
rgbimage new

rotate

Controls the rotation angle (in degrees) of the current frame.

Syntax:
rotate [<value>]
       [to <value>]
       [open|close]
 
Example:
string value = ds9.get(string cmd)
rotate
ds9.set(string cmd)
rotate 45
rotate to 30
rotate open
rotate close

samp

Configure SAMP protocol.

Syntax:
samp [no|disconnect]
     [broadcast [image|table]]
     [send [image|table] <application>]
 
Example:
ds9.set(string cmd)
samp no
samp disconnect
samp broadcast image
samp send image aladin

save

Save loaded image data of current frame as FITS.

Syntax:
save [fits|rgbimage|rgbcube|mecube|mosaic|mosaicimage] <filename> [image|table|slice]
 
Example:
ds9.set(string cmd)
save foo.fits
save fits foo.fits image
save fits foo.fits table
save fits foo.fits slice
save rgbimage foo.fits
save rgbcube foo.fits
save mecube foo.fits
save mosaic foo.fits
save mosaicimage foo.fits

saveimage

Create a snap shot of the current DS9 window and save in specified image format. If no format specified, the file name extension is used to determine the output format. Optional parameters: jpeg quality (1-100) and tiff compression method.

Syntax:
saveimage [fits|eps|gif|tiff|jpeg|png] <filename>
saveimage <filename>.jpeg [1-100]
saveimage <filename>.tiff [none|jpeg|packbits|deflate]
 
Example:
ds9.set(string cmd)
saveimage ds9.tiff
saveimage jpeg ds9.jpeg 75

scale

Controls the limits and color scale distribution.

Syntax:
scale [linear|log|pow|sqrt|squared|asinh|sinh|histequ]
      [log exp <value>]
      [datasec yes|no]
      [limits <minvalue> <maxvalue>]
      [mode minmax|<value>|zscale|zmax]
      [scope local|global]
      [match]
      [match limits]
      [lock [yes|no]]
      [lock limits [yes|no]]
      [open|close]
 
Example:
string value = ds9.get(string cmd)
scale
scale log exp
scale datasec
scale limits
scale mode
scale scope
scale lock
scale lock limits
ds9.set(string cmd)
scale linear
scale log exp 100
scale datasec yes
scale histequ
scale limits 1 100
scale mode zscale
scale mode 99.5
scale scope local
scale match
scale match limits
scale lock yes
scale lock limits yes
scale open
scale close

shm

Load a shared memory segment into the current frame.

Syntax:
shm [<key> [<filename>]]
    [key <key> [<filename>]]
    [shmid <id> [<filename>]]
    [fits [key|shmid] <id> [<filename>]]
    [mosaicimage [iraf|wcs|wcsa...wcsz|wfpc2] [key|shmid] <id> [<filename>]]
    [mosaic [iraf|wcs|wcsa...wcsz] [key|shmid] <id> [<filename>]]
    [rgbcube [key|shmid] <id> [<filename>]
    [rgbimage [key|shmid] <id> [<filename>]]
    [rgbarray [key|shmid] <id> [xdim=<x>,ydim=<y>|dim=<dim>,zdim=3],bitpix=<b>,[skip=<s>]]
    [array [key|shmid] <id> [xdim=<x>,ydim=<y>|dim=<dim>],bitpix=<b>,[skip=<s>]]
 
Example:
string value = ds9.get(string cmd)
shm
ds9.set(string cmd)
shm 102
shm key 102
shm shmid 102 foo
shm fits key 100 foo
shm mosaicimage iraf key 100 foo
shm mosaicimage wcs key 100 foo
shm mosaicimage wcsa key 100 foo
shm mosaicimage wfpc2 key 100 foo
shm mosaic iraf key 100 foo
shm mosaic wcs key 100 foo
shm rgbcube key 100 foo
shm rgbimage key 100 foo
shm rgbarray key 100 [dim=200,zdim=3,bitpix=-32]
shm array shmid 102 [dim=32,bitpix=-32]

sia

Support for VO Simple Image Access protocol. The first command will create a new search. All other commands operated on the last search created, unless indicated otherwise.

Syntax:
sia [2mass|akari|astrowise|cadc|cxc|mast|sdss|skyview|tgssadr]

        [<ref>] [cancel]
        [<ref>] [clear]
        [<ref>] [close]
        [<ref>] [coordinate <ra> <dec> <coordsys>]
        [<ref>] [crosshair]
        [<ref>] [export sb|tsv <filename>]
        [<ref>] [name <object>]
        [<ref>] [print]
        [<ref>] [retrieve]
        [<ref>] [save <filename>]
        [<ref>] [radius <value> degrees|arcmin|arcsec]
        [<ref>] [sky <skyframe>]
        [<ref>] [skyformat <skyformat>]
        [<ref>] [system <coordsys>]
        [<ref>] [update]
 
Example:
string value = ds9.get(string cmd)
sia

ds9.set(string cmd)
sia 2mass
sia cancel
sia clear
sia close
sia coordinate 202.48 47.21 fk5
sia crosshair
sia export tsv bar.tsv
sia name m51
sia print
sia retrieve
sia save foo.xml
sia radius 1degrees
sia sky fk5
sia skyformat degrees
sia system wcs
sia update

single

Select Single Display mode

Syntax:
single
 
Example:
string value = ds9.get(string cmd)
single
ds9.set(string cmd)
single

skyview

Support for SkyView image server at HEASARC.

Syntax:
skyview []
        [<object>]
        [name <object>|clear]
        [<ra> <dec>] # in wcs fk5
        [size <width> <height> degrees|arcmin|arcsec]
        [pixels <width> <height>]
        [save yes|no]
        [frame new|current]
        [update frame|crosshair]
        [survey <survey>]
        [open|close]
 
Example:
string value = ds9.get(string cmd)
skyview name
skyview coord
skyview size
skyview pixels
skyview save
skyview frame
skyview survey
ds9.set(string cmd)
skyview
skyview m31
skyview name m31
skyview name clear
skyview 00:42:44.404 +41:16:08.78
skyview size 60 60 arcmin
skyview pixels 600 600
skyview save yes
skyview frame current
skyview update frame
skyview survey sdssi
skyview open
skyview close

sleep

Delays execution for specified number of seconds. Default is 1 second.

Syntax:
sleep [#]
 
Example:
ds9.set(string cmd)
sleep
sleep 2

smooth

Smooth current image or set smooth parameters.
Boxcar width = 2*radius+1
Tophat diameter = 2*radius+1
Gaussian diameter = 2*radius+1, mean =0
Elliptical Gaussian diameter = 2*radius+1, mean =0 Syntax:

smooth []
       [yes|no]
       [function boxcar|tophat|gaussian]
       [radius <value>]
       [radiusminor <value>]
       [sigma <value>]
       [sigmaminor <value>]
       [angle <value>]
       [match]
       [lock [yes|no]]
       [open|close]
 
Example:
string value = ds9.get(string cmd)
smooth
smooth function
smooth radius
smooth radiusminor
smooth sigma
smooth sigmaminor
smooth angle
smooth lock
ds9.set(string cmd)
smooth
smooth yes
smooth function tophat
smooth radius 4
smooth radiusminor 4
smooth sigma 2.0
smooth sigmaminor 2.0
smooth angle 45
smooth open
smooth close
smooth match
smooth lock yes
smooth open
smooth close

source

Source TCL code from a file.

Syntax:
source [filename]
 
Example:
ds9.set(string cmd)
source foo.tcl

tcl

Execute one TCL command.

Syntax:
tcl <tcl command>
 
Example:
ds9.set(string cmd)
tcl {puts {Hello, World}}

threads

Set number of process threads for functions which are multi-threaded.

Syntax:
threads #
 
Example:
string value = ds9.get(string cmd)
threads
ds9.set(string cmd)
threads 8

tiff

Load TIFF image into current frame. Optional parameters: tiff compression method.

Syntax:
tiff [new|slice] [<filename>] [none|jpeg|packbits|deflate]
 
Example:
string value = ds9.get(string cmd)
tiff
tiff jpeg
ds9.set(string cmd)
tiff foo.tiff
tiff new foo.tiff
tiff slice foo.tiff
tiff
tiff new
tiff slice

tile

Controls the tile display mode.

Syntax:
tile []
     [yes|no]
     [mode grid|column|row]
     [grid]
     [grid mode automatic|manual]
     [grid direction x|y]
     [grid layout <col> <row>]
     [grid gap <pixels>]
     [row]
     [column]
 
Example:
string value = ds9.get(string cmd)
tile
tile mode
tile grid mode
tile grid direction
tile grid layout
tile grid gap
ds9.set(string cmd)
tile
tile yes
tile mode row
tile grid
tile grid mode manual
tile grid direction x
tile grid layout 5 5
tile grid gap 10
tile row
tile column

update

Updates the current frame or region of frame. In the second form, the first argument is the number of the fits HDU (starting with 1) and the remaining args are a bounding box in IMAGE coordinates. By default, the screen is updated the next available idle cycle. However, you may force an immediate update by specifying the NOW option.

Syntax:
update []
       [# x1 y1 x2 y2]
       [now]
       [now # x1 y1 x2 y2]
 
Example:
ds9.set(string cmd)
update
update 1 100 100 300 400
update now
update now 1 100 100 300 400

url

Load FITS from URL into the current frame

Syntax:
url <url>
 
Example:
ds9.set(string cmd)
url http://foo.bar.edu/foo.fits

version

Returns the current version of DS9.

Syntax:
version
 
Example:
string value = ds9.get(string cmd)
version

view

Controls the GUI.

Syntax:
view  [layout horizontal|vertical]
      [keyvalue <string>]
      [info yes|no]
      [panner yes|no]
      [magnifier yes|no]
      [buttons yes|no]
      [colorbar yes|no]
      [colorbar horizontal|vertical]
      [colorbar numerics yes|no]
      [graph horizontal|vertical yes|no]
      [filename yes|no[
      [object yes|no]
      [keyword yes|no]
      [minmax yes|no]
      [lowhigh yes|no]
      [units yes|no]
      [image|physical|wcs|wcsa...wcsz yes|no]
      [frame yes|no]
      [red yes|no]
      [green yes|no]
      [blue yes|no]
 
Example:
string value = ds9.get(string cmd)
view layout
view keyvalue
view info
view panner
view magnifier
view buttons
view colorbar
view graph horizontal
view filename
view object
view keyword
view minmax
view lowhigh
view units
view image
view wcsa
view frame
view red
ds9.set(string cmd)
view layout vertical
view keyvalue BITPIX
view info yes
view panner yes
view magnifier yes
view buttons yes
view colorbar yes
view graph horizontal yes
view filename yes
view object yes
view keyword yes
view minmax yes
view lowhigh yes
view units yes
view wcsa yes
view frame yes
view red yes
view green yes
view blue yes

vla

Support for VLA Sky Survey.

Syntax:
vla []
      [<object>]
      [name <object>|clear]
      [<ra> <dec>] # in wcs fk5
      [size <width> <height> degrees|arcmin|arcsec]
      [save yes|no]
      [frame new|current]
      [update frame|crosshair]
      [survey first|stripe82]
      [open|close]
 
Example:
string value = ds9.get(string cmd)
vla name
vla coord
vla size
vla save
vla frame
vla survey
ds9.set(string cmd)
vla
vla m31
vla name m31
vla name clear
vla 00:42:44.404 +41:16:08.78
vla size 60 60 arcmin
vla save yes
vla frame current
vla update frame
vla survey stripe82
vla open
vla close

vlss

Support for NRAO VLSS Sky Survey.

Syntax:
vlss []
     [<object>]
     [name <object>|clear]
     [<ra> <dec>] # in wcs fk5
     [size <width> <height> degrees|arcmin|arcsec]
     [save yes|no]
     [frame new|current]
     [update frame|crosshair]
     [open|close]
 
Example:
string value = ds9.get(string cmd)
vlss name
vlss coord
vlss size
vlss save
vlss frame
ds9.set(string cmd)
vlss
vlss m31
vlss name m31
vlss name clear
vlss 00:42:44.404 +41:16:08.78
vlss size 60 60 arcmin
vlss save yes
vlss frame current
vlss update frame
vlss open
vlss close

vo

Invoke an connection to a Virtual Observatory site.

Syntax:
vo [method xpa|mime]
   [server <url>]
   [internal yes|no]
   [delay #]
   [<url>]
   [connect <url>]
   [disconnect <url>]
   [open|close]
 
Example:
string value = ds9.get(string cmd)
vo
vo method
vo server
vo internal
vo delay
vo connect
ds9.set(string cmd)
vo method xpa
vo server "http://foo.bar.edu/list.txt"
vo internal yes
vo delay 15
vo chandra-ed
vo connect chandra-ed
vo disconnect chandra-ed
vo open
vo close

wcs

Controls the World Coordinate System for the current frame. If the wcs system, skyframe, or skyformat is modified, the info panel, compass, grid, and alignment will be modified accordingly. Also, using this access point, 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 . Please see WCS for more information.

Syntax:
wcs [[system] wcs|wcsa...wcsz]
    [[sky] fk4|fk5|icrs|galactic|ecliptic]
    [[skyformat] degrees|sexagesimal]
    [align yes|no]
    [reset [#]]
    [replace [#] <filename>]
    [append [#] <filename>]
    [open|close]
 
Example:
string value = ds9.get(string cmd)
wcs
wcs system
wcs sky
wcs skyformat
wcs align
ds9.set(string cmd)
wcs wcs
wcs system wcs
wcs fk5
wcs sky fk5
wcs sexagesimal
wcs skyformat sexagesimal
wcs align yes
wcs reset
wcs reset 3
wcs replace foo.wcs
wcs replace 3 foo.wcs
wcs append foo.wcs
wcs append 3 foo.wcs
ds9.set(string cmd, string url)
wcs replace
wcs append
wcs open
wcs close

web

Display specified URL in the web display.

Syntax:
web []
    [<url>]
    [new <webname> <url>]
    [<webname>] [click back|forward|stop|reload|#]
    [<webname>] [clear]
    [<webname>] [close]
 
Example:
string value = ds9.get(string cmd)
web
ds9.set(string cmd)
web www.cnn.com
web new www.cnn.com
web hvweb www.apple.com
web click back
web click 2
web clear
web close

width

Set the width of the image display window.

Syntax:
width [<value>]
 
Example:
string value = ds9.get(string cmd)
width
ds9.set(string cmd)
width 512

zscale

Set Scale Limits based  on the IRAF algorithm.

Syntax:
zscale []
       [contrast]
       [sample]
       [line]
 
Example:
string value = ds9.get(string cmd)
zscale contrast
zscale sample
zscale line
ds9.set(string cmd)
zscale
zscale contrast .25
zscale sample 600
zscale line 120

zoom

Controls the current zoom value for the current frame.

Syntax:
zoom [<value>]
     [<value> <value>]
     [to <value>]
     [to <value> <value>]
     [in]
     [out]
     [to fit]
     [open|close]
 
Example:
string value = ds9.get(string cmd)
zoom
ds9.set(string cmd)
zoom 2
zoom 2 4
zoom to 4
zoom to 2 4
zoom in
zoom out
zoom to fit
zoom open
zoom close