6 Graphics Devices and Files

6.1 Selecting a Graphics Device

You can find the list of available devices and their names with task GDNAMES. Names can be abbreviated provided they remain unambiguous. Two alternative naming schemes are supported, and the list produced by GDNAMES will include both.

PGPLOT

A general graphics device specification is of the form <file>/<type>, where <type> indicates the type of the graphics device (e.g. PostScript printer, X-window, etc.) and <file> is an optional string which indicates either a file in which the graphical output should be stored or a specification for a particular device of the specified type. For instance, m31.ps/VPS produces a file called m31.ps containing output suitable for sending to a PostScript printer in portrait mode, and xwindows2/GWM sends graphical output to the GWM X-window with name xwindows2. If the <file> string is omitted, a default device-dependent value is used (for instance, pgplot.ps for postscipt files and xwindows for X-windows).

GNS

For compatibility with previous versions of Kappa graphics devices may also be specified using a scheme that approximates closely to that of the Starlink Graphics workstation Name Service (GNS) library (see SUN/57). In this scheme a complete workstation specification is of the form <type>;<file>. This is very similar to the PGPLOT scheme described above, but the device type and file are swapped round, and the separator is a semicolon instead of a solidus. As for PGPLOT, the device file can be omitted, in which case a default is used, but note that in this case the semicolon should also be omitted. The only supported devices are those for which PGPLOT drivers are available. If a device was also available in the GKS-based graphics systems previously used by Kappa, then you can refer to it either using its PGPLOT device type or its GNS device type.

In either scheme, either the device type or the file name or the entire device specification may be replaced by a logical name, in which case the value of the logical name will be used instead.

6.1.1 Global Parameters

There is a global parameter for the graphics device. The purpose of this global parameter is ostensibly to prevent unnecessary prompting. However, there is an ulterior motive as well. The selection of devices outside of the graphics applications enables us to perform other necessary actions just once.

There is a command for selecting the current graphics device: GDSET. For example,

A selection remains in force until you change it using GDSET again, use NOGLOBALS, or delete the globals file. The current choice can be inspected via the GLOBALS command. If the global parameter is undefined you will be prompted for the device if an application requires it.

You can override the global parameter for the duration of a single application by specifying it by keyword (normally DEVICE=), or in some applications, by position. Here is an example.

6.1.2 X-windows

The most commonly used devices are X-windows. These can require a little preparation before you select a device. Starlink graphics use GWM to manage windows. It enables a window to persist between separate applications; or to be shared by different applications, potentially even running on different machines. See SUN/130 for details of GWM and how to change your X-defaults file ($HOME/.Xdefaults), but the salient points are given below.

If the window appears on a terminal or workstation other than the one running the Kappa executables you will need to redirect output to your screen, if you have not already done so for some other software. You either use the xdisplay command

or set the DISPLAY environment variable to point to the address of your screen.

You substitute your machine’s address or IP number. (Ask your computer manager.)

If you do not create the window before running Kappa, the first graphics application to open an X-windows device will create the window, using certain defaults. The defaults control amongst others the foreground and background colours, the number of colours allocated, the size and location of the window. These defaults may be altered with an X-defaults file, or a window created with the GWM xmake command.

This example makes a window of dimension 600-by-450 pixels, the background colour is black and colour for the line graphics is yellow.

The following set up to place in your X-defaults file is a reasonable compromise, as it maximises the number of colour indices for the graphics window (xwindows), and has a second graphics window (x2windows). In the defaults file there are the following lines

and you can also set the sizes of the windows too. Notice that the second device name is x2windows, but the window name is xwindows2. Don’t ask why. This confusing name rule applies also to all but the first window of the maximum of four windows allowed.

The device names can be abbreviated, to give unambiguous names. Thus you can enter xw for the xwindows device; x2w for the x2windows device; and so on. This is the reason for having device names as they are.

The following tells Kappa that this is the current device. This remains as a global parameter, so you probably will not need to issue this command that often.

6.2 Composite Hardcopy Plots

Kappa applications are modular so that you can build up more-complicated plots, and possibly add annotations with other packages especially PONGO. This is fine if the device is some sort of screen. However, care needs to be taken when using other types of device. For instance, some PGPLOT PostScript devices put the output from each command into a separate disk file. So how do you get the composite plot out on paper? There are two solutions:

(1)

the easy way—use an “accumulating” PostScript device instead. If you look at the list of device names produced by GDNAMES you will see that some of the encapsulated PostScript (EPS) devices are described as “accumulating” such as the following.

      % gdnames
      ...
      aps_p     (/AVPS)          Accumulating EPS, monochrome, portrait
      aps_l     (/APS)           Accumulating EPS, monochrome, landscape
      apscol_p  (/AVCPS)         Accumulating EPS, color, portrait
      apscol_l  (/ACPS)          Accumulating EPS, color, landscape
      ...

If you use one of these devices, each subsequent graphics application will merge its PostScript output automatically into any existing pgplot.ps file. If you display pgplot.ps using a modern PDF/PostScript viewer such OKULAR or EVINCE, the display will update automatically as each subsequent graphics application modifies the file. Once the final graphics application has been run, you can rename the pgplot.ps file to something more covenenient⁴.

To give an example, suppose we wanted to overlay a contour plot on an image.

      % gdset apscol_l
      % display $KAPPA_DIR/comwest lut=$KAPPA_DIR/spectrum_lut mode=ra axes
      % contour noclear mode=au noaxes \\
      % mv pgplot.ps myplot.ps
  

(2)

The hard way—use PSMERGE to merge separate PostScript files. If you use one of the non-accumulating PostScript devices, the output from each graphics application goes into a separate file which must then be merged. Here is what you must do.

• Select one of the non-acculumlating encapsulated PostScript device, be it colour or monochrome.
• Produce your graphics, being careful to rename the output file (usually pgplot.ps) created by each command to avoid it being over-written by the output from the next command. Alternatively, you can specified the device to use separately when running each command, including an explicit unique file name in each device specification (see above).
• Use PSMERGE (the Starlink version, usually in /star/bin) to combine the plots.

To use the same example as above:

      % gdset epsfcol_l
      % display $KAPPA_DIR/comwest lut=$KAPPA_DIR/spectrum_lut mode=ra axes
      % mv pgplot.ps display.ps
      % contour noclear mode=au noaxes \\
      % mv pgplot.ps contour.ps
      % psmerge display.ps contour.ps  > myplot.ps
      % rm display.ps contour.ps

or alternatively:

      % display $KAPPA_DIR/comwest device="epsfcol_l;display.ps" \
                lut=$KAPPA_DIR/spectrum_lut mode=ra axes
      % contour noclear device="epsfcol_l;contour.ps" mode=au noaxes \\
      % psmerge display.ps contour.ps  > myplot.ps
      % rm display.ps contour.ps

to form the merged graphic. You then print myplot.ps to the colour PostScript printer. PSMERGE also has options for scaling and rotating plots.