GNU Astronomy Utilities


Previous: , Up: SAO ds9   [Contents][Index]


B.1.1 Viewing multiextension FITS images

The FITS definition allows for multiple extensions inside a FITS file, each extension can have a completely independent data set inside of it. If you ordinarily open a multi-extension FITS file with SAO ds9, for example by double clicking on the file or running $ds9 foo.fits, SAO ds9 will only show you the first extension. To be able to switch between the extensions you have to follow these menus in the SAO ds9 window: File→Open Other→Open Multi Ext Cube and then choose the Multi extension FITS file in your computer’s file structure.

The method above is a little tedious to do every time you want view a multi-extension FITS file. Fortunately SAO ds9 also provides command-line options that you can use to specify a particular behavior. One of those options is -mecube which opens a FITS image as a multi-extension data cube (treating each 2D extension as a slice in a 3D cube). This allows you to flip through the extensions easily while keeping all the settings similar.

Try running $ds9 -mecube foo.fits to see the effect (for example on the output of NoiseChisel). If the file has multiple extensions, a small window will also be opened along with the main ds9 window. This small window allows you to slide through the image extensions of foo.fits. If foo.fits only consists of one extension, then SAO ds9 will open as usual. Just to avoid confusion, note that SAO ds9 does not follow the GNU style of separating long and short options as explained in Arguments and options. In the GNU style, this ‘long’ (multi-character) option should have been called like --mecube, but SAO ds9 follows its own conventions.

Recall the -mecube opens each 2D input extension as a slice in 3D. Therefore, when you want to inspect a multi-extension FITS file containing a 3D dataset, the -mecube option is no good any more (it only opens the first slice of the 3D cube in each extension). In that case, we have to use SAO ds9’s -multiframe option to open each extension as a separate frame. Since the input is a 3D dataset, we get the same small window as the 2D case above for scrolling through the 3D slices. We then have to also ask ds9 to match the frames and lock the slices, so for example zooming in one, will also zoom the others.

Since opening a multi-extension file (that contains similarly sized datasets) differs between a 2D and 3D dataset, we will have to define a script to decide which path to go based on the input. After the following steps, when clicking on a FITS file in your graphic user interface, ds9 will open in the respective mode and a shell function will also be available to open it on the command-line. Note that the following solution assumes you already have Gnuastro installed (in particular Fits).

We will use a shell script for the conditional call of ds9. Let’s assume that you want to put it in BINDIR (that is in your PATH environment variable, see Installation directory). Tip: a good place would be ~/.local/bin. Afterwards using your favorite text editor, put the following script into a file called BINDIR/ds9-multi-ext. You can change the size of the opened ds9 window by changing the 1800x3000 part of the script below.

#! /bin/bash

# Make sure an input file is given.
if [ "x$1" == "x" ]; then
  echo "No input file given."
else
  # Make sure we are dealing with a FITS file. We are using shell
  # redirection here to make sure that nothing is printed in the
  # terminal (to standard output when we have a FITS file, or to
  # standard error when we don't). Since we've used redirection,
  # we'll also have to echo the return value of `astfits'.
  check=$(astfits $1 -h0 > /dev/null 2>&1; echo $?)

  # If the file was a FITS file, then `check' will be 0.
  if [ "$check" == "0" ]; then

    # Read the number of dimensions.
    n0=$(astfits $1 -h0 | awk '$1=="NAXIS"{print $3}')

    # Find the number of dimensions.
    if [ "$n0" == "0" ]; then
      ndim=$(astfits $1 -h1 | awk '$1=="NAXIS"{print $3}')
    else
      ndim=$n0
    fi;

    # Open DS9 based on the number of dimension.
    if [ "$ndim" = "2" ]; then
      ds9 -zscale -geometry 1800x3000 -mecube $1 -zoom to fit    \
          -wcs degrees
    else
      ds9 -zscale -geometry 1800x3000 -tile -wcs degrees         \
          -multiframe $1 -zoom to fit -match frame image         \
          -lock slice image -lock frame image
    fi
  else
    if [ -f $1 ]; then
      echo "'$1' isn't a FITS file."
    else
      echo "'$1' doesn't exist."
    fi
  fi
fi

To be able to run it, you have to activate its executable flag with this command:

$ chmod +x BINDIR/ds9-multi-ext

If BINDIR is within your system’s PATH environment variable (see Installation directory), you can now open ds9 conditionally (depending on dimensions of the input, as described above) with a command like this:

$ ds9-multi-ext foo.fits

For the graphic user interface, we’ll assume you are using GNOME (the most popular graphic user interface for GNU/Linux systems), version 3. For GNOME 2, see below. You can customize GNOME to open specific files with .desktop files. For each user, they are stored in ~/.local/share/applications/. In case you don’t have the directory, make it your self (with mkdir). Using your favorite text editor, you can now create ~/.local/share/applications/saods9.desktop with the following contents. Just don’t forget to correct BINDIR. If you would also like to have ds9’s logo/icon in GNOME, download it, uncomment the Icon line, and write its address in the value.

[Desktop Entry]
Type=Application
Version=1.0
Name=SAO ds9
Comment=View FITS images
Terminal=false
Categories=Graphics;RasterGraphics;2DGraphics;3DGraphics
#Icon=/PATH/TO/DS9/ICON/ds9.png
Exec=BINDIR/ds9-multi-ext %f

The steps above will add SAO ds9 as one of your applications. To make it default, take the following steps (just once is enough). Right click on a FITS file and select Open with other application→View all applications→SAO ds9.

In case you are using GNOME 2 you can take the following steps: right click on a FITS file and choose Properties→Open With→Add button. A list of applications will show up, ds9 might already be present in the list, but don’t choose it because it will run with no options. Below the list is an option “Use a custom command”. Click on it and write the following command: BINDIR/ds9-multi-ext in the box and click “Add”. Then finally choose the command you just added as the default and click the “Close” button.


Previous: , Up: SAO ds9   [Contents][Index]