=pod

=head1 NAME



B<FunDS9: Funtools and DS9 Image Display>



=head1 SYNOPSIS




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



=head1 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 B<Load Analysis Commands ...> option of
the B<Analysis> menu.  Alternatively, you can tell DS9 to load
this file automatically at start-up time by adding the pathname to the
B<Edit>->B<Preferences>->B<Analysis Menu>->Analysis
File menu option.  (NB: make sure you select
B<Edit>->B<Preferences>->B<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.



=head1 SEE ALSO



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



=cut
