GNU Astronomy Utilities

10.4.1 Invoking astscript-fits-view

Given any number of FITS files, this script will either open SAO DS9 (for images or cubes) or TOPCAT (for tables) to visualize their contents in a graphic user interface (GUI). For more on installed scripts please see (see Installed scripts). This script can be used with the following general template:

$ astscript-fits-view [OPTION] input.fits [input-b.fits ...]

One line examples

## Call TOPCAT to load all the input FITS tables.
$ astscript-fits-view table-*.fits

## Call SAO DS9 to open all the input FITS images.
$ astscript-fits-view image-*.fits

This script will use Gnuastro’s Fits program to see if the file is a table or image. If the first input file contains an image HDU, then the sequence of files will be given to SAO DS9. Otherwise, the input(s) will be given to TOPCAT to visualize (plot) as tables. When opening DS9 it will also inspect the dimensionality of the first image HDU of the first input and open it slightly differently when the input is 2D or 3D:


DS9’s -mecube will be used to open all the 2D extensions of each input file as a “Multi-extension cube”. A “Cube” window will also be opened with DS9 that can be used to slide/flip through each extensions. When multiple files are given, each file will be in one “frame”.


DS9’s -multiframe option will be used to open all the extensions in a separate “frame” (since each input is already a 3D cube, the -mecube option can be confusing). 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. If multiple files are given, there will be a separate frame for each HDU of each input (each HDU’s name or number will be put in square brackets after its name).

Double-clicking on FITS file to open DS9 or TOPCAT: for those graphic user interface (GUI) that follow the standards (including GNOME, KDS Plasma, or Xfce) Gnuastro installs a fits-view.desktop file to instruct your GUI to call this script for opening FITS files when you click on them. To activate this feature take the following steps:

  1. Run the following command, while replacing PREFIX. If you do not know what to put in PREFIX, run which astfits on the command-line, and extract PREFIX from the output (the string before /bin/astfits). For more, see Installation directory.
    ln -sf PREFIX/share/gnuastro/astscript-fits-view.desktop \
  2. Right-click on a FITS file, and choose these items in order (based on GNOME, may be different in KDE or Xfce): “Open with other application”→“View all applications”→“astscript-fits-view”.

This script takes the following options

-h STR

The HDU (extension) of the input dataset to display. The value can be the HDU name or number (the first HDU is counted from 0).

-p STR

Directory to search for SAO DS9 or TOPCAT’s executables (assumed to be ds9 and topcat). If not called they will be assumed to be present in your PATH (see Installation directory). If you do not have them already installed, their installation directories are available in SAO DS9 and TOPCAT (they can be installed in non-system-wide locations that do not require administrator/root permissions).

-s STR

The string to give to DS9’s -scale option. You can use this option to use a different scaling. The Fits-view script will place -scale before your given string when calling DS9. If you do not call this option, the default behavior is to cal DS9 with: -scale mode zscale or --ds9scale="mode zscale" when using this script.

The Fits-view script has the following aliases to simplify the calling of this option (and avoid the double-quotations and mode in the example above):


or --ds9scale=zscale equivalent to --ds9scale="mode zscale".


or --ds9scale=minmax equivalent to --ds9scale="mode minmax".


The central coordinate for DS9’s view of the FITS image after it opens. This is equivalent to the “Pan” button in DS9. The nature of the coordinates will be determined by the --ds9mode option that is described below.

-O img/wcs

The coordinate system (or mode) to interpret the values given to --ds9center. This can either be img (or DS9’s “Image” coordinates) or wcs (or DS9’s “wcs fk5” coordinates).


The initial DS9 window geometry (value to DS9’s -geometry option).


Do not show a single color bar for all the loaded images. By default this script will call DS9 in a way that a single color bar is shown for any number of images. A single color bar is preferred for two reasons: 1) when there are a lot of images, they consume a large fraction of the display area. 2) the color-bars are locked by this script, so there is no difference between! With this option, you can have separate color bars under each image.