An Example

As an illustrated example, this section describes how to produce a PostScript file containing a plot similar to that in Figure  8. For clarity (at the time), the earlier sections of this chapter did not adhere to either of the tips given above when prototyping in an X-window; that is, we did not choose the shape of the X-window to match our PostScript device, and we did not save the output from each run of CURSOR in a positions list file. For this reason, the steps taken here are a little more complicated than they need to be, and do not mimic exactly the steps taken while prototyping.

First, select and clear the graphics device. We choose a monochrome, portrait, encapsulated PostScript device:

   % gdset epsf_p
   % gdclear

We will sometimes need to specify positions within the BASE picture. To do this we can either use the GRAPHICS, the BASEPIC or the NDC Frame, all of which span the entire graphics device. GRAPHICS is an absolute co-ordinate system giving millimetres from the bottom left corner of the graphics device, and BASEPIC is a normalised co-ordinate system in which both axes have the same scale and the shorter dimension of the graphics device has length 1.0¹⁸. The BASEPIC Frame is usually easier to work with since it does not depend on the size of the paper. To determine the bounds of the available plotting space in the BASEPIC Frame, use GDSTATE, having first ensured that the BASE picture is the current picture (this will be the case at the moment since we have just cleared the database using GDCLEAR):

   % gdstate

   Status of the epsf_p graphics device...

      The current picture is a BASE picture.
      Comment: Base picture
      Current co-ordinate Frame: BASEPIC

      Picture bounds in the BASEPIC Frame:
         Axis 1 (X) : 0.000 to 1.000
         Axis 2 (Y) : 0.000 to 1.455

The choice of a portrait PostScript device may have surprised you, given that Figure  8 seems more naturally to fit into a landscape page. Portrait mode was chosen so that the final plot appears up-right when included in a document. If landscape mode had been chosen, the final plot would have been rotated by 90$^\circ$ when included in a latex document such as this one, requiring the page to be viewed on its side. However, if we use the entire portrait page, we will have too much vertical space between the components of the plot. To avoid this we only use the bottom third (roughly) of the page--that is, we pretend that the top of our `page' is at 0.6 instead of 1.454659.

We first create a FRAME picture at the left hand side of the page covering the full height of our reduced `page' and 0.6 of the width. We specify the upper and lower bounds of the picture within the BASEPIC Frame, using the limits found above, giving the FRAME picture the label `main' so that we can easily re-select the picture later. We then display the optical image within it, including annotated axes:

   % picdef mode=xy lbound=\[0.0,0.0\] ubound=\[0.6,0.6\] outline=no
   % piclabel main
   % display m31 axes mode=perc percentiles=\[30,99\] style="'colour=black,size=0.6'" \
             margin=\[0.2,0.02\]
   % mv pgplot.ps display1.ps

Note, we are using a monochrome PostScript device, and so the colour of all annotation produced by DISPLAY was set to black using the STYLE parameter. This is done for all applications that produce graphical output. We also request text 0.6 of the default size. We specified the MARGIN parameter when running DISPLAY in order to reduce the margin on the right hand side of the image. By default, DISPLAY leaves a margin equal to 0.2 of the width of the DATA picture. We reduced this to 0.02 to make more room for the other components of the plot (the first value supplied for MARGIN is the bottom margin and is left at 0.2). Note the mv command at the end of the above sequence. This renames the output PostScript file created by DISPLAY so that it is not over-written by subsequent graphics commands. Throughout the rest of this example, we will save each required PostScript file in this way.

We now draw a box over this image to mark the `selected region' indicated in Figure  3. In this particular case, we use LISTMAKE to create a positions list holding the RA and DEC at the two opposite corners of the box. Alternatively, we could have saved the output from CURSOR while prototyping, using the OUTCAT parameter. In either case, we use LISTSHOW to draw the box:

   % listmake ndf=m31 outcat=boxpos
     POSITION - A position for the output list /!/ > 0:41:33.5 40:33:01
     POSITION - A position for the output list /!/ > 0:39:25.0 40:54:17
     POSITION - A position for the output list /!/ >
   % listshow boxpos plot=box style='colour=black'
   % mv pgplot.ps box.ps

Specifying ndf=m31 resulted in LISTMAKE interpreting the supplied positions as positions within the current co-ordinate Frame of the NDF m31. It also results in all the WCS  information being copied from the NDF into the output positions list.

We now create a Frame in the top-right corner of the reduced `page' in which a magnified image of the selected region will be displayed. The picture occupies the remainder of the width left over by the main image (0.4 of the total width) and half the height.:

   % picdef mode=xy lbound=\[0.6,0.3\] ubound=\[1.0,0.6\] outline=no

We now display the selected image section within the FRAME picture just created, and overlay contours from iras.sdf. We draw the border with twice the default width:

   % display 'm31(173:213,79:114)' border noaxes mode=scale low=3889 high=10854.78 \
              borstyle='width=2'
   % mv pgplot.ps display2.ps
   % picdata
   % piclabel mag
   % contour noclear noaxes nokey iras mode=perc percentiles=\[55,75,95\]
   % mv pgplot.ps contour.ps

What are those two extra commands in the middle? Well, we will need to be able to re-select the DATA picture holding the image when we come to draw the warp-lines. To do this we need to label the picture now. For this reason, we use PICDATA to select the DATA picture created by DISPLAY as the current picture, and then use PICLABEL to give the label "mag" to the picture.

We now display a title above this DATA picture. The string is centred horizontally within the enclosing FRAME picture (i.e. half way between 0.6 and 1.0), and drawn so that its bottom edge is placed at the top of the Frame:

   % listmake frame=basepic outcat=ttlpos
     POSITION - A position for the output list /!/ > 0.8 0.6
     POSITION - A position for the output list /!/ >
   % listshow ttlpos plot=text strings='"IRAS 12 \gmm contours"' just=bc
   % mv pgplot.ps title.ps

LISTMAKE is used to store the position in a positions list, and then LISTSHOW is used to draw the title. Again, we could have saved the output from CURSOR in a positions list while prototyping, instead of using LISTMAKE to create the positions list. The JUST parameter is set to bc so that the title string is displayed with its bottom centre at the supplied position.

We now draw the line marking the path of the profiles that will be displayed later. We draw them in white so that they show up against the predominantly dark background of the image:

   % listmake ndf=m31 outcat=prfpos
     POSITION - A position for the output list /!/ > 0:41:22.7 40:35:12
     POSITION - A position for the output list /!/ > 0:39:56.5 40:50:27
     POSITION - A position for the output list /!/ >
   % listshow prfpos plot=chain marker=3 style="'colour=white,width=3'"
   % mv pgplot.ps line.ps

The line is drawn with three times the default width. We now create the profiles as before:

   % profile m31 incat=prfpos out=m31_prof
   % profile iras incat=prfpos out=iras_prof

We now create a FRAME picture occupying the remaining area at the bottom right corner of the page, and display the two profiles in it. We use line style to differentiate the two curves, instead of colour as we did when prototyping:

   % picdef mode=xy lbound=\[0.6,0.0\] ubound=\[1.0,0.3\] outline=no
   % linplot m31_prof style=^style1 keystyle='size=0.7'
   % mv pgplot.ps m31_prof.ps
   % linplot iras_prof noclear noalign style=^style2
   % mv pgplot.ps iras_prof.ps

The appearances of the two plots are controlled by the two plotting styles contained in the text files style1 and style2. style1 contains the following attribute settings:

   tickall=0
   colour=black
   gap(2)=1000
   drawtitle=0
   label(2)=DSS data value (solid)
   textlabgap(1)=0.02
   labelunits=0

The file style2 contains the following attribute settings:

   edge(2)=r
   gap(2)=0.2
   tickall=0
   colour=black
   style(curve)=2
   drawtitle=0
   label(2)=IRAS data value (dashed)
   textlabgap(1)=0.02
   labelunits=0

Now comes the complicated bit--the warp lines! The problem is that we used the cursor to define the start and end of these lines when prototyping. This was good enough for an X-window that has relatively low resolution, but will not do for PostScript. We cannot place the cursor accurately enough to ensure that there is no visible gap between the end of the line and the corresponding box corner when using PostScript, so we cannot use the positions found while prototyping. The only way to ensure that the lines join up properly with the box corners is to use the co-ordinates of the box corners to define the lines. First, we need to transform the box corners into the BASEPIC Frame since both ends of each line must be given within the same co-ordinate Frame.

We start with the `selection box' drawn over the main image. The corners of this box are currently stored in the boxpos positions list. This file contains the RA and DEC at the corners of the box, together with WCS information copied from the NDF m31. But this does not include the BASEPIC, NDC or CURPIC Frame, which are only available within the WCS information stored with graphics database pictures. In order to find the BASEPIC co-ordinates at the corners of the box, we need to align the RA/DEC values in the positions list with the WCS information stored with the first DATA picture we created (the main image), and then display the corresponding BASEPIC co-ordinates. LISTSHOW can do this, but we need to change the current picture first. At the moment, the current picture is the FRAME containing the line plots. If we did not change the current picture LISTSHOW would assume that the supplied RA/DEC values refer to the line plots (not to the main image), and would consequently give the wrong BASEPIC co-ordinates. We use PICSEL to select the FRAME picture containing the main image (so that it becomes the current picture), and then run LISTSHOW:

   % picsel main
   % listshow boxpos plot=blank frame=BASEPIC

     Title: M31 (Digitised Sky Survey)

      Position        X           Y
     identifier
     -----------------------------------

       #1         0.3657834   0.1911708
       #2         0.4269177   0.245274

The parameter assignment PLOT=BLANK tells LISTSHOW to search the graphics database for a picture with which the positions in boxpos can be aligned, but without marking the positions in any way on the screen. Doing this means that the co-ordinate Frames stored with the picture are available when specifying a value for Parameter FRAME. This is necessary because the BASEPIC Frame is only available within graphics data base pictures since it describes positions on a graphics device.

We now find the BASEPIC co-ordinates at the corners of the magnified image. The most simple way of doing this is to use the same RA/DEC positions. The problem with this approach is that the bounds of the magnified image were rounded to a whole number of pixels and so may not correspond exactly to the RA an DEC at the corners of the selection box. A more accurate method is to use the pixel indices at the corners of the image section to define the box corners. We first need to create a positions list holding the pixel co-ordinate bounds of the image section, remembering to reduce the lower pixel index bounds by 1.0 in order to convert the integer pixel indices into floatingpoint pixel co-ordinates (see here for more information about pixel co-ordinates and indices):

   % listmake frame=pixel dim=2 outcat=magpos
     POSITION - A position for the output list /!/ > 172.0 78.0
     POSITION - A position for the output list /!/ > 213.0 114.0
     POSITION - A position for the output list /!/ >

We now need to use LISTSHOW to get the corresponding BASEPIC co-ordinates, aligning the above PIXEL co-ordinates with the DATA picture holding the magnified image section. Another slight complication arises here since the required DATA picture is obscured by the DATA picture holding the IRAS contours. Pixel co-ordinates in the IRAS image are totally different to those in the grey-scale image, and so we need to make sure that LISTSHOW is using the correct DATA picture. However, we labelled the required DATA picture when it was created and so we can just use PICSEL to re-select it:

   % picsel mag
   % listshow magpos plot=blank frame=BASEPIC
     Alignment has occurred within the PIXEL Domain.


     Title: Output from LISTMAKE

      Position        X           Y
     identifier
     -----------------------------------

       #1         0.6473798   0.3159827
       #2         0.9524395   0.5838399

We now create a positions list containing the BASEPIC co-ordinates at the ends of the upper warp line, and draw it. By default, LISTSHOW draws within the most recent DATA picture contained within the current picture. Since the line is not contained within a single DATA picture, we need to tell LISTSHOW to draw within the BASE picture. This is done by setting Parameter NAME to BASE (we also revert to drawing in black):

   % listmake frame=basepic outcat=war1pos
     POSITION - A position for the output list /!/ > 0.3657834 0.245274
     POSITION - A position for the output list /!/ > 0.6473798 0.5838399
     POSITION - A position for the output list /!/ >
   % listshow war1pos plot=poly style='colour=black' name=base
   % mv pgplot.ps war1.ps

The last drawing we need to do is to create the second warp line in the same way:

   % listmake frame=basepic outcat=war2pos
     POSITION - A position for the output list /!/ > 0.4269177 0.1911708
     POSITION - A position for the output list /!/ > 0.9524395 0.3159827
     POSITION - A position for the output list /!/ >
   % listshow war2pos plot=poly name=base
   % mv pgplot.ps war2.ps

We now have separate PostScript files containing the output from all the above applications. These are stacked together in the order they were created to produce the final encapsulated PostScript file:

   % psmerge -e display1.ps box.ps display2.ps contour.ps title.ps \
                line.ps m31_prof.ps iras_prof.ps war1.ps war2.ps > total.eps

The file total.eps is displayed in Figure  9.

Figure 9: The equivalent plot produced directly in PostScript.