The Graphics Database in Action

The following examples assume that KAPPA is loaded and the graphics device--an X-window containing a plotting area of 850 by 500 pixels--is available. To create such a window use the xmake (SUN/130) command:

     % xmake xwindows -height 500 -width 850 -colours 64

This command limits the number of colours used by the X-window to 64. It is usually a good idea to be sparing with X-window colours. Creating X-windows with too many colours can restrict the availability of colours for other X applications.

First of all we make the X-window the current graphics device (as described in in global device names.) This selection will remain in force until changed. The following command would not be necessary if the global parameter already had this value:

     % gdset xwindows

Next we shall clear the X-window, and empty the graphics database of xwindows pictures (pictures relating to other graphics devices are retained):

     % gdclear

The display is now clear, but one picture remains in the graphics database; this is the BASE picture and corresponds to the entire plotting area. To understand why this BASE picture is required we need to introduce the idea of the current picture.

At any time, one of the pictures stored within the graphics database is nominated as the current picture. All graphical applications are written so that the graphical output that they create is scaled to fit within the current picture. Thus, the plotting area used by a graphics application can be controlled by selecting a suitable current picture before running the application. Since we have just cleared the database, the only picture remaining is the BASE picture, which consequently becomes the current picture. This allows subsequent applications to draw in any part of the plotting area.

We now load a grey-scale colour table into the X-windows and display an IRAS 12 $\mu$ m image of M31. The pixel values are scaled so that 10% of the pixels appear as pure black, and 1% appear as pure white. We ensure that no annotated axes are produced (this will result in the image being a little larger since no margins need to be left for the axes):

     % lutgrey
     % display $KAPPA_DIR/iras noaxes
     MODE - Method to define the scaling limits /'FLASH'/ > perc
     PERCENTILES - Percentiles for scaling /[10,90]/ > 10,99
     Data will be scaled from 0.05178363 to 1.051904.

Figure 1: An IRAS 12 micron image of M31 displayed in the middle of the BASE picture. The X-window should now look like Figure  1. The application has displayed the image in the middle of the current picture (the BASE picture), and has made it as large as possible, subject to the constraints that it must lie entirely within the current picture. Note, as with many IRAS images, equatorial north is downwards in this image

Let's now use the PICLIST command to look at the contents of the graphics database (press return in response for the prompt for Parameter PICNUM):

     % piclist

       No. Name             Comment                   Label            Ref
       -------------------------------------------------------------------
     C   1 BASE             Base picture
         2 DATA             KAPPA_DISPLAY                              Ref
     PICNUM - Number of new current picture /!/ >

This shows us that there are now two pictures in the database, listed in the order in which they were created. The current picture is still the base picture, as indicated by the letter C at the left of the line describing picture number 1. The second picture was created by the KAPPA application DISPLAY, and has the name DATA, indicating that it contains a representation of a set of data values. DATA is one of four standard picture names. BASE is another of these standard names. We shall come across the other two shortly. The PICLIST application allows you to select a new current picture by supplying a picture number in response to the prompt for parameter PICNUM. Accepting the null default by pressing return causes the current picture on entry to be retained.

The above use of DISPLAY illustrates an important rule regarding the behaviour of most graphical applications; the current picture is not changed by applications that produce graphical output.¹⁰If it were not for this rule, pictures would become progressively smaller, vanishing into the distance, since new pictures cannot be drawn outside the current picture.

We will now display an optical image of M31. This time we will arrange for it to be placed towards the left hand side of the X-window. To do this, we first clear the whole X-window and graphics database using GDCLEAR:

     % gdclear

We now create a new picture using the PICDEF command (note, the "\" characters are needed to prevent the UNIX shell interpreting the square bracket characters):

     % picdef mode=cl fraction=\[0.6,1.0\] outline=no

The MODE parameter specifies the position of the new picture within the BASE picture; in this case "cl" indicates that the new picture is to be centred ("c") vertically within the BASE picture and placed at the left ("l") hand edge. The FRACTION parameter specifies the dimensions of the picture; the first value (0.6) gives the horizontal size of the picture as a fraction of the horizontal size of the BASE picture, and the second value (1.0) gives the vertical size of the picture as a fraction of the vertical size of the BASE picture. Thus, the new picture is just over half the width of the BASE picture, and is the full height of the BASE picture. The OUTLINE parameter specifies whether a box should be drawn on the screen showing the outline of the new picture. In this case we switch this option off.

If we run PICLIST again, we get:

     % piclist

       No. Name             Comment                   Label            Ref
       -------------------------------------------------------------------
         1 BASE             Base picture
     C   2 FRAME            KAPPA_PICDEF
     PICNUM - Number of new current picture /!/ >

The picture created earlier by DISPLAY was deleted when we ran GDCLEAR. The BASE picture is still there (of course), and we also have the picture created by PICDEF. This is a FRAME picture, another of the four standard picture names. A FRAME picture acts as a `frame' for other pictures. A FRAME picture can itself contain other nested FRAME pictures, together with DATA and KEY pictures. The picture created by PICDEF is the current picture (indicated by the letter C again), and so subsequent graphics applications will arrange for any pictures they create to fall entirely within this FRAME picture.

Now display the image, this time including annotated axes around the edges.¹¹ DISPLAY will ensure that all its output (both the image and the axis annotation) fall within the current picture (i.e. the picture created by PICDEF above). We scale the pixel values to produce a negative image in which 1% of the pixels appear black and 30% appear white:

     % display axes
     IN - NDF to be displayed /@$KAPPA_DIR/iras/ > $KAPPA_DIR/m31
     MODE - Method to define scaling limits /'perc'/ >
     PERCENTILES - Percentiles for scaling /[10,99]/ > 99,30
     Data will be scaled from 10854.78 to 3889.016.

Figure 2: Optical M31 image with axes displayed toward the left of the BASE picture.

The X-window should now look like Figure  2. We can use PICLIST again to list the pictures stored in the database:

     % piclist
       No. Name             Comment                   Label            Ref
       -------------------------------------------------------------------
         1 BASE             Base picture
     C   2 FRAME            KAPPA_PICDEF
         3 FRAME            KAPPA_DISPLAY
         4 DATA             KAPPA_DISPLAY                              Ref
     PICNUM - Number of new current picture /!/ >

There are four pictures this time; the BASE picture, the picture created by PICDEF (number 2), and two pictures created by DISPLAY (numbers 3 and 4). Picture number 2 was made the current picture by PICDEF and as explained above, DISPLAY did not change this. DISPLAY creates two pictures, one (the DATA picture) containing just the image area itself, and another (the FRAME picture) to act as a frame for the DATA picture and the annotated axes.

Let's say you wanted to display an enlarged sub-section of the image in the top-right corner of the X-window. First, you need to decide on the bounds of the sub-section to be displayed. Here, we use a graphics cursor to indicate the bottom left and top-right corners of a box enclosing the required area. Click the left mouse button at the bottom left and top right corners of a box enclosing the required sub-section of the image:

     % cursor showpixel plot=box maxpos=2

       Use the cursor to select up to 2 positions to be reported.
         To select a position press the space bar or left mouse button
         To forget the previous position press "d" or the middle mouse button
         To quit press "." or the right mouse button

      Picture comment: KAPPA_DISPLAY, name: DATA, reporting: SKY co-ordinates

      RA = 0:41:33.5 (hh:mm:ss.s)   Dec = 40:33:01 (ddd:mm:ss)
      (172.4       78.2)

      RA = 0:39:25.0    Dec = 40:54:17
      (212.8       113.9)

Figure 3: A box is drawn using the CURSOR application.

The box I selected is indicated in Figure  3.

When an application such as DISPLAY produces a DATA picture containing a representation of an NDF, it saves a copy of the NDF's WCS component  (which contains co-ordinate Frame  information) with the DATA picture in the graphics database. When CURSOR subsequently reports a position, it uses this saved WCS information to convert the graphics co-ordinates at the cursor into any of the available co-ordinate Frames. By default, CURSOR reports positions in the co-ordinate Frame that was current when the NDF was displayed (RA/DEC in this case), but other co-ordinate Frames may be requested using the FRAME parameter (e.g. FRAME=PIXEL displays pixel co-ordinates). In addition to the co-ordinate Frames inherited from the NDF, there are also four extra Frames available.

GRAPHICS

- specifies positions in terms of millimetres from the bottom left corner of the graphics device (e.g. X-window or paper).

BASEPIC

- similar to GRAPHICS but specifies positions in a normalised co-ordinate system in which the shorter dimension of the screen or paper has a length of 1.0 (the scales on both axes are equal).

NDC

- similar to BASEPIC but specifies positions in a normalised co-ordinate system in which the bottom-left corner has co-ordinates (0, 0) and the top-right corner has co-ordinates (1, 1). Thus, for a non-square device the scales on the two axes will be different.

CURPIC

- similar to BASEPIC except that it covers only the specified picture. Thus, the bottom-left corner of each picture is at $(0,~0)$ and the shorter dimension of each picture has length 1.0.

Going through the parameters supplied to the above CURSOR command, the first one (SHOWPIXEL) causes the pixel co-ordinates at each selected position to be displayed, in addition to the co-ordinates selected using Parameter FRAME (which defaults in this case to RA/DEC since FRAME was not specified). For instance, the first position is at a right ascension of $0^{\rm h} 41^{\rm m} 33.5^{\rm s}$ and a declination of $40$ $^\circ$ $33$ $^\prime$ $01$ $^\prime$ $^\prime$ , and has pixel co-ordinates $(172.4,78.2)$ .¹²The second parameter (PLOT=BOX) causes a box to be drawn on the screen between each pair of positions. There are several other allowed values for the PLOT parameter, which mark the positions in different ways (markers, poly-lines, chains, text, etc.). The last parameter (MAXPOS=2) is purely a convenience, and causes the application to terminate when two positions have been supplied. Without this, you would need to press the right mouse button once the two positions had been given to indicate that you do not want to supply any more positions.

We now need to create a new FRAME picture to contain the magnified image section. We have seen how PICDEF can be used to create a FRAME picture of a given size at a given position within the BASE picture, but there are also several other ways in which PICDEF can be used. Here, we use PICDEF in `cursor' mode; the bottom left and top-right corners of the new picture are specified by pointing and clicking with the mouse.¹³ We use this mode to create a new FRAME picture occupying the area to the top right of the existing image:

     % picdef mode=cursor nooutline

       Use the cursor to select 2 distinct points.
         To select a point press the space bar or left mouse button
         To quit press "." or the right mouse button

     Co-ordinates are ( 0.9155139, 0.5470942 ) and ( 1.683106, 0.9799599 )

The co-ordinates displayed by PICDEF are BASEPIC co-ordinates.

We now display the required image section in this new FRAME picture. The screen output from CURSOR above shows that the selected image section runs from pixel 173 to 213 on the first (X) axis, and from pixel 79 to 114 on the second (Y) axis. To display just this section we include the pixel bounds in the specification of the input NDF when we run DISPLAY:

     % display border noaxes mode=scale high=3889.016 low=10854.78
     IN - NDF to be displayed /@m31/ > m31(173:213,79:114)
     Data will be scaled from 10854.78 to 3889.016.

Figure 4: The selected section of the NDF is re-displayed.

The X-window should now look like Figure  4.

The string m31(173:213,79:114) is called an NDF section specifier. These are described more fully here. The image is surrounded by a thin border instead of fully annotated axes in order to make the image larger. This is achieved using the BORDER and NOAXES keywords (equivalent to setting BORDER=YES and AXES=NO). The pixel scaling was specified explicitly using parameters HIGH and LOW in order to ensure that the image was displayed with the same grey-scale as the main image (the high and low data values are the data values corresponding to black and white--or white and black if reversed - and were reported when the main image was displayed earlier).

Remember the IRAS image of M31 we started with? We'll now overlay contours of the IRAS image on top of the magnified section of the visual image we have just displayed. Don't forget, these two images have not been aligned--for instance, north is up in the visual image, but down in the IRAS image. However, both images have information within the WCS component describing the relationship between pixel co-ordinates and RA/DEC. This WCS information was stored with the DATA picture created by DISPLAY above, and so can be used by the CONTOUR application in order to draw the IRAS contours in alignment with the displayed visual image.¹⁴ In addition, we also use CURSOR to mark a position with a text string giving a title for the contour plot:

     % contour noclear noaxes nokey iras mode=perc percentiles=\[55,75,95\]
     Alignment has occurred within the SKY Domain.

     Contour heights used:
     0.5499523,   0.7577766,   1.012756.

     % cursor plot=text maxpos=1 minpos=1 strings='"IRAS 12 \gmm contours"'

     Use the cursor to select 1 position to be reported.
       To select a position press the space bar or left mouse button
       To quit press "." or the right mouse button

       Picture comment: Base picture, name: BASE, reporting: BASEPIC
       co-ordinates
       X = 1.308796      Y = 0.9839679

Figure 5: IRAS contours overlayed on the visual image.

The X-window should now look like Figure  5.

The most important parameter in the above invocation of CONTOUR is the NOCLEAR keyword (equivalent to CLEAR=NO). This tells CONTOUR not to clear the graphics device before drawing the contours. Instead, CONTOUR looks for an existing DATA picture contained within the current picture. If one is found, then CONTOUR attempts to align the contours using the WCS information stored with the existing DATA picture. In our case, the current picture is still the top-right FRAME picture created by PICDEF, and so the contours are aligned using the WCS information stored with the DATA picture contained within this FRAME picture (i.e. the magnified image section). CONTOUR tells us that this alignment occurred within the `SKY Domain'--if either of the two NDFs had not contained a calibration in a suitable celestial co-ordinate system, then alignment on the sky could not have been performed. In this case, CONTOUR would have aligned the contours in the `PIXEL Domain' (i.e. in pixel co-ordinates).

Since we produced no annotated axes, a title string was added using the text drawing abilities of CURSOR. The pointer was positioned above the contour plot, and the left button clicked. The specified text string was drawn centred at this cursor position. Note, the string \gm is a `PGPLOT escape sequence' that represents the Greek letter mu ("$\mu$ "). See the PGPLOT manual for a detailed description of the available escape sequences.

Let's say we wanted to compare the data values in the visual and IRAS images along a given line through the magnified sub-section. To do this, we first use the application PROFILE to create a pair of one-dimensional NDFs containing the data values along the line in each of the two images. We then display these one-dimensional NDFs using application LINPLOT. First we choose the line along which the profiles are to be taken, using CURSOR (again!):

     % cursor plot=chain marker=3 style='colour=white' outcat=zz maxpos=2

     Use the cursor to select up to 2 positions to be reported.
       To select a position press the space bar or left mouse button
       To forget the previous position press "d" or the middle mouse button
       To quit press "." or the right mouse button


     Picture comment: KAPPA_CONTOUR, name: DATA, reporting: SKY co-ordinates
       RA = 0:41:22.7 (hh:mm:ss.s)   Dec = 40:35:12 (ddd:mm:ss)
       (175.8467    81.82527)

       RA = 0:39:56.5    Dec = 40:50:27
       (202.917     107.3986)

The pointer is positioned at the two ends of the required profile, and the left button clicked at each position. The supplied positions are marked by two markers of PGPLOT type 3 (small crosses), and a white line is drawn between them (forming a `chain'). The selected positions are written to an output catalogue stored in file zz.FIT. We now sample the data in the two images along this profile to create a pair of one-dimensional NDFs (m31_prof and iras_prof):

     % profile m31 incat=zz out=m31_prof
       Alignment has occurred within the SKY Domain.
       Profile contains 38 samples.

     % profile iras incat=zz out=iras_prof
       Alignment has occurred within the SKY Domain.
       Profile contains 38 samples.

We want to draw the two line profiles in a new plot in the clear area at the bottom right of the X-window. We therefore need to create a new FRAME picture. This time we use PICDEF in `XY mode', in which the bounds of the new FRAME picture are given explicitly using parameters UBOUND and LBOUND (we could have used cursor mode again; we use XY mode just to explore the different possibilities):

     % picdef mode=xy lbound=\[0.93,0.03\] ubound=\[1.67,0.54\] nooutline
       Bounds are ( 0, 0 ) and ( 1.701635, 1 )

The bounds are supplied in the BASEPIC Frame (the bounds reported by the application are the bounds of the entire BASE picture). The new FRAME picture is, as usual, made the current picture by PICDEF and so any subsequent graphics applications will draw in the new FRAME picture.

We now draw the first of the two line profiles:

     % linplot m31_prof style='"tickall=0,colour(curve)=black, \
               drawtitle=0,label(2)=DSS data value (black)"'

Figure 6: Data trace through the visual image.

The X-window should now look like Figure  6. The plotting attributes specified by the STYLE parameter do the following; tickall=0 stops tick marks from being drawn on the un-labelled edges (i.e. the top and right edges); colour(curve)=black specifies that the data curve is to be drawn in black; drawtitle=0 prevents a title being drawn at the top of the plot; label(2)=DSS data value (black) specifies the textual label for the left hand edge.

We now draw the second line plot over the top of the first line plot:

     % linplot iras_prof noclear noalign style='"edge(2)=r,tickall=0, \
               colour(curve)=white,drawtitle=0, \
               label(2)=IRAS data value (white)"'

Again, the NOCLEAR keyword prevents LINPLOT from clearing the graphics device before drawing the new line plot. Instead, the new line plot is drawn within the same axes as any existing line plot within the current picture. By default, the new line plot would adopt the bounds of the two existing axes. This would be inappropriate in this case since the two images have very different data scales. To prevent this, we specify the NOALIGN keyword, which causes the default bounds for the new axes to be determined from the supplied data instead of the existing line plot. The STYLE parameter is similar to the previous line plot except that the data values are annotated on the right hand edge (edge(2)=r), the data curve is drawn in white, and data label is different.

Figure 7: Data traces through both images.

The X-window should now look like Figure  7.

As a final touch, we will add two `warp' lines to the display joining the corners of the box marking the enlarged image area to the corresponding corners on the enlarged image. CURSOR can be used to draw these lines, but we need to take a little care. Normally, graphics produced by CURSOR will be clipped at the edge of the picture in which the supplied positions fall. In our case, the required lines start in one picture (the main image display DATA picture), but end in another (the magnified image DATA picture). To avoid the lines being clipped when they leave the main image DATA picture, we first ensure that the current picture is the BASE picture (i.e. the whole screen), and we tell CURSOR to report positions within the current picture. Normally, CURSOR reports each position within the most recent picture under the cursor, but setting parameter MODE=CURRENT when running CURSOR means that the reported positions always refer to the co-ordinate system of the current picture. So, first make the BASE picture the current picture. This is done using PICLIST, remembering that the BASE picture is always picture number 1:

     % piclist picnum=1

We now run CURSOR to draw the first warp line:

     % cursor plot=poly mode=current maxpos=2

Position the pointer over the top left corner of the black box marking the selected image section in the main image display, and click the left button. Then position the pointer over the top left corner of the border surrounding the enlarged image display, and click again. A line is drawn between these two points.

We now run CURSOR again to draw the second warp line:

     % cursor plot=poly mode=current maxpos=2

Point and click over the bottom right corners of the two boxes this time. The final X-window should look now look like Figure  8.

Figure 8: The complete display with warps.