DS9 FAQ

DS9 FAQ

    This 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
      IRAF
      Coordinates
      Regions
      Printing
      Save As
      X11
      XPA
      PORTS
      Help

    General

  1. When I open my FITS image, all I see is 'white'. Yet everything, including the colorbar seems to work?
    1.  
      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 overscan 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.

    IRAF

  2. 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.
    1.  
      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 200Mhz. Again saoimage does not even run in 24 bit mode, so there are no  comparisons.
       

  3. I try to display an image from IRAF and I get: ERROR: Cannot open device (node!imtool,,512,512)
    1.  
      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%d
         
      If 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
         
  4. I try to display an image, I see something, but it's corrupted and I get multiple error messages from DS9...
    1.  
      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.
         
  5. Where do I find this .imtoolrc file?
    1.  
      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.
         
  6. Can I display from IRAF to DS9 running under Windows 95/98/ME/NT/2000?
  7. 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
  8. When I display an image from IRAF, the SCALE menu option is not active, Why?
    1.  
      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

  9. Why don't I see PHYSICAL/DETECTOR/AMPLIFIER/WCS coordinates displayed when I load my image?
    1.  
      DS9 supports the following coordinate systems:
       
        WCS Sky coords (fk4,fk5,icrs,galatic,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 CRVAL,CRPIX,CRDELT,CD... (for images)
      TCRVL,TCRPX,TCDLT,... (for tables)
      Image none required
      Physical LTM, LTV
      Detector DTM, DTV
      Amplifier ATM, ATV

      If the required keywords are not present, values for those coordinates are not
      displayed.

    Regions

  10. How do I indicate distance on my printed images?
    1.  
      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

  11. 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?
    1.  
      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. Second, when printing from  DS9 for publication, choose CMYK as opposed to RGB in the print dialog box.

      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.

      From ApJ:
      http://www.journals.uchicago.edu/ApJ/information.html

      Guidelines for Authors Submitting Electronic Art Files
       

        9. Figures that are intended to be printed in color must be prepared as CMYK
        (i.e., four-color) files, not RGB files. (RGB files cannot be used for printing
        and must be converted to CMYK, which often results in undesirable color shifts.)
        If authors cannot provide us with four-color files we will convert their files
        from RGB to CMYK. In addition, authors must submit a hard copy of each color
        figure, which shows how the colors should look in the printed journal. This is
        needed because the appearance of a color figure is highly device-dependent, and
        the Press and the printer need to know what colors the author has seen and
        approved.

        Optimum resolution for CMYK files is 300 dpi. CMYK EPS files created with
        Photoshop seem to produce the best results.

        10. When preparing grayscale figures, use gray levels between 20% and 80%, with
        at least 20% difference between the levels of gray. Use a screen of 80 lpi or
        lower (coarser) and make the figures as close to final publication size as
        possible, as reduction can cause levels of gray to drop out. Whenever possible,
        use different patterns of hatching instead of grays to differentiate between
        areas of a figure.
         

      P.S. Even though ApJ recommends 300 dpi, I believe this is over-kill. For 3 or 4
      color separated images, 150 dpi is plenty of resolution and 1/4 the file size.

    Save As

  12. When I try Save As Image, and select jpeg, tiff, pgn, or ppm, all I see is a large number of streaming error messages. What am I doing wrong?

  13.  
      There have been several reports of the failure of the Save As Image function. DS9 uses Ghostscript to rasterize the image and graphic data and to convert to one of the supported image formats. However, there seems to be problems with using older versions of ghostscript. In particular, it appears that Ghostscript version 6.50 or greater is required. Below is a list of the versions of Ghostscript that have been tested with DS9:
       
      DS9 Port Ghostscript Version
      Solaris AFPL Ghostscript 7.04 (2002-01-31)
      Linux GNU Ghostscript 6.51 (2001-03-28)
      MacOSX AFPL Ghostscript 6.50 (2000-12-02) 
      Windows (Cygwin) GNU Ghostscript 6.51

    X11

  14. When I start DS9, I get the following error message:

  15. _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

    XPA

  16. 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?
    1.  
      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

    Ports

  17. I have Red Hat 7, and I'm running KDE. The magnifier keeps going blank after a few seconds, what's going on?
    1.  
      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 1.
  18. I have Windows 98. All line graphics, such as regions and contours appear corrupted. What's going on?
    1.  
      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.

    Help

  19. When I select 'Help:Reference Manual', nothing happens...
    1.  
      The help facility of DS9 currently uses Netscape. DS9 will try to determine if Netscape is available and if it is currently running. If Netscape is running, DS9 will just redirect it to the Reference Manual url. If Netscape is available, but not running, DS9 will try to start a new version and direct it to the correct url.

      If Netscape is not available, or if you are not connected to a network, you should see an error message.

      However, there have been a number of bug reports received that indicates the reliability of this method varies platform to platform, and is depended upon what version of Netscape is used and what the users X11 window manager is. Sometimes, everything works fine, but Netscape is on another virtual screen and the user never sees it. Other times, Netscape will bring up multiple versions, or just hang.

      Also, if you have a stand-alone machine, or have a laptop and are not currently connected, help is not available.

      To address these problems, the user has the option of downloading the DS9 Reference Manual from DS9  to a local drive, then tell DS9 to use this version as the reference manual by selecting  Edit:Preferences:Help Menu: Reference Manual URL.