A FITS Cube is a FITS image which contains more than 2 axes (NAXES>2). DS9 will automatically detect if a cube is present and will load all additional images. In addition, individual images can be loaded one at a time into a cube. DS9 will display the Cube dialog box which allows the user to select which 2 image to be displayed.
| Command: | fits slice [filename] |
| Menu: | File - Open As - Slice |
| Description: | Used to open animage and add it as a new slice at the end of the current data cube. |
| Command: | save fits [filename] slice |
| Menu: | File - Save As - Slice |
| Description: | Save current slice as a FITS image. |
Once a cube is created, File - Create Movie - Slice Movie followed by File - Create Movie - MPEG or File - Create Movie - Animated GIF will make an MPEG or GIF movie file. File - Create Movie - Display can be used to set the frame rate.
| Command: | movie slice|frame mpeg|gif [delay] blink|fade [filename] |
| Menu: | File - Create Movie |
| Description: | Saves the current slice set, or frames set, as an animated GIF or an MPEG.The delay and blink/fade arguments are optional. |
| Command: | blink yes|no |
| Menu: | Frame - Blink Frames |
| Description: | This shows a single frame at any one instant, but every few seconds cycles through the set of frames. |
| Command: | blink interval [N] |
| Menu: | Frame - Frame Parameters - Blink Interval - [N] |
| Description: | Sets the time interval in seconds for the Blink Frames mode |
| Command: | fade yes|no |
| Menu: | Frame - Fade Frames |
| Description: | Cycles through a time sequence where the frames fade into one another. |
| Command: | fade interval [N] |
| Menu: | Frame - Frame Parameters - Fade Interval - [N] |
| Description: | Sets the time interval in seconds for the Fade Frames mode |
| Command: | movie 3d slice|frame mpeg|gif [delay] [filename] [opts] |
| Menu: | File - Create Movie - 3D movie |
| Description: | Saves the current 3D data, as an animated GIF or an MPEG.Options are 'number' (of frames), 'az from', 'az to', 'slice from ', 'slice to', 'zoom from n', 'zoom to n', 'oscillate n', 'repeat n'.Example:movie 3d mpeg ds9.mpg number 10 az from -60 az to 60 oscillate 1 |
| Command: | mosaicimage wcs [filename] |
| Menu: | File - Open As - Mosaic WCS |
| Description: | Mosaic images consist of multiple chips each with their own coordinate system.Note: A FITS Mosaic Data Cube is a FITS mosaic image which contains more than2 axes (NAXES>2). DS9 will automatically detect if a mosaic data cube ispresent and will load all additional images. At the same time, DS9 willdisplay the data cube dialog box which allows the user to select which 2Dimage is to be displayed. |
| Command: | mosaic wcs [filename] |
| Menu: | Open As - Mosaic WCS Segment |
| Description: | Open mosaic segment in current frame |
| Command: | mosaicimage wcs new [filename] |
| Menu: | - |
| Description: | Open mosaic image in new frame |
| Command: | mosaic wcs new [filename] |
| Menu: | - |
| Description: | Open mosaic segment in new frame |
| Command: | save mosaic [filename] |
| Menu: | File - Save As - Mosaic WCS Segment |
| Description: | Save mosaic |
| Command: | save mosaicimage [filename] |
| Menu: | File - Save As - Mosaic WCS |
| Description: | Save mosaic |
| Command: | scale scope local|global |
| Menu: | Scale - Local|Global |
| Description: | Determines whether the range limitalgorithm is applied separately for each mosaic segment oronce for the whole dataset. |
| Command: | - |
| Menu: | File - Open As - Mosaic WFPC2 |
| Description: | Special support for WFPC images |
| Command: | - |
| Menu: | File - Open As - Mosaic IRAF |
| Description: | Loads a Mosaic IRAF file. |
| Command: | prefs irafalign yes|no |
| Menu: | Edit - Preferences - General - Mosaic IRAF DETSEC Align |
| Description: | If this is set, the DETSEC metadata will be usedto align the components of the mosaic. |
| Command: | - |
| Menu: | File - Open As - Mosaic IRAF Segment |
| Description: |
Some telescopes provide data with multiple image extensions.
A FITS Multiple Extension Data Cube file is a FITS file with one or more extensions, that is to be displayed as a data cube. Each image does not have to be the same size. However, only the coordinate systems from the first extension will be used for contours and grids.
DS9 provides a way to load these as a data cube;
| Command: | mecube [filename] |
| Menu: | File - Open As - Multiple Extension Cube |
| Description: | Load ME FITS file as data cube into current frame.Example:ds9 -mecube foo.fits # load multiple extension fits file as data cube |
| Command: | multiframe [filename] |
| Menu: | File - Open As - Multiple Extension Frames |
| Description: | Load ME FITS file as separate images in separate frames.Example:ds9 -multiframe foo.fits # load multiple extension fits file as multiple frames |
| Command: | mecube new [filename] |
| Menu: | - |
| Description: | Load ME FITS file as data cube into new frame |
| Command: | save mecube [filename] |
| Menu: | File - Save As - Multiple Extension Cube |
| Description: | Save current data as an ME FITS file. |
On opening a FITS file, DS9 makes an image from the first non-null HDU which is either a FITS IMAGE or a binary table with a compatible dataset (ZIMAGE compressed image, HEALPIX image, or event file0.
If binary table extension is found for which the ZIMAGE keyword is T, a compressed FITS image is read.
If binary table extension is found for which the PIXTYPE keyword is HEALPIX, a HEALPIX image is read. Only full-field HEALPIX images are supported.
If the file doesn't have any valid images or event files, an error is reported.
An X-ray event file is stored as a FITS table with a set of columns, usually including ones called X and Y. DS9 recognizes an event file if it finds a binary table for which the EXTNAME keyword is EVENTS, STDEVENT or RAYEVENT; and for which column names X and Y are present.
When the file is loaded, DS9 makes an image on the fly, binning the data on the X and Y columns with a pixel size of 1 in the X and Y column units.
Columns with other names can be used as the columns to bin on instead; I will call these the axis columns. The center of the image is found from the image bounds determined using any of the following keywords, checked in this order: TDMIN/TDMAX, TLMIN/TLMAX, TALEN, and AXLEN.
In other words, if you are binning on columns named ENERGY and TIME with FITS keywords TTYPE5='ENERGY',TTYPE13='TIME', then it looks for the keywords TDMIN5 and TDMAX5 to define the range of the x (i.e. ENERGY) axis, and failing that TLMIN5 and TLMAX5, and then TALEN5, and finally AXLEN5. If none of these are present it uses the possible range of the data type of the axis columns (e.g 1 to 32767 for a 2 byte integer column).
By default only a 1024 x 1024 subset of the image at a binning value of 1 is loaded.
Instead of using the GUI to define the columns to bin on, you can use a qualified filename in the 'open file' dialog (or on the command line) of the form
filename[ext][binspec][filterspec][sect]
The ext and sect specifiers are the same as for the FITS image case. The binspec is of the form "bin=colx,coly" or "bin=colx,coly,colz" and the filterspec is of the form of entries with 'colname=value' or 'colname logical operator value' separated by '&&'.
Examples:
ds9 foo.fits # default load ds9 foo.fits[1] # load first extension ds9 foo.fits[BCKGRD] # load extension named 'BCKGRD' ds9 foo.fits[bin=detx,dety] # bin on detx,dety ds9 foo.fits[2][bin=rawx,rawy] # load ext 2, cols rawx,rawy ds9 foo.fits[bg_events][bin=rawx,rawy] # load ext bg_events, cols rawx,rawy ds9 foo.fits[bin=x,y,pha] # bin on x,y,pi ds9 foo.fits[bin=pi] # bin on x,y,pi ds9 'foo.fits[ccd_id==3&&energy>4000]' # quoted filter ds9 '"foo.fits[ccd_id==3 && energy>4000]"' # double quoted filter ds9 'foo.fits[events][pha>5,pi<2]' # load extension 'events' and filter
The shell environment variable DS9_BINKEY may also be used to specify default bin cols for FITS bin tables. Example:
$ export DS9_BINKEY='[bin=rawx,rawy]'
$ ds9 foo.fits # load FITS bin table, bin on rawx, rawy
| Command: | bin cols [xname] [yname |
| Menu: | Bin - Binning Parameters - Bin Columns |
| Description: | Select the columns to bin on. |
| Command: | bin colsz [xname] [yname] [zname] |
| Menu: | Bin - Binning Parameters - Bin 3rd Column |
| Description: | Select one of the other columns as a Z axis and create a 3D image. |
| Command: | bin depth [value] |
| Menu: | Bin - Binning Parameters - Bin 3rd Column - Depth |
| Description: | Selects the number of bins to use on the third axis. |
| Command: | - |
| Menu: | Bin - Binning Parameters - Apply |
| Description: | Causes the data cube to be createdand the data cube dialog box to be opened. The first slice of the data cube is displayed; the data cube dialog box commands such asData cube - Next can be used to navigate the slices of the cube. |
Data cube - Interval selects a time interval to control how Data cube - Play sequentially cycles through the slices of the cube.
| Command: | bin filter [string] |
| Menu: | Bin- Binning Parameters - Bin Filter |
| Description: | The data may be filtered;Enter a comma separated list of CIAO type filter strings "colname=min:max" entered in the dialog box(e.g. "energy =2500:8000, ccd_id=7") and then executeBin- Binning Parameters - Apply. > and < may also be used to define ranges. |
Note that if your /tmp directory is mounted -noexec, binary table filtering does not work. Before starting DS9, set the environment variable FILTER_TMPDIR to a directory that is both writable and can execute.
| Command: | save fits [filename] |
| Menu: | File - Save |
| Description: | The filtered data may be saved as a FITS image.In the GUI, after you press 'ok' on the file selection dialog, a small dialog appears allowing you to select Image or Table. |
HEALPIX is an encoding designed for all-sky data. FITS supports the HEALPIX paradigm with binary or ascii tables.
Only full-sky HEALPIX images are supported in DS9.
At load time, the user may provide just a file name or a file name along with FITS extension name/number, image section specification, and Healpix parameters. DS9 will automatically convert a FITS HEALPIX binary or ascii table into a 2D image for display. FITS extension names and parameters are case insensitive. The users may specify a number of parameters on how to construct the image. Any table with keyword PIXTYPE=HEALPIX or NSIDE=x will be processed as an HEALPIX image. The following FITS keywords will be used if present and not overwritten by a command line option: NSIDE, COORDSYS, ORDER.
Syntax:
filename
filename[ext]
filename[ext][sect]
filename[sect]
filename[ext,sect]
filename[ext][hpx]
filename[ext][hpx][sect]
filename[ext][sect][hpx]
filename[hpx]
filename[hpx][sect]
filename[sect][hpx]
filename[ext,hpx]
where [ext] and [sect] are extension and subset specifiers as described earlier for standard FITS images and the [hpx] specifier is special to HEALPIX with the following forms:
[order=ring|nested] # default ring
[layout=equatorial|north|south] # default equatorial
[col=] # defaut 1
[quad=] # (1-4) default 1
[system=equatorial|galactic|ecliptic|unknown] # default unknown
Example:
ds9 foo.fits # default load ds9 foo.fits[1] # load first extension ds9 foo.fits[order=ring,layout=equatorial,col=1,quad=1,system=unknown] ds9 foo.fits[1,order=nested] # first extension, nested order