SAOImage DS9 FAQ
SAOImage DS9 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
General
Grids
IRAF
Coordinates
Regions
Printing
X11
XPA
Linux
Windows
Netscape
VO
General
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 uncompress 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 colorbar 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.
Grids
When displaying a coordinate grid, the rendered grid is incorrect, or I receive an error message. How can I fix this?
Displaying a valid grid is a complicated process and a lot can go wrong. One of the most common problem is a conflict in defining certain projections in older FITS files. You can tell DS9 to use the old AIPS Projections code by selecting the following menu item 'Edit:Preferences:Misc:Use AIPS Projections'
IRAF
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.
Can I display from IRAF to DS9 running under Windows 95/98/ME/NT/2000
Yes, DS9 Windows is also a fully functional IRAF display server. To direct image output from IRAF to DS9 running under windows, use the IMTDEV environment variable. For example, if the windows 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
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.
Coordinates
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)
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 LTM, LTV 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.
Regions
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.
Printing
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.
X11
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.
XPA
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
Linux
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 (filename)
Windows
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 filename, such as foo.fits[2]. You must use the Unix like standard dialogs to be able to specify an extension. Select Edit->Preferences->DialogBox to change the default standard dialog.
I have Windows 98. All line graphics, such as regions and contours appear corrupted. What's going on?
The problem is with Windows 98 and your video driver. If you turn off the video driver optimization, the problem will be corrected. To do so, select Start:Settings:ControlPanel:Display. This will bring up the Display Properties dialog box. Select the tab Settings, and press the Advanced button. Now, select the Performance tab. This problem appears to be most common for laptops.
How to I configure windows to automatically start DS9 when I double click on a fits file?
The following instructions are for Windows 2000. The procedure for other versions of windows should be similar. First, ds9 needs to be installed in the C:\Program Files\ds9 directory (this is the default location).
Next click on the Startup button, and select the Settings menu item. Now select the Control Panel menu item. Next, double click on Folder Options. This will bring up a dialog box. Click once on the File Types tab.
Now click once on the New button. Enter FITS and click on the OK button. Now click once on the Change button. Select ds9 from the list, and click the OK button. Finally, click once on the Close button. All done. Now, when you double click on any file with an extension of FITS will open within DS9.
Everytime 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.
Netscape
I am unable to configure DS9 as a "helper application" for viewing FITS files in Netscape or Mozilla. Is this possible?
Yes, it is easy to configure Netscape or Mozilla to automatically invoke ds9, when downloading a fits file. These instructions are for Netscape 4.x. Other versions follow a similar process: From the Edit menu, select Preferences. In the dialog box, click once on the arrow next to Navigator, and then Applications. Click once on New button and enter the following information:
Description FITS MIME Type image Suffixes fits,fits.gz Application ds9 %s VO
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.