ds9 is an image viewing application and xpa is a means by which one can command ds9 from another process. These comments apply to ds9 verson 3.0.3 but may be updated as newer versions are released.
After having spent many frustrating hours trying to write a cross-platform program that commands ds9 via xpa (RO.DS9, part of the RO python utility package), I've written up a guide to some of the stranger aspects. See that code for an implementation of the techniques discussed here.
The main issue for controlling ds9 from xpa is whether xpa can find ds9. Normally ds9 registers itself with xpans when ds9 starts up. However, if ds9 cannot find xpans then this does not occur and xpaget and xpaset cannot find ds9.
On unix, as long as xpans is on your PATH there is no problem. Unfortunately, things are much harder on MacOS X and Windows.
As of ds9 3.0.3, there is a MacOS X version: ds9.app, an application bundle. Some Mac users may prefer to install the darwin version (and there is essentially no difference between the two). Issues include:
path to application appname, does not work for ds9 3.0.3, presumably due to a bug in bundling ds9.
My solution for controlling ds9 via xpa from a program is as follows. If you do this then ds9 can find xpans when it starts. and you can run ds9 and xpa without worrying about where they live.
The installer, by default, puts ds9 in C:\Program Files\ds9\ and xpa in C:\Program Files\xpa\. Unfortunately, when you launch ds9 3.0.3 from the command line, it cannot find xpans in this configuration (unless xpans is already running).
For command-line use of xpa with ds9, the simplest solution is to move the xpa executables with ds9 (i.e. xpaget.exe, etc. go into the directory as ds9.exe). (Oddly enough, it does NOT suffice to put xpa on the PATH.)
As a result, my solution for controlling ds9 via xpa from a program is as follows. If you do this then ds9 can find xpans when it starts. and you can run ds9 and xpa without worrying about where they live.
ds9 only has one window. To get multiple windows launch ds9 multiple times. However, if you launch ds9 with no arguments you will find it challenging to communicate with any other than the first copy you launched.
The simplest workaround is to specify a unique title and a port of 0 whenever you launch a ds9 (if you use the default port then the 2nd and later copies of ds9 will complain that the port they want is in use and you will only be able to communicate with the first ds9 you launched). Then you can reference each ds9 window by its name. For example:
% ds9 -title foo -port 0 % xpaget foo mode
To tell ds9 to open a file whose name or path includes spaces, surround the path with "{...}", e.g.
% xpaset -p ds9 file "{foo bar/my image.fits}"
Windows is a special case (surprise): backslashes in the path name must be replaced by forward slashes else the file command will fail. Fortunately Windows does not allow forward slashes in file names, so this does not reduce its ability to open files. That also means the bug could easily be fixed while retaining backwards compatibility by simply allowing / or \ to mean \.
On Windows under ds9 3.0.3 the command xpaset ds9 array [arrayinfo] (where the array data is then piped to xpaset's stdin) does not work. It appears that the data is being carriage-return translated (not a good idea for binary data). Kudos to Craig Loomis for identifying the problem.
On MacOS X (and so almost certainly any unix) I have not been able to load binary files under ds9 3.0.3 using the command xpaset -p ds9 file array filepath[arrayinfo]; I always get an error saying the file could not be loaded. This may be due to an error on my part, but I had it working with an earlier version of ds9.
ds9 supports the same data types as the FITS standard, an eclictic mix:
ds9 has a number of bugs and quirks that you must watch out for when commanding it via xpa.
Bugs (as of ds9 3.0.3):
Quirks:
Thanks to Eric Mandel for extensive help with ds9 and xpa. Much of this document is based directly on his suggestions and very little of it would have been possible without his help.
Thanks to Sander Tekelenburg for the applescript command "path to application ds9". He also supplied a bash shell version: osascript -e "path to application \"Finder\"" (this runs under bash but not tcsh).