funds9 (1)

Describes how funtools can be integrated into the ds9 Analysis menu.

SAOImage/DS9 is an astronomical imaging and data visualization application used by astronomers around the world. \s-1DS9\s0 can display standard astronomical \s-1FITS\s0 images and binary tables, but also has support for displaying raw array files, shared memory files, and data files automatically retrieved via \s-1FTP\s0 and \s-1HTTP\s0. Standard functional capabilities include multiple frame buffers, colormap and region manipulation, and many data scaling algorithms. \s-1DS9\s0's advanced features include TrueColor visuals, deep frame buffers, true PostScript printing, and display of image mosaics. The program's support of image tiling, \*(L"blinking\*(R", arbitrary zoom, rotation, and pan is unparalleled in astronomy. It also has innovative support for automatic retrieval and display of standard image data such as the Digital Sky Survey (using servers at \s-1SAO\s0, StScI, or \s-1ESO\s0).

\s-1DS9\s0 can communicate with external programs such as Funtools using the \s-1XPA\s0 messaging system. In addition, programs can be integrated directly into the \s-1DS9\s0 \s-1GUI\s0 by means of a configurable Analysis menu. By default, the \s-1DS9\s0 Analysis menu contains algorithms deemed essential to the core functions of \s-1DS9\s0, e.g., display cross-cuts of data, iso-intensity contours, and \s-1WCS\s0 grids. However, new programs can be added to \s-1DS9\s0 by creating a set-up file which can be loaded into \s-1DS9\s0 to reconfigure the Analysis menu.

The basic format of the analysis set-up file is:

  #
  # Analysis command descriptions:
  #   menu label/description
  #   file templates for this command
  #   "menu" (add to menu) |"bind" (bind to key)
  #   analysis command line

For example, the funcnts program can be specified in this way:

Funcnts (counts in source/bkgd regions; options: none) * menu funcnts $filename $regions(source,,) $regions(background,,) | $text

As shown above, \s-1DS9\s0 supports a macro facility to provide information as well as task support to command lines. For example, the $regions macro is expanded by \s-1DS9\s0 to provide the current source and/or background region to the analysis command. The $text macro is expanded to generate a text window display. It also is possible to query for parameters using a $param macro, plot data using a $plot macro, etc. See the \s-1DS9\s0 documentation for further details.

A set-up file called funtools.ds9 will load some useful Funtools applications (counts in regions, radial profile, X\-ray light curve and energy spectrum, 1D histogram) into the \s-1DS9\s0 Analysis menu (version 2.1 and above). The file resides in the bin directory where Funtools programs are installed. It can be manually loaded into \s-1DS9\s0 from the Load Analysis Commands ... option of the Analysis menu. Alternatively, you can tell \s-1DS9\s0 to load this file automatically at start-up time by adding the pathname to the Edit->Preferences->Analysis Menu->Analysis File menu option. (\s-1NB:\s0 make sure you select Edit->Preferences->Save Preferences after setting the pathname.)

The tasks in this setup file generally process the original disk-based \s-1FITS\s0 file. Funcnts-based results (radial profile, counts in regions) are presented in \s-1WCS\s0 units, if present in the \s-1FITS\s0 header. For situations where a disk file is not available (e.g., image data generated and sent to \s-1DS9\s0's 'fits' \s-1XPA\s0 access point), versions of the radial profile and counts in regions tasks also are also offered utilizing \s-1DS9\s0's internal image data. Results are presented in pixels. Aside from the units, the results should be identical to the file-based results.

See funtools(7) for a list of Funtools help pages