NAME

       FunDS9 - Funtools and DS9 Image Display

SYNOPSIS

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

DESCRIPTION

       SAOImage/DS9 is an astronomical imaging and data visualization application used by
       astronomers around the world.  DS9 can display standard astronomical FITS images and
       binary tables, but also has support for displaying raw array files, shared memory files,
       and data files automatically retrieved via FTP and HTTP.  Standard functional capabilities
       include multiple frame buffers, colormap and region manipulation, and many data scaling
       algorithms. DS9's advanced features include TrueColor visuals, deep frame buffers, true
       PostScript printing, and display of image mosaics. The program's support of image tiling,
       "blinking", 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 SAO, StScI, or ESO).

       DS9 can communicate with external programs such as Funtools using the XPA messaging
       system.  In addition, programs can be integrated directly into the DS9 GUI by means of a
       configurable Analysis menu.  By default, the DS9 Analysis menu contains algorithms deemed
       essential to the core functions of DS9, e.g., display cross-cuts of data, iso-intensity
       contours, and WCS grids. However, new programs can be added to DS9 by creating a set-up
       file which can be loaded into DS9 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, DS9 supports a macro facility to provide information as well as task
       support to command lines. For example, the $regions macro is expanded by DS9 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 DS9 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 DS9
       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 DS9 from the Load Analysis
       Commands ... option of the Analysis menu.  Alternatively, you can tell DS9 to load this
       file automatically at start-up time by adding the pathname to the
       Edit->Preferences->Analysis Menu->Analysis File menu option.  (NB: make sure you select
       Edit->Preferences->Save Preferences after setting the pathname.)

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

SEE ALSO

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