SAOImageDS9 FAQ SAOImageDS9 FAQThis FAQ is a new, on going project, and it is far from being complete. But as common questions on DS9 are received, the FAQ will be updated.
Contents
Copyright
General
Fonts
Linux
Windows
MacOSX
X11
IRAF
Coordinates
Regions
Printing
XPA
VO
DS9 is composed of approximately 20 open source packages, all of which are distributed under their own open source license agreements, usually GPL, LGPL, or BSD. In addition, several open source packages have been developed here at the Smithsonian Astrophysical Observatory, Cambridge, MA, USA and are distributed under the terms of the GNU General Public License as published by the Free Software Foundation. As long as you continue to adhere to the provisions of the licenses, you are free to distribute DS9 along with your software.
The GNU site contains an excellent FAQ on the the dos and donts of GPL.
The web browser, catalog tool, image server, and other Analysis functions don't appear to work. Whats going on?
For a number of the Analysis functions, DS9 requires temporary disk space to download and store data. By default, this directory is defined by the TMP or TEMP environment variable. This is usually defined as /tmp for Linux and MacOSX users. For Windows users, this will vary, depending on which version of Windows you have. In any case, if the temp directory is not writable, or you have specified an invalid directory in the preferences, these functions will fail with a variety of error messages.
My system admin stripped the DS9 binary and now DS9 fails to start with the following error message:
Application initialization failed: Can't find a usable tk.tcl in the following directories...
DS9 is based on tcl/tk which is a scripting language which requires many support files. To create a stand alone application, we fool tcl/tk into thinking that it has a valid installation. To do this, DS9 is really an application, along with an zip archive attached. The first thing DS9 does is to create a virtual file system in memory and unpack that archive into memory. The application DS9 is already stripped of debugging symbols when built.
It appears that the strip command is stripping part of the archive, hence DS9 is unable to un-compress it. In summary, don't strip the DS9 binary and everything works fine.
When I open my FITS image, all I see is 'white'. Yet everything, including the color bar seems to work?
New with version 2.1, is support for the DATASEC keyword. This keyword specifies what portion of the image is valid data, for calculating min / max and for displaying. This is very important for images created from CCDs with over scan and bias strips. By default, this support is enabled. However, a number of fits images with this keyword, have invalid values. Therefor, when DS9 opens the image, it finds no valid data to display. To correct this problem, either disable DATASEC support, via the Scale menu, or correct the the value of DATASEC in the fits header. You can also change the default behavior by disabling DATASEC from the preferences menu.
Where is the Symbol Font? How do I enter special characters into an entry dialog?
The concept of a separate SYMBOL font is no longer implemented with the latest OS font and scripting support, especially with scalable anti-alias fonts such as Xft for Linux. Most newer fonts (if not all) now have greek characters as part of the font. The greek chars start at unicode \u0391 for 'A' and \u03b1 for 'a'. Each OS has a tool used to build and copy a string of characters. Then use the Edit:Paste menu of DS9 to insert the character string.
Linux- Gnome: gucharmap
Linux- KDE: kcharselect
MacOSX: Character Viewer (Select Edit:Special Characters) Now click and drag the characters to a terminal window. Then select the string and select Edit:Copy.
Windows: Character Map (from Start button, select All Programs, Accessories, System Tools and then Character Map)
My /tmp directory is mounted -noexec and bin table filtering does not work.
Set the environment variable FILTER_TMPDIR to a directory that is both writable and can execute.
I have Red Hat 7, and I'm running KDE. The magnifier keeps going blank after a few seconds, what's going on?
The problem was in KDE. If the user has decided to hide the panel taskbar and sets a delay time for when it appears if the mouse is moved to the panel location, then it appears that KDE creates mouse events that fool DS9 into thinking the mouse is outside and it blanks the magnifier. By turning off the hide panel, the effect goes away. The alternative is to update to KDE2.1Beta where this method of dealing with the hidden panel is not used and all is well, as it was for KDE
I have FreeBSD. When I run ds9, I get the following error: ELF binary type "0" not known Whats going on?
The solution was to use the brandelf utility on the file to ensure that the machine understood that it was a Linux program.
% brandelf -t Linux (file name)
When I do Save Image, I get the same result (and this is true for either .gif, .jpeg, .tiff, .png and .ppm) : it saves only a stripe at the top of my image.
This problem seems to be caused by running DS9 in Windows XP compatibility mode. Please un-check the compatibility option in the properties dialog.
How can I open a FITS file with an extension name?
By default, the windows port of DS9 uses the Windows standard dialog box to open and save files. This can be a problem in that the native Windows dialog will not allow extensions to the file name, such as foo.fits[2]. You must use the Unix like standard dialogs to be able to specify an extension. Select Edit->Preferences->General:Dialogbox to change the default standard dialog.
Every time I create an auxiliary window in ds9, such as a Pixel Table, or Analysis Plot, it will retreat behind the main ds9 window. Then, when I bring the auxiliary window to the front and move the mouse out of it, it automatically goes behind the main ds9 window again. What can I do to fix things so that the auxiliary window stays on top of the ds9 window?
To fix things so that the auxiliary window stays on top of the ds9 window, do the following:
Go to the icon task bar at the bottom of the screen. Bring the auxiliary window to the front by clicking on its icon in the icon task bar. While the mouse still is on the aux window icon, press the mouse button, and keeping it pressed, move the mouse off the task bar. Release the mouse while off the task bar. The auxiliary window will now stay on top of the main ds9 window.
I can't invoke the 'Save Image' function from the MacOSX X11 version. I get an error message "An error has occurred while creating the image. Please make sure entire image is visible on screen."
Up until MacOSX 10.8 (Mountain Lion), Apple provided their own version of a X11 server. At first, it was based on XFree86 (X11R6.6) and available with versions up to MacOSX 10.4. Later with MacOSX versions 10.5 to 10.7, the Apple's X11 server was based upon X.org (X11R7.2).
The Apple version of X11 server for MacOSX 10.5 to 10.7 contains a bug which fails if you invoke certain X11 calls on a window if its location is not at 0,0 on the screen. Hence, within DS9, if you 'Save Image' and your window is not exactly in the upper left corner, it will fail.
Again, this only affects users of MacOSX 10.5 to 10.7.
Starting with MacOSX 10.8, Apple no longer provides a X11 window server. The user must go to the XQuartz site and download/install directly. The current version is 2.7.3.
When I invoke DS9 MacOSX Aqua from the command line, I get weird errors such as:
The document "foo.fits" could not be opened. SAOImage DS9 cannot open files in the "Flexible Image Transport System" format.
When opening MacOSX Aqua from the command line, it is better to use the OPEN application as opposed to specifying the binary directly. The OPEN application sets up the environment just as it is when a user double clicks.
# good
% open /Applications/SAOImage\ DS9.app foo.fits
# bad
% /Applications/SAOImage\ DS9.app/Contents/MacOS/ds9 bar.fits
How can I open a FITS file with an extension name?
By default, DS9 MacOSX Aqua uses the MacOSX standard dialog box to open and save files. This can be a problem in that the native MacOSX dialog will not allow extensions to the file name, such as foo.fits[2]. You must use the Unix like standard dialogs to be able to specify an extension. Select Edit->Preferences->General to change the default standard dialog.
How do I set my PATH environment variable under MacOSX for use with external analysis programs, such as funtools?
When you double click on a MacOSX application, it does not parse any shell startup files, such as ~/.profile. Instead, the environment is defined using a special environment file, .MacOSX/environment.plist. This file can be created with the MacOSX utility /Developer/Applications/PropertyListEditor.app. For further information, please click here.
Is it possible to work in batch mode without a physical display?
DS9 is written as an interactive, window client program, and as a result, does require a window server to be available for rendering (X11, Windows, or MacOSX).
Therefore, using DS9 as a batch process can be cumbersome. We recommend using xvfb under X11. Just set up a virtual display buffer, reset your DISPLAY variable, then invoke DS9 with a number of command line options or use xpa from a shell script as a batch processor. Example:
% export DISPLAY=:1
% Xvfb :1 -screen 0 1024x768x16 &
% ds9 -file cmap.fits -zoom to fit -cmap b -grid skyformat degrees -grid yes -regions ../EMS-names.reg -saveimage png mytest.png -exit
When I start DS9, I get the following error message:
_X11TransSocketINETConnect: Can't get address for foo.bar.edu
couldn't connect to display "foo.bar.edu:0.0"
DS9 is unable to determine a valid X11 Display server, because of a number of reasons. Most often this is seen when you have a laptop configured for a network, but is not physically connected. You need to set the DISPLAY environment variable to :0.0
$ xhost +
$ set DISPLAY=:0.0
$ export DISPLAY
Under Solaris, when I start DS9, my twm window manager crashes!
TWM distributed with X11R5 had a major bug, that was corrected around 1996. DS9 will trigger this bug, and will cause TWM to crash. If you are running Solaris, and have X11R5 installed, be sure that /usr/openwin/bin is in your path before X11R5/bin. This will insure that you are running the correct version of TWM .
When I run ds9 with the tvtwm window manager, sometimes the open file dialog box does not appear?
If you are running tvtwm, and you are currently viewing a virtual screen other than the first, when you open a file, the dialog box will appear in the first virtual screen, not your current. This is a bug with tvtwm and not ds9.
I can't use more than 9 frames with the IMEXAMINE task?
The task IMEXAMINE can not be used with frame numbers greater than 9.
Can I display from IRAF to DS9 running under Windows or MacOSX?
Yes, DS9 for Windows and MacOSX is also a fully functional IRAF display server. To direct image output from IRAF to DS9 running under Windows or MacOSX, use the IMTDEV environment variable. For example, if the machine is named 'foo.bar.edu', define IMTDEV to the follow value before entering IRAF.
$ setenv IMTDEV inet:5137:foo.bar.edu
$ cl
cl> display dev$pix
I'm having problems with mscred task msczero?
DS9 now supports IRAF's new IIS image display protocol. However, there is one minor problem with the mscred task msczero. Before using msczero, issue the following command in the cl:
cl> set disable_wcs_maps=""
cl> flpr
I find that there is a frustrating delay in performing operations on images displayed from IRAF - there's a wait of a second or two before an image is (re)displayed, whereas saoimage reacts virtually instantly for the same type of operation. This makes running imexamine on a batch of images a pain, and using the mouse to change color gamma/bias to desired values basically impossible.
DS9 and saoimage are similar in speed when working with IRAF. In fact, DS9 uses the same code to interface with IRAF as saoimage and ximtool. The only difference is that DS9 is double buffered, whereas, saoimage and ximtool only use a single buffer. So with saoimage and ximtool, you see incremental progress, where DS9 will render the image all at one time. However, the overall time to finish rendering should almost be the same.
DS9 runs in both 8 bit and 24 bit environments, but saoimage is restricted to 8 bit. If you are running DS9 and saoimage at the same time, then you must be in 8 bit mode. You should not see any delay in changing the color bias/contrast between the two.
However, if you are running DS9 in 24 bit mode, then you will see slower performance in changing the bias/contrast, as compared to 8 bit mode. Instead of changing a color look up table, as in 8 bit mode, DS9 has to update every pixel on the screen. If your cpu speed is slow, you can select the Edit:Preferences:True Colorbar to tell DS9 not to update the entire screen, only a part of the screen. This should only be needed if your machine is slower than 200 MHz. Again saoimage does not even run in 24 bit mode, so there are no comparisons.
I try to display an image from IRAF and I get the following error message:
Cannot open device (node!imtool,,512,512)
DS9 works the same way as ximtool, saoimage, and saotng. No special scripts should be needed. If you have one of the above currently working, DS9 should work out of the box.
IRAF can use one of three methods to communicate with DS9: fifo, socket, and unix domain name. The DS9 defaults are:
fifo /dev/imt1
port 5137
unix /tmp/.IMT%dIf your IRAF configuration is set up different (i.e., a different port number, or via a fifo), you need to tell DS9 how to communicate with iraf. DS9 uses the same command line options as XIMTOOL:
-fifo
-fifo_only
-inet_only
-port
-port_only
-unix
-unix_only
I try to display an image, I see something, but it's corrupted and I get multiple error messages from DS9...
An IRAF image server (ximtool, saoimage, DS9, etc...) uses a configuration file to specify the number of available buffers and their sizes. What actually passes from IRAF is not the buffer size, but an index number into this file.
So when an image server starts (DS9), it will attempt to locate this file as $HOME/.imtoolrc and /usr/local/lib/imtoolrc. If not found, it will look for shell environment variables IMTOOLRC and imtoolrc, that contains the name of the configuration file.
If no configuration file is found, DS9 will assume the following default configuration:
1 2 512 512 # imt1|imt512
2 2 800 800 # imt2|imt800
3 2 1024 1024 # imt3|imt1024
4 1 1600 1600 # imt4|imt1600
5 1 2048 2048 # imt5|imt2048
6 1 4096 4096 # imt6|imt4096
7 1 8192 8192 # imt7|imt8192
8 1 1024 4096 # imt8|imt1x4
9 2 1144 880 # imt9|imtfs full screen (1152x900 minus frame)
10 2 1144 764 # imt10|imtfs35 full screen at 35mm film aspect ratio
11 2 128 128 # imt11|imt128
12 2 256 256 # imt12|imt256
13 2 128 1056 # imt13|imttall128 tall & narrow for spectro.
14 2 256 1056 # imt14|imttall256 tall & wider for spectro.
15 2 1056 128 # imt15|imtwide128 wide & thin for spectro.
16 2 1056 256 # imt16|imtwide256 wide & fatter for spectro.
17 2 1008 648 # imt17|imtssy Solitaire fmt w/ imtool border
18 2 1024 680 # imt18|imtssn Solitaire fmt w/out imtool border
19 1 4096 1024 # imt19|imt4x1
If on the other hand, IRAF assumes a different buffer size, the image will appear corrupted and DS9 may issue a number of error messages.
Another problem is that this file must be in sync with dev$graphcap. If your system administrator has made changes to graphcap, they must also be implemented in imtoolrc.
Here is a note from NOAO:
The messages means that there is no /usr/local/lib/imtoolrc file on the machine. This is created as a symlink to dev$imtoolrc by the iraf install script but only if the /usr/local/lib dir already exists on the machine. The fix is the create the dir and rerun the install script or else make the link by hand. Users can also just copy dev$imtoolrc to $HOME/.imtoolrc and restart the server to also workaround it. Note that an existing .imtoolrc might define old frame buffer configs which might confuse things, so if the system file exists check for a private copy screwing things up.
Where do I find this .imtoolrc file?
Again, here a note from NOAO concerning this issue:
In a smooth installation the imtoolrc file is installed as a /usr/local/lib/imtoolrc symlink pointing to the dev$imtoolrc file in the iraf system. This is normally what's used but XImtool (and DS9?) also allow a $HOME/.imtoolrc and IMTOOLRC environment variable defining the path as fallbacks. There are several practical problems with this: for some reason (I'm trying to fix) the imtoolrc link won't be created if the /usr/local/lib directory doesn't exist when the install script is run on the machine, even though it's run as root and the file can be directory easily. On PC-IRAF systems there is also a typo in the install script (extra logical or at line 515) which causes it to exit before the display setup is run (i.e. no /dev fifos or imtoolrc). If users don't catch this or see it in the README file they'll think everything went fine. Lastly, the local iraf admin might not have run the install script on the local iraf NFS client machine at all.
When I display an image from IRAF, the SCALE menu option is not active, Why?
When you display an image from IRAF into DS9, IRAF actually does the color scale distribution. In Display, use the ztrans and z1,z2 parameters to set the upper/lower bounds and distribution. You can also use the zscale parameter to auto determine z1,z2.Here are the DISPLAY parameters in question:
ztrans=[linear|log|none|user]
z1=min
z2=max
zscale=[yes|no]What actually is sent from IRAF to DS9 is one byte per pixel, values 0-200, which already has applied both the upper and lower clipping bounds and the distribution. So this is why, the SCALE menu is disabled in DS9 when it receives a image from IRAF.
Why don't I see PHYSICAL/WCS/WCSA...WCSZ coordinates displayed when I load my image?
DS9 supports the following coordinate systems:
WCS Sky coords (fk4,fk5,icrs,galactic,ecliptic)
WCS Linear coords
Image (also known as Logical)
Physical (also known as CCD)
Detector
Amplifier
DS9 uses the following FITS keywords in the header to define a coordinate system:
Coordinate System Keyword Values WCS / WCSA...WCSZ CRVAL,CRPIX,CRDELT,CD... (for images)
TCRVL,TCRPX,TCDLT,... (for tables)Image none required Physical WCSNAMEP='PHYSICAL' or LTMx_x/LTVx Detector
DTMx_x/DTVx
Amplifier
ATMx_x/ATVx
If the required keywords are not present, values for those coordinates are not displayed.
Note: For PHYSICAL, DS9 will first look for an alternative WCS with WCSNAMEx='PHYSICAL'. If not found, DS9 will then look for the LTMx_x LTVx keywords.
How do I indicate distance on my printed images?
You have two choices, the RULER region and the LINE region. The ruler region is mainly used for interactive measurements. For printed output, use the LINE region to create a distance indicator. In the line region dialog, there is a read-only entry that indicates the length in pixels, degrees, arcmin, or arcsec. Edit to the desired distance and enter the desired label, including ' or ", in the region text labile entry. You have the option of arrows at each end of the line.
I can make some wonderful color images in DS9 and save them as postscript files that look great, but often when I print them they appear washed out or very different than they do on the screen. My question then is what, if anything, can I do about this?
The problem is that you create an image on a display, which is the product of RGB colors (red, green, and blue) and print the image on a printer, which is the product of CMYK colors (cyan, yellow, magenta, and black). Furthermore, every monitor is different in how it will display a certain color, and every printing technology is different in how well it will reproduce that color. And finally, the translation between RGB and CMYK is not symmetric, i.e. its not possible to translate some colors back and forth.
It's possible to calibrate your monitor and your printer, to create a translation matrix, to correct for problems outlined above (in the Macintosh world, this is what ColorSync does). The idea is to apply a gamma correction to the output of DS9, so that it will print much more in line with what you expect. To do this you'd need special software and hardware, and its only valid for your monitor and your printer.
In summary, its not worth it. Especially in the case of publication, such as ApJ, where you have no idea on what printing technology will be used to reproduce your image. So the only control you have is to calibrate your monitor and to hope for the best.
However, there are some rules of thumb that might help. First, printers have a very hard time with blues and purples, as they tend to be washed out. Either avoid these colors, or over compensate these colors.
ApJ has a good idea in that you send in both an electronic version and a hard copy of your color image. That way, they can manually adjust the printers to try to match your output.
NOTE: Even though ApJ requests images in CMYK, we recommend RGB. From personal experience, if you send RGB, the printed results will be closer to the original.
We used DS9 to generate 300 dpi CMYK eps figures, as per the ApJ specifications, but the color scheme on our proofs is wrong. In the proofs, the violet is washed out and looks similar to the black, and the blue is not nearly as intense.
There are two issues here: first, color printers are notorious for failure to reproduce blues and purples correctly. Second, not all colors in RGB space can be reproduced correctly in CMYK space, blues being the prime example. Below is an excerpt from an industry pamphlet:
Be aware that it is possible to see colors in RGB that you can't make with CMYK. They are said to be "out of the CMYK color gamut". What happens is that the RGB-to-CMYK translator just gets as close as possible to the appearance of the original and that's as good as it can be. It's something that everyone in the industry puts up with. So it's best to select any colors you use for fonts or other design elements in your layout using CMYK definitions instead of RGB. That way, you will have a better idea of how they will appear in your printed piece. Here's a common example: many programs translate the 100% Blue in RGB into a somewhat purple-looking color in CMYK. We recommend a CMYK value of 100-65-0-0 to get a nice clean blue.
For this reason, you may wish to use the RGB color space or colormaps without deep blues and purples, such as BB or Heat.
How can I use XPA to display from a client machine to DS9 on a server machine?
Assuming you have direct IP reachability between the machines (i.e. one host can successfully connect() to the other), XPA does allow you to have an XPA-enabled server like DS9 on one machine and a client on another. To make this work, you need to do two things (let's assume DS9 is running on a machine called "server_host" and you want to send xpa commands from "client_host"):
- The XPA server program (i.e. DS9) must allow the client host to send XPA commands. Access can be permitted in one of two ways:
- Send the XPA server an acl request by running xpaset on the same host on which the server is running (i.e. on the server_host):
% xpaset -p ds9 -acl client_host +
- For more permanent access, add permissions in ~acls.xpa:
% cat > ~/acls.xpa
DS9:ds9 client_host +
You can check the acls for an XPA server using xpaget:
% xpaget ds9 -acl
- On the client side, the client needs to communicate with the xpansname server program on the server machine to find the XPA server communication info. This also can be done in two ways:
- use the -i [host] switch to override XPA_NSINET for this execution (The default port is 14285):
% xpaget -i 'server_host:14285' ds9
- Set the XPA_NSINET variable for more permanent selection of xpans on the server host:
% setenv XPA_NSINET 'server_host:14285'
Once these two setup steps are performed, you should be able to send commands to DS9 and receive data from DS9. You can look at the xpaacl man page for more information.
I have a laptop, that most of the time, is connected to a network. DS9 runs fine. However, when I'm not connected to a network and I start DS9, it hangs. What's going on?
DS9 uses XPA for interprocess communication. When DS9 starts, XPA initializes itself. XPA uses either IP sockets or UNIX sockets, based if your machine is configured to connect to the internet. In the case where your machine is configured for the internet, but you are not currently connected, XPA gets very confused. So, you can define a shell variable, XPA_METHOD, that tells XPA which method to use.
The following is from the XPA documentation:
Determines the socket connection method used by this session of XPA. The choices are: inet (to use INET or Internet-based sockets) and local (unix) (to use UNIX sockets). The default is INET. Using the inet method will allow access from other machines (subject to access controls) but using local will not. Local is most useful for private access and when the machine in question is not connected to the Internet
More information is available on XPA shell variables at: The XPA Environment
I can't connect to any of the virtual observatories. What do I do now?
The DS9 help facility now contains a tutorial on how to configure DS9 to by pass network firewalls. See Virtual Observatory Reference for more information.