Genie Graphics
D. S. Sivia :
March, 1996
ï Device options
ï Display/Plot command
ï Windows and coordinates
ï Drawing and modification
ï Cursor interaction
ï Graphics procedures
ï Hardcopy options
Device Options
Before you can begin any graphics plotting, you need to select a device; i.e. you need to choose the type, and size, of the "paper" that you want to draw on.
>> DEVICE / OPEN "device-type" width height
The default device type is "XW", which is an interactive X-window. Others include "TEK", "PS", "VPS", "CPS", "VCPS", "GIF" and "HPGL"; most of the latter are hardcopy devices and output files like pgplot.ps, pgplot.gif, and so on. The size of the page, defined by the optional parameters width and height, is taken to be given in inches.
>> DEVICE / CLEAR
>> DEVICE / CLOSE
These commands clear and close the graphics device, respectively, and have no other parameters. The syntax and options for the DEVICE command can be obtained by typing:
>> DEVICE / HELP
Display / Plot
If you read in a spectrum from a RAW or intermediate GENIE file, then you can quickly put up a plot by using the GENIE II compatible DISPLAY command. In other words, you could have a sequence of instructions like:
>> SET / FILE "/usr/dsusers/dss/hrp07092.fst"
>> S = GET(1)
>> DISPLAY S Xmin Xmax Ymin Ymax
The DISPLAY, PLOT and ALTER commands are designed to mimic GENIE II instructions; the output will also be similar. For example, one could envisage the following commands:
>> ALTER / BINNING 50
>> PLOT / MARKERS S
This would bin the spectrum in groups of 50 and overlay the result with crosses on the underlying (histogram) plot. The syntax and options for these commands can be obtained by typing: DISPLAY / HELP , PLOT / HELP , ALTER / HELP and TOGGLE / HELP . A further useful facility is provided by the ZOOM command:
>> ZOOM
This will prompt you for two cursor clicks, which define the bottom left-hand corner and the top right-hand corner of the desired region to be zoomed.
Windows and Coordinates
If you want to construct a plot to your own liking, or if you have read in a non-GENIE type file ( e.g. an ASCII "X Y E" file), then the first thing you must do is decide where on the "paper" the plot should go. This is done by invoking the WINDOW command; the syntax and option can be obtained by typing:
>> WINDOW / HELP
A simple example would be:
>> WINDOW / SCALED
0.2 0.9 0.2 0.9 0 10 0 100
The first four numbers define where the plotting box will go on the page; they refer to device coordinates, where (0,0) is the bottom left-hand corner and (1,1) is the top right-hand corner. The next four numbers relate to world coordinates, or the X and Y range that will be seen on the plot. This distinction between the two coordinate systems is illustrated in the figure on the following page. The X and Y range of the plot can be chosen automatically by GENIE if the arrays of X and Y coordinates is given in the parameter-list and the AUTOSCALED qualifier is used; for example:
>> WINDOW / AUTOSCALED
0.2 0.9 0.2 0.9 S.X S.Y _ $BLUE
where S is the name of the workspace containing the pertinent data, and the inclusion of the $BLUE parameter will paint the chosen window blue instead of using the default background colour.
Several windows can be placed on a page; if these are overlapping, then an inset diagram can be generated. In other words, set up a window and plot something in it; then, set up another window and plot something else in that.
Drawing Primitives
A plot can be constructed in the desired manner by calling a sequence of drawing commands. The options and syntax can be obtained by typing:
>> DRAW / HELP
Axes can be drawn, for example, by invoking the AXES qualifier:
>> DRAW / AXES
colour line-width text-size
font
If no parameters are given, then the default values of $BLACK, 1, 1.0 and $NORMAL are used for drawing a numerically annotated box around the chosen window (a text-size of 1.5 is probably preferable to the default). There are also sub-qualifiers / XLOG and / YLOG which will annotate the axes logarithmically. Unlike the TOGGLE / LOGX equivalent for DISPLAY, however, DRAW expects the workspace to be plotted to contain the logarithm of the X and Y values; the same goes for the X and Y world-coordinate range given in WINDOW / SCALED. The following would plot the data in workspace S as points with Y error-bars:
>> DRAW / MARKERS S.X S.Y $GREEN $CIRCLE 1.5 2
>> DRAW / ERRORS / VERTICAL S.X S.Y S.E
$GREEN 2
A dashed line from workspace FIT can be overlain by typing:
>> DRAW / PLOT FIT.X FIT.Y $RED $DASH
The graph can be labelled by using the / LABELS and / TITLE qualifiers; further annotation can be obtained by invoking the / TEXT option. For example:
>> DRAW / TEXT 1.3 85.0 "(a)" _ 1.5 _ $ITALIC
will write (a) , in text-size 1.5, at (left-justified) world coordinates (1.3,85) , which might be the top left-hand corner of the current window. There is also the facility to draw lines, boxes and polygons by using DRAW / LINE, DRAW / BOX and DRAW / POLYGON ; the latter can be shaded with colours, if required.
Sometimes we may change our mind about the desirability of a DRAW action once we see the result on the graph. Such unfortunate implementations can be undone with the UNDRAW command. For example, we might decide that our (a) would look better if it were larger, thicker and in roman font; this change can be executed if the above line is followed immediately by:
>> UNDRAW
>> DRAW / TEXT 1.3 85.0 "(a)" _ 2.5 _ $ROMAN 3
If the UNDRAW command is followed by a negative integer - N, then it is the previous Nth DRAW that is undone. In other words, UNDRAW -1 is the default; whereas UNDRAW -3 undoes the command two before the last one.
When several plots have been generated, we can return to a previous one by using REDRAW :
>> REDRAW -1
will put up the previous graph. Further information can be obtained by typing REDRAW / HELP .
Cursor Interaction
If an interactive device, such as "XW", is open, then an active "dialogue" with the graph can be conducted by using the GET_CURSOR command. That is to say, the instruction
>> K = GET_CURSOR( )
will prompt you for cursor-click with the mouse. The world and device coordinates of the selected point can be accessed through K.W_X , K.W_Y , K.D_X and K.D_Y ; the former are given with reference to the currently active window. The nature of the button pressed can also be ascertained through the parameter K.CHAR : if GET_CURSOR returns an "A", then the left-hand button was used; a "D" means that the middle button was pressed, whereas an "X" tells us that it was the right-hand one. A complete list of all 5 parameters can be printed on the screen by typing:
>> PRINTN K
The GET_CURSOR command opens up the possibility of developing fairly sophisticated procedures for interactive graphics. A very simple example would be the positioning of text for annotating plots; i.e. the GET_CURSOR command above could be followed by:
>> DRAW / TEXT
K.W_X
K.W_Y
"text"
Procedures
A whole series of graphics commands can be strung together and stored as a procedure. An example which reads in a 3-column ascii file test1.dat (from the current directory) and plots the same data as points (with error-bars), histograms and bins is given below:
PROCEDURE test1
LOCAL w iwidth
iwidth = 1
w = READ:ASCII:COLUMNS("test1.dat","x,y,e")
DEVICE / CLEAR
WINDOW / SCALED 0.15 0.9 0.15 0.9 0.1 10 0.1 100
DRAW / AXES _ iwidth 1.5 _
DRAW / MARKERS w.x w.y $CYAN 17 2.0 3
DRAW / ERRORS / VERTICAL w.x w.y w.e $CYAN iwidth
DRAW / HISTOGRAM w.x w.y $RED 1 $FULL iwidth
DRAW / PLOT w.x w.y $GREEN 4 iwidth
DRAW / LABELS "X" "Y" _ 2.0 $ ITALIC iwidth
DRAW / TITLE "Y = X\\u2\\d" _ 2.0 $ITALIC
ENDPROCEDURE
If this procedure is stored in the (ascii) file /usr/dsusers/dss/test1.gcl , it must be loaded into GENIE (once in the current session) before it is executed:
>> LOAD "/usr/dsusers/dss/test1.gcl"
>> test1
A slightly more general procedure, which facilitates the placement of text on a graph for annotation purposes, is shown below:
PROCEDURE ANNOTATE
LOCAL text colour size angle iwidth coord
text = INQUIRE("ANNOTATE > Text ? ")
angle = INQUIRE("Orientation > Angle ? (def=0 deg) ")
IF angle = " "; angle = 0.0 ; ENDIF
size = INQUIRE("Annotate > Character-size ? (def=1.5) ")
IF size = " "; size = 1.5 ; ENDIF
iwidth = INQUIRE("Annotate > Line-width ? (def=1) ")
IF iwidth = " " ; iwidth = 1 ; ENDIF
colour = INQUIRE("Annotate > Colour ? (def=1) ")
IF colour = " " ; colour = 1 ; ENDIF
coord = GET_CURSOR( )
DRAW/TEXT coord.w_x coord.w_y text colour &
size angle $NORMAL iwidth
ENDPROCEDURE
Once this ANNOTATE procedure has been loaded into GENIE, it can be invoked as many times as desired.
Hardcopy
If the open DEVICE is of the interactive variety, such as "XW", then a hard copy of the plot can be obtained with the following command:
>> HARDCOPY "filename" "device-type"
The default name for the output file is "GENIE.PS", and it is of the postscript flavour. For colour postscript you should choose "CPS", and so on. Online help on the syntax and options can be obtained by typing:
>> HARDCOPY / HELP