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:

2D

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”.

3D

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).

This script takes the following options

-h STR

--hdu=STR

The HDU(s), or extension(s), of the input dataset(s) to display. The value can be the HDU name (a string) or number (the first HDU is counted from 0). If there are multiple inputs, this option needs to be called multiple times: the first input will be opened with the first call to this option, the second input with the second call and etc. If you want to open the same HDU of all your inputs, you don’t need to repeat this option, use --globalhdu instead.

-g STR

--globalhdu=STR

The HDU/extension name or number to use for all inputs. Note that HDU counting starts from 0. If --hdu called, it takes precedence over this.

-p STR

--prefix=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

--ds9scale=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):

zscale

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

minmax

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

-c=FLT,FLT

--ds9center=FLT,FLT

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.

-r=STR[,STR[,STR]]

--ds9region=STR[,STR[,STR]]

Name of DS9 region file(s) to load within the DS9 window once it opens. Any number of region files can be loaded with a single call to this command (separated by comas).

-O img/wcs

--ds9mode=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).

-g INTxINT

--ds9geometry=INTxINT

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

-m

--ds9colorbarmulti

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.

-e STR

--ds9extra=STR

Any other custom options you would like to directly pass to DS9. This option can be called multiple times. The string(s) given to this option will be the final component of the DS9 command that this script generates. This allows you to over-ride/customize previously set options (for example in large scripts).

Besides enabling all DS9 options that don’t have a high-level wrapper in this script, you can also use this option to re-order the way the options of this script call DS9. This is because this script ignores the order that you have requested options and will always put the high-level functions in a fixed order. Before calling DS9, this script will print the command that it executes so you can see the order explicitly before DS9 opens.

Since DS9 does not recognize a = between the option name and value, a SPACE is usually necessary. Therefore, be sure to put them in a single string within double quotes (so the spaces are preserved and passed to DS9 correctly). For example usage of this option within this manual, see Column statistics (color-magnitude diagram) or Subtracting the PSF.