The Starlink graphics software was introduced in Chapter 13. A guide to its use is available in SUN/113. The main packages are:
Three more specialised graphics facilities provided by ADAM are:
Before proceeding, a word of warning which is applicable to all Starlink graphics. Do not examine the workstation type or name in order to control the behaviour of a program. For example, you are not allowed to say ‘the GKS workstation type is 3200, therefore this is an Ikon image display, therefore colour is available’. This information must be obtained by calling the appropriate GKS, SGS, or PGPLOT inquiry routines; in the unlikely event of the property you are interested in not being available through such inquiries, then devise some mechanism external to the program, or solicit information from the user.
The following example graphics program uses SGS to draw a circle on a selected graphics device:
The statements concerned specifically with graphics will now be considered individually.
This makes the association between the parameter DEVICE and an SGS zone on the graphics device provided by the parameter system. The zone identifier is returned to the program in the ZONE variable. SGS and the zone are made ready for graphical output. The second parameter is the access mode whose possible values are ’READ’, ’WRITE’, and ’UPDATE’. The value ‘WRITE’ will cause the screen to be cleared; the other values cause the screen to be left as it is.
This draws a circle centered at (0.5,0.5) in world coordinates with radius RADIUS.
This closes the graphics workstation without cancelling the associated parameter. The routine SGS_CANCL is similar but does cancel the parameter.
This de-activates SGS.
A possible interface file for this program is:
After compiling and linking CIRCLE:
we can run it from ICL. In the following example, circles of different radii are plotted on different devices (things like device names and print queues are likely to be different for you):
With hard copy graphics devices, such as ‘postscript_l’, a file is created which must then be sent to the device with a DCL PRINT command.
IDI is a standard for displaying astronomical data on an image display. It is introduced in SUN/65, and the routine specifications are given in ‘An image display interface for astronomical image processing’ by D L Terrett, et al, published in Astron. Astrophys. Suppl. Ser. 76, 263-304 (1988). It has been integrated with ADAM by the usual ASSOC, ANNUL, and CANCL routines discussed in Chapter 14. An example of its use is contained in SUN/65.
IDI is intended for programs that need to manipulate images to a greater extent than can be done with GKS and its offspring. Thus, it does not supersede GKS, but offers features not available in GKS. It is not as good as GKS for producing line plots or character annotation — it does have routines to draw lines and plot text, but these are primitive and offer you little control over how the result will appear in terms of character sizes, style of line widths etc.
Its major strength is its ability to perform many types of interaction using the mouse. Like GKS, it can display an image, move the cursor, and rotate the look-up table. However, it can also scroll and zoom, blink, and read back a representation of the whole display, which can then be used to obtain a hardcopy. IDI allows these functions to be programmed in a device independent way, so a program can use any device for which IDI has been implemented.
It is not possible to mix GKS and IDI calls on the same display; the two packages use completely different display models. However, it is possible to run the packages one after the other. For example, IDI could follow GKS and the display could be opened without resetting it. However, this is an undesirable approach since the results could be unpredictable. A better solution is to use AGI to mediate between the packages.
One of the recurring problems in graphics programming is that you would like a program to know about graphics drawn by another program. For instance, you display an image of the sky, then later you want to obtain the co-ordinates of the stars within the image via the cursor. There are two ways of doing this. The first is to duplicate the display code in the cursor application, which is wasteful and inflexible. The second is to store information about pictures in a database that can be accessed by graphics programs. Immediately after a picture is created, information about its position and extent can be added to the database. This second approach is implemented by AGI which can store information about plots on any graphics device.
The AGI graphics database is stored in file AGI_USER:AGI_hostname.SDF which contains a data object named WORKSTATION comprising a set of components, one set for each device used. Each type of workstation used causes the generation of a WORKSTATION structure in the database (which is specific to each user). The PICTURE structure stores details of one or more ‘pictures’ which are visible on the workstation’s display. The AGI routines are used to create and manipulate these picture structures in the database. The AGI documentation (SUN/48) talks about ‘storing pictures’ in the database. Don’t be alarmed by this loose terminology; the picture itself isn’t stored, just the following information:
This information enables AGI to relate a particular position on the display surface to a particular position in world coordinates, and vice versa. The PNAME and COMENT fields are used to describe a ‘picture’, and the DEVICE, NDC, and WORLD fields are used to define its ‘extent’.
Each time a picture is stored in the database for a particular workstation, it is added to the end of the PICTURE array. This array acts as a push-down stack; thus the ‘last’ picture is the one added most recently to the array, and this ‘precedes’ the one added before it. This order corresponds to the visual impression of new pictures obscuring older pictures on the display screen.
The database always has a ‘current’ picture and workstation associated with it. Each workstation also has a ‘base’ picture associated with it; this fills the display area and always exists. A new picture is always created inside the current picture. The current picture for each workstation is remembered between sessions. AGI routines: The ‘objects’ manipulated by the AGI library are ‘pictures’ in the database. The basic set of routines in the library begin with the prefix ‘AGI_’. In the descriptions below, the routines will be identified by the characters which follow ‘AGI_’. They fall naturally into the following groups:
These are the usual two routines used to integrate a subroutine library with the ADAM parameter system, i.e. ASSOC and CANCL. They correspond to the OPEN and CLOSE stand-alone routines. The ‘picture’ object is identified by a picture identifier ‘picid’. The parameter with which the picture is associated is a graphics display device, normally called a workstation in GKS.
These are the three routines that actually do something, rather than just navigate around the database.
SELP changes the identity of the current picture — most AGI routines simply use the current picture but don’t change its identity.
NUPIC creates a new picture in the database and selects this as the new current picture. The information that must be provided is:
PDEL deletes all the pictures in the database for the current workstation.
These nine routines obtain information about pictures. Their names (after the ‘AGI_’) all start with ‘I’. One routine, IBASE, identifies the base picture for the current workstation. The other eight all obtain information about the current picture. Five of these, ICURP, ILAB, INAME, ICOM, and IWOCO, obtain the identifier, label, name, comment, and extent. Two others indicate whether or not the picture, IPOBS, or a set of test points, ITOBS, in the picture are obscured by a test picture. The last, ISAMD, says whether or not the picture is on the same workstation as a test picture.
These eight routines search the database for a picture with a given name, or which satisfies certain criteria. The routine names are of the form RCxy, where the ‘x’ specifies where to start the search and the direction of search, and ‘y’ can be used to specify that the picture must enclose a given test point.
The associated interface file will contain specifications like these:
This will cause a workstation to be associated with parameter DEVICE, and PICID will point to the current ‘picture’ in the database entry for this workstation. SGS will be opened using the MODE to decide whether or not to erase the existing display, and an SGS zone will be opened which will correspond to the current picture in the database. You can then use PICID to address the database using AGI and AGS routines, and ZONE to address the display using SGS routines.
Similar routines exist to interface AGI with PGPLOT and IDI. These are prefixed by ‘AGP_’ and ‘AGD_’ respectively.
Full details of the AGI routines are given in SUN/48, and a comprehensive example of its use is given in SUN/95. You can examine the coding of other examples by looking at the DISPLAY and PHOTOM routines in the KAPPA source library KAPPA_DIR:KAPPA.TLB.
Almost any graphics program requires the user to identify which graphics device is to be used. When the GKS graphics package is used, graphics devices are identified by two integers: a ‘workstation type’ and a ‘connection identifier’. No one can be expected to remember the workstation types of all available graphics devices, so a package called GNS has been provided that translates ‘friendly’ and easy to remember names into their GKS equivalents.
Most high-level graphics libraries, such as SGS, will perform the necessary name translation when a workstation is opened, so unless you are writing programs that open GKS workstations directly (by calling GOPWK) you will not need to call any GNS routines yourself.
The GNS library provides three sorts of service to the users and writers of graphics subroutine libraries and programs:
More information on GNS and descriptions of its routines are given in SUN/57. Demonstration program: A complete list of all the workstation names defined on your system can be obtained by running the program GNS_DIR:GNSRUN. After listing all the GKS names along with a short description of each workstation, the program prompts for a workstation name. If one of the names in the list (or any other valid workstation name) is entered, a simple demonstration picture is plotted on the device selected. The IDI devices are then listed and again a demonstration plot can be generated by providing an appropriate device name. If the program produces error messages you should report them to your Site Manager. However, you should not necessarily expect all workstations on the list to be usable. A device could, for example, be in use by someone else.