XPA
Access Points
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
block
colormap
contour
crosshair
cursor
exit
file
fits
frame
iconify
mode
mosaicimage
orient
page setup
pan
print
regions
rotate
scale
source
tcl
tile
version
view
wcs
zoom
about
Get DS9 credits.
Syntax:
about
Example:
$xpaget ds9 about
analysis
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 task
array
Load raw data array.
Syntax:
array [xdim=<x>,ydim=<y>,bitpix=<b>,skip=<s>]
Example:
$cat foo.arr | xpaset ds9 array "[dim=512,bitpix=16]"
blink
Toggles Blink Mode
Syntax:
blink [yes|no]
Example:
$xpaget ds9 blink
$xpaset -p ds9 blink yes
block
Controls blocking factor, blocking buffer
size, and blocking function for binning FITS bin tables. The access
point blocking is provided for backward compatibility.
Syntax:
block [buffersize <value>]
[factor <value>]
[function average|sum]
[to fit]
Example:
$xpaget ds9 block factor
$xpaget ds9 block buffersize
$xpaget ds9 block function
$xpaset -p ds9 block factor 4
$xpaset -p ds9 block buffersize 512
$xpaset -p ds9 block function sum
$xpaset -p ds9 block to fit
colormap
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 yes
contour
Controls contours in the current frame.
Syntax:
contour [yes|no|new|copy|paste <coordinate system>|clear]
Example:
$xpaget ds9 contour
$xpaset -p ds9 contour yes
$xpaset -p ds9 contour new
$xpaset -p ds9 contour copy
$xpaset -p ds9 contour paste fk4
$xpaset -p ds9 contour clear
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 <coordinate system>]
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 fk5
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:
$xpaset -p ds9 cursor 10 10
exit
Exit DS9. The access point quit is
provided for backward compatibiltiy.
Syntax:
exit
Example:
$xpaset -p ds9 exit
file
Load a FITS image or FITS Mosaic image(s)
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>]
Example:
$xpaget ds9 file
$xpaset -p ds9 file foo.fits
$xpaset -p ds9 file mosaicimage bar.fits
fits
Load a FITS image from xpa into the current
frame. Options can include the FITS extension or binning instructions.
Syntax:
fits [<options>]
Example:
$xpaget ds9 fits
$cat foo.fits | xpaset ds9 fits
$cat abc.fits | xpaset ds9 fits [2]
$cat bar.fits | xpaset ds9 fits [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|clear|delete|new|reset|refresh|hide|show #|frameno
#|#]
Example:
$xpaget ds9 frame # returns the id number of the current frame
$xpaget ds9 frame frameno # returns the id number of the current
frame
$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 new
$xpaset -p ds9 frame delete
$xpaset -p ds9 frame reset
$xpaset -p ds9 frame refresh
$xpaset -p ds9 frame center
$xpaset -p ds9 frame hide
$xpaset -p ds9 frame show 1 # show frame 'Frame1'
iconify
Toggles iconification.
Syntax:
iconify [yes|no]
Example:
$xpaget ds9 iconify
$xpaset -p ds9 iconify yes
mode
Controls the first mouse button mode.
Syntax:
mode [pointer|crosshair|colorbar|pan|zoom|rotate]
Example:
$xpaget ds9 mode
$xpaset -p ds9 mode crosshair
mosaicimage
Load a FITS multiple extension mosaic image
from xpa into the current frame. NOTE: this is different from the FITS
xpa point. Each FITS extension must be a valid FITS mosaic image.
Syntax:
mosaicimage
Example:
$xpaget ds9 mosaicimage
$cat foo.fits | xpaset ds9 mosaicimage
orient
Controls the orientation of the current frame.
Syntax:
orient [none|X|Y|XY]
Example:
$xpaget ds9 orient
$xpaset -p ds9 orient xy
page 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 poster
pan
Controls the current image cursor location
for the current frame.
Syntax:
pan [x y <corrdinate system>]
[to x y <corrdinate system>]
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
print
Controls printing. Use print -option to set
printing options. Use print to actually print.
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 option
regions
Controls regions in the current frame.
Syntax:
regions [movefront]
[moveback]
[selectall]
[selectnone]
[deleteall]
[file <regions file>]
[format ds9|saotng|saoimage|pros]
[coord <coordinate
system>]
[coordformat degree|hms]
<region commands>
Example:
$xpaget ds9 regions
$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 "rectangle 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 coord fk5
$xpaset -p ds9 regions coordformat hms
rotate
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 30
scale
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 local
source
Source tcl code from a file.
Syntax:
source [filename]
Example:
$xpaset -p ds9 source foo.tcl
tcl
Execute one tcl command
Syntax:
tcl [<tcl command>]
Example:
$echo 'puts "Hello, World"' | xpaset ds9 tcl
tile
Controls Tile Mode.
Syntax:
tile [yes|no}
[mode grid|column|row]
Example:
$xpaget ds9 tile
$xpaget ds9 tile mode
$xpaset -p ds9 tile yes
$xpaset -p ds9 tile mode row
version
Returns the current version of DS9.
Syntax:
version
Example:
version
view
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 no
wcs
Controls the World Coordinate System for the
current frame.
Syntax:
wcs [fk4|fk5|galactic|ecliptic]
[align yes|no]
[format degrees|hms]
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 hms
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