9 Using PONGO with other Starlink Applications

Using graphics between different applications packages is often difficult because once one package has finished plotting and completed execution all information concerning the contents of the plot is lost. This problem may be overcome by storing relevant graphical information for the plot (e.g. the graphics device, the size and position of the plot on the display surface, the coordinate limits of the data) in a file and providing facilities to store and retrieve the information in this database. This allows different applications to be used to display images, draw contours and annotate, for example, on the same plot without each application losing access to the plot dimensions. One such facility is provided by Starlink and is called AGI – Applications Graphics Interface (SUN/48). As its name implies, this facility provides a means by which any application can store plotting information for later use and retrieve plotting information stored by previous applications. To use AGI to good effect requires familiarity with some nomenclature.

AGI divides the plotting surface up into pictures, where a picture represents a rectangular area on the display surface. AGI stores coordinate information for each picture it creates on a graphics device in its database. AGI pictures are independent of the graphics package used to plot the data (where supported; i.e. SGS, IDI or PGPLOT), but they do depend explicitly upon the graphics device used to plot the data. AGI stores each picture in its database, grouped by the graphics device (or workstation in Starlink graphics terminology) upon which the picture was created, and each is stored sequentially in the order in which they were created. AGI pictures are given a name which indicates their use: a BASE picture refers to the whole plotting surface and the name is reserved only for this use; a FRAME picture refers to a picture which contains other pictures; and a DATA picture refers to a picture which contains a plot of the data. AGI also stores a label for each picture: a short character string which can be used by an application to uniquely identify a picture. Finally, AGI can store a one-line comment for each picture in the database to describe its use.

PONGO uses the definitions of world coordinates, window, device coordinates and viewport used by the PGPLOT graphics package (SUN/15) upon which it is based. Here, a PONGO plot represents a window of given size in the data or world coordinates the you’re working in. The data are plotted within these world coordinate limits in a rectangular area of the workstation surface. This area is called the viewport and its size and shape are defined in terms of the device coordinates. The data are plotted exactly within this viewport and so plot annotation and labelling will normally extend beyond the viewport limits. AGI pictures refer directly to PONGO viewports. Clearly, not all viewports used by PONGO will be associated with data windows and refer to plotted data; many will just define regions of the workstation surface in which further viewports will be defined. These viewports are directly analogous to the AGI FRAME pictures and are stored as such by AGI. Those viewports which are used for plotting data within are directly analogous to AGI DATA pictures and again are stored as such by AGI.

By default, when BEGPLOT (or DEVICE) is used to begin a new PONGO plotting session; e.g. :

PONGO will open the device and use the AGI BASE picture for that device, unless there is a more recent picture. In the case of a more recent picture, a FRAME picture will be created with the dimensions of the picture current on entry. In either case, the workstation will also be cleared. When a PONGO plot ends, using ENDPLOT, the AGI picture current on entry is again made current.

There are two further modes in which a PONGO plot may be begun: assert that PONGO use the BASE picture for plotting (BEGPLOT ACTION=B); and assert that PONGO use the last DATA picture in the current FRAME, without clearing the graphics device (BEGPLOT OVERLAY NOCLEAR). Specifying BEGPLOT ACTION=B forces PONGO to make the AGI BASE picture current on entry; i.e. if you specifically want to use the whole display surface for plotting. Using BEGPLOT OVERLAY=YES CLEAR=NO allows plotting with other applications packages in a coordinated way. Here, PONGO will search for the last DATA picture in the AGI database and use the associated coordinates to define the PGPLOT viewport. The workstation will not be cleared on entry. This means that anything plotted with PONGO will be on the same axes and to the same scale as the existing plot.

As an example, PONGO can be used to annotate images displayed using KAPPA. First, KAPPA will be used to set the image display device and to clear the AGI database for the device (i.e. a tidy start):

It is necessary to first define the viewport the image is to be plotted within using PONGO in order to assure that there is enough room around the image for the annotation (remember, the annotation of PONGO graphs normally lies outside the viewport):

Then use KAPPA to display the image⁵:

Here, KAPPA PICDATA is used to select the last defined AGI DATA picture, which is a DATA picture created by PONGO with enough space around it to annotate the plot. You could also use KAPPA PICLIST which shows a table of all the pictures in the AGI database. These include the BASE picture, referring to the entire plotting surface of the graphics device; the PONGO FRAME picture, defined on entry and again referring to the entire plotting surface; and finally the PONGO DATA picture, referring the area of the plotting surface within which the image is displayed.

Now PONGO may be used to annotate the plot:

The image has been displayed by KAPPA and then the axes drawn and annotated using PONGO. In this case, the annotation represents the pixel number in each of the axes of the image. A more detailed example of the interaction between KAPPA and PONGO, via AGI, is provided in §8.3.