Next: Speculations on the Future of FITS
Previous: WCSTools: Image World Coordinate System Utilities
Up: FITS-Flexible Image Transport System
Table of Contents - Index - PS reprint - PDF reprint

---

Astronomical Data Analysis Software and Systems VI
ASP Conference Series, Vol. 125, 1997
Editors: Gareth Hunt and H. E. Payne

---

The SAOtng Programming Interface

E. Mandel
Smithsonian Astrophysical Observatory, Cambridge, MA 02138

Abstract:

1. Introduction

SAOtng (SAOimage: The Next Generation) is an updated and improved version of the popular SAOimage display program for X Windows. It utilizes the Xt Toolkit and Xt-based widgets, the Gterm-image widget, and the NOAO widget server as the basis for its graphical and imaging functionality (Mandel & Tody 1995). SAOtng supports direct display of IRAF images and FITS images (and easily can support other file formats), multiple frame buffers, region/cursor manipulation, add-on scaling algorithms, many colormaps, and communication with external analysis tasks. It is highly configurable and extensible to meet the evolving needs of the astronomical community.

2. The SAOtng Public Access Interface

SAOtng uses the X Public Access mechanism ( XPA) to give external processes access to its data and algorithms (Mandel, Swick, & Tody 1995). XPA allows an Xt program such as SAOtng to define named ``public access points'' through which data and commands can be exchanged with other programs. Each public access point in SAOtng supports the exchange of arbitrary amounts of information through the call-back paradigm already familiar to Xt application programmers.

XPA extends the SAOtng graphical user interface beyond the customary boundaries of the program. Usually, actions in a graphical program are initiated by mouse and keyboard events input by the user. But in SAOtng, these actions can be initiated by external programs using the public access programming interface. In addition, new actions that are not part of the GUI can be added to this interface.

The public access interface to SAOtng supports UNIX, C, and FORTRAN calls. For example, the UNIX public access commands are:

    # does SAOtng exist? (returns ``yes'' or ``no'')
    csh) xpaaccess SAOtng

    # send data or commands to SAOtng
    # access points can accept modifying parameters
    csh) <data> | xpaset SAOtng <access_point> [parameters]
or  csh) imset <access_point> [parameters]

    # retrieve data or info from SAOtng
    csh) xpaget SAOtng <access_point> [parameters]
or  csh) imget <access_point> [parameters]

The C and FORTRAN interfaces define a set of calls similar to the UNIX commands described above. For example, the C interface contains the following routines:

    /* open a connection to the xpa server */
    void *xpafd = OpenXPA(``SAOtng'');

    /* send data or commands to SAOtng */
    SetXPAValue(void *xpafd, char *paramlist, char *data, int len);

    /* retrieve data or info from SAOtng */
    GetXPAValue(void *xpafd, char *paramlist, char *data, int *len);

    /* close connection */
    CloseXPA(void *xpafd);

More than thirty-five public access points in SAOtng (a selection of which is shown in Table 1) support communication with external processes. Several of these are designed specially to provide commonly-used information and data to astronomical analysis programs. It is this combination of broad flexibility and specific useful functionality that makes the public access interface a valuable part of SAOtng's image display services.

 
Table: A Selection of Public Access Points in SAOtng

3. Examples of the SAOtng Public Access Interface

New image files can be loaded using the file public access point:

    csh) imset file ../data/coma.fits

The file access point can contacted from the command line or from programs such as archive servers and file browsers to display local files. For example, the XDir file browser issues a file command to SAOtng when the user double-clicks on an image file. UNIX scripts also can use file to process a list of images.

For processes requiring the fastest possible display of image data, the shm (shared memory) access point can be used to share in-memory FITS with SAOtng. For example, a data acquisition program can collect FITS data into a shared memory segment. The program sends shm information to SAOtng so that the latter can access the same shared memory:

    sprintf(paramlist, ``shm %s %d %d'', name, shm_id, shm_segsz);
    SetXPAValue(xpafd, paramlist, NULL, 0);

SAOtng supports the ability to mark regions of interest on images. Geometric markers (circles, rectangles, ellipses, polygons, points, and lines) and text can be placed interactively on an image and then moved, resized, reshaped, etc. Markers can have attributes of ``include'' or ``exclude'' and ``source'' or ``background.'' They are used in systems such as IRAF/PROS and HEASARC xselect to specify spatial filtering of image data (Mandel et al. 1993).

The regions public access point supports external control of these markers. Using this access point, markers can be loaded from a file:

    csh) cat regions.file | xpaset SAOtng regions

    csh) xpaget SAOtng regions degrees > newregions.file

Finally, the coords public access point allows a user to retrieve the spatial position (and associated data value) pointed to by the mouse:

    GetXPAValue(xpafd, ``coords'', cbuf, 132);

4. Summary

SAOtng and XPA are available as part of the SAO R&D software suite. Other programs contained in this package include ASSIST (a uniform interface to heterogeneous analysis systems), XDir (an X directory and file browser which supports user-defined actions for different file types), and ncl ( IRAF cl with line-editing). This software suite has been ported to Sun, SGI, HP, Dec Alpha, PC/Linux, and PC/FreeBSD systems, and is available via anonymous ftp.

The SAO R&D software suite is an embodiment of an evolving software cooperation philosophy that we hope to bring to astronomy and other disciplines. It reflects our understanding about how software systems (and researchers and developers) can act in concert without sacrificing their independence.

Acknowledgments:

This work was performed in large part under a grant from NASA's Applied Information System Research Program (NAGW-3913), with support from the AXAF Science Center (NAS8-39073).

References:

Mandel, E., Roll, J., Schmidt, D., VanHilst, M., & Burg, R. 1993, in Astronomical Data Analysis Software and Systems II, ASP Conf. Ser., Vol. 52, eds. R.J. Hanisch, R.J.V. Brissenden, & J. Barnes (San Francisco, ASP), 430

Mandel, E., & Tody, D. 1995, in Astronomical Data Analysis Software and Systems IV, ASP Conf. Ser., Vol. 77, eds. R. A. Shaw, H. E. Payne & J. J. E. Hayes (San Francisco, ASP), 125

Mandel E., Swick R., & Tody D. 1995, The X Resource, Vol. 13, (Boulder: O'Reilly), 235

Next: Speculations on the Future of FITS
Previous: WCSTools: Image World Coordinate System Utilities
Up: FITS-Flexible Image Transport System
Table of Contents - Index - PS reprint - PDF reprint