GNU Astronomy Utilities


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


B.1.1 Viewing multiextension FITS images

The FITS definition allows for multiple extensions inside one FITS file, each extension can have a completely independent dataset inside of it. If you just double click on a multi-extension FITS file or run $ds9 foo.fits, SAO DS9 will only show you the first extension. If you have a multi-extension file containing 2D images, one way to load and switch between the each 2D extension is to take the following steps 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. A different series of steps is also necessary if you the extensions are 3D data cubes. 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.

We can use a script to automatize this process and make work much easier (and save a lot of time) when opening any generic 2D or 3D dataset. After taking the following steps, when you click on a FITS file in your graphic user interface, ds9 will open in the respective 2D or 3D mode when double clicking a FITS file on the graphic user interface, and an executable will also be available to open ds9 similarly on the command-line. Note that the following solution assumes you already have Gnuastro installed (and in particular the Fits program).

Let’s assume that you want to store this script in BINDIR (that is in your PATH environment variable, see Installation directory). [Tip: a good place would be ~/.local/bin, just don’t forget to make sure it is in your PATH]. 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

# To allow generic usage, if no input file is given (the `if' below is
# true), then just open an empty ds9.
if [ "x$1" == "x" ]; then
    ds9
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
            # 2D multi-extension file: use the "Cube" window to
            # flip/slide through the extensions.
            ds9 -zscale -geometry 1800x3000 -mecube $1         \
                -zoom to fit -wcs degrees
        else
            # 3D multi-extension file: The "Cube" window will slide
            # between the slices of a single extension. To flip
            # through the extensions (not the slices), press the top
            # row "frame" button and from the last four buttons of the
            # bottom row ("first", "previous", "next" and "last") can
            # be used to switch through the extensions (while keeping
            # the same slice).
            ds9 -zscale -geometry 1800x3000 -wcs degrees       \
                -multiframe $1 -match frame image              \
                -lock slice image -lock frame image -single    \
                -zoom to fit
        fi
    else
        if [ -f $1 ]; then
            echo "'$1' isn't a FITS file."
        else
            echo "'$1' doesn't exist."
        fi
    fi
fi

As described above (also in the comments of the script), if you have opened a multi-extension 2D dataset (image), the “Cube” window can be used to slide/flip through each extension. But when the input is a 3D data cube, the “Cube” window will slide/flip through the slices in each extension (a separate 3D dataset). To flip through the extensions (while keeping the slice fixed), click the “frame” button on the top row of buttons, then use the last four buttons of the bottom row ("first", "previous", "next" and "last") to change between the extensions.

To run this script, 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 using the script above with this command:

$ 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: SAO DS9, Up: SAO DS9   [Contents][Index]