The XPA messaging system provides seamless communication between DS9 and other Unix programs, including X programs and Tcl/Tk programs. It also provides an easy way for users to communicate with DS9 by executing XPA client commands in the shell or by utilizing such commands in scripts. Because XPA works both at the programming level and the shell level, it is a powerful tool for unifying any analysis environment.
about analysis array blink bin colormap contour crosshair cursor dss exit file fits frame iconify lower mode nameserver orient page setup pan raise rass regions rotate scale shm single source tcl tile update version view wcs zoom about
Get DS9 credits.
Syntax:
about
Example:
$xpaget ds9 aboutanalysis
Control external analysis tasks. Tasks are numbered as they are loaded, starting with 0.
Syntax:
analysis [task number]
Example:
$xpaget ds9 analysis
$xpaset -p ds9 analysis 0 # invoke first analysis taskarray
Load raw data array from stdin. If new is specified, a new frame is created first, before loading.
Syntax:
array [new][[xdim=<x>,ydim=<y>|dim=<dim>],bitpix=<b>,[skip=<s>]]
Example:
$cat foo.arr | xpaset ds9 array new [dim=512,bitpix=16]blink
Select Blink Display Mode
Syntax:
blink
Example:
$xpaget ds9 blink
$xpaset -p ds9 blinkbin
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>]
[buffersize <value>]
[cols <x> <y>]
[factor <value>]
[filter <string>]
[function average|sum]
[to fit]
Example:
$xpaget ds9 bin about
$xpaget ds9 bin buffersize
$xpaget ds9 bin cols
$xpaget ds9 bin factor
$xpaget ds9 bin filter
$xpaget ds9 bin function
$xpaset -p ds9 bin about 4096 4096
$xpaset -p ds9 bin buffersize 512
$xpaset -p ds9 bin cols detx dety
$xpaset -p ds9 bin factor 4
$xpaset -p ds9 bin filter "pha>5"
$xpaset -p ds9 bin function sum
$xpaset -p ds9 bin to fitcolormap
Controls the colormap for the current frame. The colormap name is not case sensitive.
Syntax:
colormap [<colormap>]
[invert yes|no]
Example:
$xpaget ds9 colormap
$xpaget ds9 colormap invert
$xpaset -p ds9 colormap Heat
$xpaset -p ds9 colormap invert yescontour
Controls contours in the current frame.
Syntax:
contour [yes|no] | [|copy|paste image|physical|fk4|fk5|icrs|galactic|ecliptic|linear]
Example:
$xpaget ds9 contour
$xpaset -p ds9 contour yes
$xpaset -p ds9 contour copy
$xpaset -p ds9 contour paste fk4crosshair
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 image|physical|fk4|fk5|icrs|galactic|ecliptic|linear]
Example:
$xpaget ds9 crosshair # get crosshair in image coords
$xpaget ds9 crosshair fk4 # get crosshair in wcs coords
$xpaset -p ds9 crosshair 100 100 physical # set crosshair in physical
$xpaset -p ds9 crosshair 345 58.8 fk5 # set crosshair in wcs coords
$xpaset -p ds9 crosshair 23:01:00 +58:52:51 fk5cursor
Move mouse pointer or crosshair in image pixels in the current frame. Note, this will move selected Regions also.
Syntax:
cursor [x y]
Example:
$xpaset -p ds9 cursor 10 10dss
Download image from Digital Sky Survey.
Syntax:
dss [server sao|stsci|eso]
[survey dss|dss2red|dss2blue]
[name <object>]
[x <fk5>]
[y <fk5>]
[width <arcmin>]
[height <arcmin>]
[<object>]
Example:
$xpaget ds9 dss server # get dss server
$xpaset -p ds9 dss m31 # get dss image of m31
$xpaset -p ds9 dss server sao name m31 # set server to sao and get imageexit
Exit DS9. The access point quit is provided for backward compatibiltiy.
Syntax:
exit
Example:
$xpaset -p ds9 exitfile
Load a FITS image,FITS Mosaic image(s), or array from a file into the current frame, or return the current file name(s) loaded for the current frame.
Syntax:
file [<filename>]
[mosaicimage <filename>]
[mosaicimages <filename>]
[mosaic <filename>]
[array <filename>[[xdim=<x>,ydim=<y>|dim=<dim>],bitpix=<b>,[skip=<s>]]]
[save <filename>]
Example:
$xpaget ds9 file
$xpaset -p ds9 file foo.fits
$xpaset -p ds9 file mosaicimage bar.fits
$xpaset -p ds9 file mosaicimages im1.fits
$xpaset -p ds9 file mosaic im3.fits
$xpaset -p ds9 file array r512.arr[dim=32,bitpix=-32]
$xpaset -p ds9 file save foo.fits # save the current frame as FITS Imagefits
Load a FITS image from stdin into the current frame. Options can include the FITS extension or binning instructions. xpaget returns the FITS image in the current frame. If new is specified, a new frame is created before loading.
Syntax:
fits [new][<options>]
Example:
$xpaget ds9 fits > foo.fits
$cat foo.fits | xpaset ds9 fits
$cat abc.fits | xpaset ds9 fits [2]
$cat bar.fits | xpaset ds9 fits new [bin=detx,dety]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] | delete [ |#|all]]
[new | reset [ |#|all] | refresh [ |#|all]]
[hide [ |#|all]| show [#|all]]
[first | next | prev | last | frameno #| #]
Example:
$xpaget ds9 frame # returns the id of the current frame
$xpaget ds9 frame frameno # returns the id of the current frame
$xpaget ds9 frame all # returns the id of all frames
$xpaget ds9 frame active # returns the id of all active frames$xpaset -p ds9 frame 3 # goto frame 'Frame3', create if needed
$xpaset -p ds9 frame frameno 4 # goto frame 'Frame4', create if needed
$xpaset -p ds9 frame first # goto first frame
$xpaset -p ds9 frame next # goto next frame
$xpaset -p ds9 frame prev # goto prev frame
$xpaset -p ds9 frame last # goto last frame
$xpaset -p ds9 frame new # create new frame
$xpaset -p ds9 frame delete # delete current frame
$xpaset -p ds9 frame delete 1 # delete 'Frame1'
$xpaset -p ds9 frame delete all # delete all frames
$xpaset -p ds9 frame reset # reset current frame
$xpaset -p ds9 frame refresh # refresh current frame
$xpaset -p ds9 frame center # center current frame
$xpaset -p ds9 frame hide # hide current frame
$xpaset -p ds9 frame show 1 # show frame 'Frame1'iconify
Toggles iconification.
Syntax:
iconify [yes|no]
Example:
$xpaget ds9 iconify
$xpaset -p ds9 iconify yeslower
Will lower ds9 in the window stacking order.
Syntax:
lower
Example:
$xpaset -p ds9 lowermode
Controls the first mouse button mode.
Syntax:
mode [pointer|crosshair|colorbar|pan|zoom|rotate]
Example:
$xpaget ds9 mode
$xpaset -p ds9 mode crosshairnameserver
Resolve object name into fk5 coordinates.
Syntax:
nameserver [server ned-sao|ned-eso|simbad-sao|simbad-eso]
[format degrees|sexagesimal]
[name <object>]
[<object>]
Example:
$xpaget ds9 nameserver m31 # resolve object name 'm31'
$xpaget ds9 nameserver server # get server
$xpaset -p ds9 nameserver server ned-sao # get server to 'ned-sao'
$xpaset -p ds9 nameserver format sexagesimal # set formatorient
Controls the orientation of the current frame.
Syntax:
orient [none|X|Y|XY]
Example:
$xpaget ds9 orient
$xpaset -p ds9 orient xypage setup
Controls Page Setup options.
Syntax:
page setup [orientation portrait|landscape]
[pagescale scaled|fixed]
[pagesize letter|legal|tabloid|poster|a4]
Example:
$xpaget ds9 page setup orientation
$xpaget ds9 page setup pagescale
$xpaget ds9 page setup pagesize
$xpaset -p ds9 page setup orientation portrait
$xpaset -p ds9 page setup pagescale scaled
$xpaset -p ds9 page setup pagesize posterpan
Controls the current image cursor location for the current frame.
Syntax:
pan [x y image|physical|fk4|fk5|icrs|galactic|ecliptic|linear]
[to x y image|physical|fk4|fk5|icrs|galactic|ecliptic|linear]
Example:
$xpaget ds9 pan # get current image coords
$xpaget ds9 pan fk4 # get current wcs coords
$xpaset -p ds9 pan 200 200 # pan relative
$xpaset -p ds9 pan to 400 400 physical # pan to physical coords
$xpaset -p ds9 pan to 13:29:55 47:11:50 fk5 # pan to wcs coords
Syntax:
print [destination printer|file]
[command <command>]
[filename <filename>]
[palette rgb|cmyk|gray]
[level 1|2]
[interpolate yes|no]
[resolution 53|72|75|150|300|600]
Example:
$xpaget ds9 print destination
$xpaget ds9 print command
$xpaget ds9 print palette
$xpaget ds9 print level
$xpaget ds9 print interpolate
$xpaget ds9 print resolution
$xpaset -p ds9 print # print
$xpaset -p ds9 print destination file -filename foo.ps # set option
$xpaset -p ds9 print palette cmyk # set option
$xpaset -p ds9 print level 2 # set option
$xpaset -p ds9 print interpolate no # set option
$xpaset -p ds9 print resolution 75 # set optionraise
Will raise ds9 in the window stacking order.
Syntax:
raise
Example:
$xpaset -p ds9 raiserass
Download image from ROSAT All Sky Survey.
Syntax:
rass [server mpe]
[survey broad|hard|soft|raw]
[name <object>]
[x <coord>]
[y <coord>]
[system fk4|fk5|icrs|galactic|ecliptic]
[<object>]
Example:
$xpaget ds9 rass server # get rass server
$xpaset -p ds9 rass m31 # get rass image of m31
$xpaset -p ds9 rass server mpe name m31 # set server to mpe and get imageregions
Controls regions in the current frame.
Syntax:
regions [movefront]
[moveback]
[selectall]
[selectnone]
[deleteall]
[file <regions file>]
[format]
[-format ds9|saotng|saoimage|pros]
[coord]
[-coord image|physical|fk4|fk5|icrs|galactic|ecliptic|linear]
[coordformat]
[-coordformat degree|sexagesimal]
[delim]
[-delim nl|semicolon]
<region commands>
Example:
$xpaget ds9 regions
$xpaget ds9 regions -format ds9 -coord fk5 -coordformat sexagesimal
$xpaget ds9 regions format
$xpaget ds9 regions coord
$xpaget ds9 regions coordformat
$xpaget ds9 regions delim
$echo "circle 100 100 20" | xpaset ds9 regions
$echo "circle 13:29:55 47:11:50 .5' fk5" | xpaset ds9 regions
$echo "ellipse 100 100 20 40 physical" | xpaset ds9 regions
$echo "box 100 100 20 40 25" | xpaset ds9 regions
$echo "line 100 100 200 400 image" | xpaset ds9 regions
$echo "ruler 200 300 200 400" | xpaset ds9 regions
$echo "text 100 100 text='Hello, World'" | xpaset ds9 regions
$echo "boxcircle point 13:29:55 47:11:50 fk4" | xpaset ds9 regions
$xpaset -p ds9 regions selectall
$xpaset -p ds9 regions selectnone
$xpaset -p ds9 regions file foo.reg
$xpaset -p ds9 regions format ds9
$xpaset -p ds9 regions coord fk5
$xpaset -p ds9 regions coordformat degrees
$xpaset -p ds9 regions delim nlrotate
Controls the rotation angle (in degrees) of the current frame.
Syntax:
rotate [<value>]
[to <value>]
Example:
$xpaget ds9 rotate
$xpaset -p ds9 rotate 45
$xpaset -p ds9 rotate to 30scale
Controls the limits and color scale distribution.
Syntax:
scale [linear|ln|log|squared|sqrt]
[limits <minvalue> <maxvalue>]
[mode][minmax|zscale|user]
[scope][local|global]
Example:
$xpaget ds9 scale
$xpaget ds9 scale limits
$xpaget ds9 scale mode
$xpaget ds9 scale scope
$xpaset -p ds9 scale log
$xpaset -p ds9 scale limits 1 100
$xpaset -p ds9 scale zscale
$xpaset -p ds9 scale localshm
Load image(s) from a shared memory segment.
Syntax:
shm <key> <size> [<filename>]
shm [key|shmid] <id> <size> [<filename>]
shm mosaicimage [key|shmid] <id> <size> [<filename>]
shm mosaic [key|shmid] <id> <size> [<filename>]
shm array [key|shmid] <id> <size> [[xdim=<x>,ydim=<y>|dim=<dim>],bitpix=<b>,[skip=<s>]]
Example:
$xpaget ds9 shm
$xpaset -p ds9 shm 102 8640
$xpaset -p ds9 shm shmid 102 8640 foo[2]
$xpaset -p ds9 shm mosaicimage key 100 10240 foo
$xpaset -p ds9 shm mosaic key 100 10240 foo
$xpaset -p ds9 shm array shmid 102 8640 [dim=32,bitpix=-32]single
Select Single Display mode
Syntax:
single
Example:
$xpaget ds9 single
$xpaset -p ds9 single
source
Source tcl code from a file.
Syntax:
source [filename]
Example:
$xpaset -p ds9 source foo.tcltcl
Execute one tcl command
Syntax:
tcl [<tcl command>]
Example:
$echo 'puts "Hello, World"' | xpaset ds9 tcltile
Selects/Controls Tile Display Mode.
Syntax:
tile []
[mode grid|column|row]
Example:
$xpaget ds9 tile
$xpaget ds9 tile mode
$xpaset -p ds9 tile
$xpaset -p ds9 tile mode rowupdate
Updates the current frame or region of frame. In the second form, the first argment is the number of the fits HDU (starting with 1) and the remaining args are a bounding box in IMAGE coordindates.
Syntax:
update []
[# x1 y1 x2 y2]
Example:
$xpaset -p ds9 update
$xpaset -p ds9 update 1 100 100 300 400version
Returns the current version of DS9.
Syntax:
version
Example:
versionview
Controls the GUI.
Syntax:
view [info yes|no]
[panner yes|no]
[magnifier yes|no]
[buttons yes|no]
[colorbar yes|no]
[horzgraph yes|no]
[vertgraph yes|no]
[wcs yes|no]
[detector yes|no]
[amplifier yes|no]
[physical yes|no]
[image yes|no]
Example:
$xpaget ds9 view info
$xpaset -p ds9 view info nowcs
Controls the World Coordinate System for the current frame. 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 File Format for more information.Syntax:
wcs [fk4|fk5|icrs|galactic|ecliptic|linear]
[align yes|no]
[format degrees|sexagesimal]
[reset|replace|append|replace file <filename>|append file <filename>]
Example:
$xpaget ds9 wcs
$xpaget ds9 wcs align
$xpaget ds9 wcs format
$xpaset -p ds9 wcs fk4
$xpaset -p ds9 wcs align yes
$xpaset -p ds9 wcs format sexagesimal
$xpaset -p ds9 wcs reset
$xpaset -p ds9 wcs replace foo.wcs
$xpaset -p ds9 wcs append foo.wcs
$cat foo.wcs | xpaset ds9 wcs replace
$cat foo.wcs | xpaset ds9 wcs append
zoom
Controls the current zoom value for the current frame.
Syntax:
zoom [<value>]
[to <value>]
[to fit]
Example:
$xpaget ds9 zoom
$xpaset -p ds9 zoom 2
$xpaset -p ds9 zoom to 4
$xpaset -p ds9 zoom to fit