.ds :? P\s-1WB\s+1/Graphics Overview .PH "''''" .OH "'\s9\f2\*(:?\fP''\\\\nP\s0'" .EH "'\s9\\\\nP''\f2\*(:?\^\fP\s0'" .na .bd S B 3 .EQ delim $$ .EN .TL 49582-063 39382-900 PWB/Graphics Overview .AU "A. R. Feuer" ARF PY 3782 7016 2F-202 .TM 79-3782-1 .MT 4 .sp .sp 3 .H 1 INTRODUCTION PWB/Graphics, or just .I graphics, is the name given to a growing collection of numerical and graphical commands available as part of the Programmer's Workbench [1]. In its initial release, .I graphics includes commands to construct and edit numerical data plots and hierarchy charts. This memorandum will help you get started using .I graphics and show you where to find more information. The examples below assume that you are familiar with the \s-1UNIX\s+1\*(Tm Shell [1]. .H 1 "BASIC CONCEPTS" The basic approach taken in .I graphics is to generate a drawing by describing it rather than by drafting it. Any drawing is seen as having two fundamental attributes: its underlying logic and its visual layout. The layout encompasses one representation of the logic. For example, consider the attributes of a drawing that consists of a plot of the function $y = x sup 2$ for $x$ between 0 and 10. The logic of the plot is the description as just given, viz. $y = x sup 2 , 0 <= x <= 10$. The layout consists of an x-y grid, axes labeled perhaps 0 to 10 and 0 to 100, and lines drawn connecting the x-y pairs 0,0 to 1,1 to 2,4 and so on. .P The way to generate a picture in .I graphics is .DS 1 1 gather data | transform the data | generate a layout | display the layout. .DE To generate the specific plot of $y = x sup 2 , 0 <= x <= 10$ and display it on a Tektronix\(rg display terminal would be: .DS 1 1 .tr ~" .B "gas \-s0,t10 | af ~x^2~ | plot | td" .DE .VL 1i .5i .LI \fBgas\fR generates sequences of numbers, in this case \fBs\fRtarting at 0 and \fBt\fRerminating at 10. .LI \fBaf\fR performs general arithmetic transformations. .LI \fBplot\fR builds x-y plots. .LI \fBtd\fR displays drawings on Tektronix terminals. .LE 1 The resulting drawing is shown in Figure 1. .P The layout generated by a \fIgraphics\fR program may not always be precisely what is wanted. There are two ways to influence the layout. Each drawing program accepts options to direct certain layout features. For instance, in the previous example we may have wanted the x-axis labels to indicate each of the numbers plotted and we might not have wanted any y-axis labels at all. To achieve this the \fIplot\fR command would be changed to: .DS 1 1 .B "plot \-xi1,ya" .DE producing the drawing of Figure 2. .P The output from any drawing command can also be affected by editing it directly at a display terminal using the graphical editor, \fIged\fR. To edit a drawing really means to edit the computer representation of the drawing. In the case of .I graphics the representation is called a graphical primitive string, or \s-1GPS\s+1. All of the drawing commands (e.g., \fIplot\fR\|) write \s-1GPS\s+1 and all of the device filters (e.g., \fItd\fR\^) read \s-1GPS\s+1. \fIGed\fR allows you to manipulate \s-1GPS\s+1 at a display terminal by interacting with the drawing the \s-1GPS\s+1 describes. .SK 1 .P \s-1GPS\s+1 describes graphical objects drawn within a Cartesian plane 65,534 units on each axis. The plane, known as the \fIuniverse\fR, is partitioned into 25 equal sized square regions. Multi-drawing displays can be produced by placing drawings into adjacent regions and then displaying each region. .H 1 "GETTING STARTED" To access the .I graphics commands when logged in on a \s-1PWB/UNIX\s+1 system type .B graphics. Your \fIShell\fR variable \fB\s-1PATH\s+1\fR will be altered to include the .I graphics commands and the \fIShell\fR primary prompt will be changed to \fB^\fR. Any command accessible before typing .B graphics will still be accessible; .I graphics only adds commands, it doesn't take any away. Once in .I graphics, you can find out about any of the .I graphics commands using \fIwhatis\fR. Typing \fBwhatis\fR by itself on a command line will generate a list of all the commands in .I graphics along with instructions on how to find out more about any of them. .P All of the \fIgraphics\fR commands accept the same command line format: .VL 2.1i .5i .LI "A command is:" a \fIcommand-name\fR followed by \fIargument\fR(s). .LI "A \fIcommand-name\fR is:" the name of any of the \fIgraphics\fR commands. .LI "An \fIargument\fR is:" a \fIfile-name\fR or an \fIoption-string\fR. .LI "A \fIfile-name\fR is: any file name not beginning with \fB\-\fR, or a \fB\-\fR by itself to reference the standard input. .LI "An \fIoption-string\fR is:" a \fB\-\fR followed by \fIoption\fR(s). .LI "An\ \fIoption\fR\ is:" letter(s) followed by an optional value. Options may be separated by commas. .LE .P You will get the best results with .I graphics commands if you use a display terminal. \fIPlot\fR\|(1) filters can be used in conjunction with \fIgtop\fR (see \fIgutil\fR(1)) to get somewhat degraded drawings on Versatec printers and Dasi-type terminals. And since \s-1GPS\s+1 can be stored in a file, it can be created from any terminal for later displaying on a graphical device. .P To remove the .I graphics commands from your .B \s-1PATH\s+1 .I Shell variable type \fB\s-1EOT\s+1\fR (control-d on most terminals). To logoff \s-1UNIX\s+1 from .I graphics type \fBquit\fR. .sp .H 1 "EXAMPLES OF WHAT YOU CAN DO" .H 2 "Numerical Manipulation and Plotting" \fIStat\fR\|(1) describes a collection of numerical commands. All of these commands operate on vectors. A vector is a text file that contains numbers separated by delimiters, where a delimiter is anything that is not a number. For example, .DS 1 1 2 3 4 5, and arf tty47 Mar 5 09:52 .DE are both vectors. (The latter being the vector: 47 5 9 52.) .sp 2 Here is an easy way to generate a Celsius-Fahrenheit conversion table using \fIgas\fR to generate the vector of Celsius values: .DS 1 1 .B "gas \-s0,t100,i10 | af ~C,9/5*C+32~" .DE .SK The output is: .DS 1 0.0 32 10 50 20 68 30 86 40 104 50 122 60 140 70 158 80 176 90 194 100 212 .DE This is what is going on: .VL 2i .5i .LI "\fBgas \-s0,t100,i10\fR" We have seen \fIgas\fR in an earlier example. In this case the sequence \fBs\fRtarts at 0, \fBt\fRerminates at 100, and the \fBi\fRncrement between successive elements is 10. .LI "\fBaf ~C,9/5*C+32~\fR" We have also seen \fIaf\fR. Arguments to \fIaf\fR are expressions. Operands in an expression are either constants or filenames. If a filename is given that does not exist in the current directory it is taken as the name for the standard input. In this example \fBC\fR references the standard input. The output is a vector with odd elements coming from the standard input and even elements being a function of the preceding odd element. .LE .sp 2 Here is an example that illustrates the use of vector titles and multiline plots: .DS 1 .B "gas | title \-v~first ten integers~ >N" .B "root N >RN" .B "root \-r3 N >R3N" .B "root \-r1.5 N >R1.5N" .B "plot \-FN,g N R1.5N RN R3N | td" .DE The resulting plot is shown in Figure 3. .P .VL 2i .5i .LI "\fBtitle \-v~\fIname\fR~ " \fITitle\fR associates a \fIname\fR with a vector. In this case, \fBfirst ten integers\fR is associated with the vector output by \fIgas\fR. The vector is stored in file \fBN\fR. .LI "\fBroot \-r\fIn\fP" \fIRoot\fR outputs the \fIn\fR\|th root of each element on the input. If \fB\-r\fIn\fR is not given then the square root is output. Also, if the input is a titled vector the title will be transformed to reflect the root function. .LI "\fBplot \-F\fIX\fB,g \fIY(s)\fR" This command generates a multiline plot with \fIY(s)\fR plotted versus \fIX\fR. The \fBg\fR option causes tick marks to appear instead of grid lines. .LE .sp 2 The next example generates a histogram of random numbers. .DS 1 .B "rand \-n100 | title \-v~100 random numbers~ | qsort | bucket | hist | td" .DE The output is shown in Figure 4. .SK 1 .P .VL 2i .5i .LI "\fBrand \-n100\fR" \fIRand\fR outputs random numbers using \fIrand\fR(3C). In this case 100 numbers are output in the range 0 to 1. .LI "\fBqsort\fR" \fIQsort\fR sorts the elements of a vector in ascending order. .LI "\fBbucket\fR" \fIBucket\fR breaks the range of a vector into intervals and counts how many elements from the vector fall into each interval. The output is a vector with odd elements being the interval boundaries and even elements being the counts. .LI "\fBhist\fR" \fIHist\fR builds a histogram based on interval boundaries and counts. .LE 1 .H 2 "Drawings Built from Boxes" There is a large class of drawings composed from boxes and text. Examples are structure charts, configuration drawings, and flow diagrams. In \fIgraphics\fR the general procedure to construct such box drawings is the same as that for numerical plotting. Namely gather and transform the data, build and display the layout. .P As an example, consider hierarchy charts. The command line .DS 1 1 .B "dtoc | vtoc | td" .DE outputs the drawing shown in Figure 5. .P \fIDtoc\fR outputs a table of contents that describes a directory structure (Figure 5a). The fields from left to right are level number, directory name, and the number of ordinary readable files contained in the directory. \fIVtoc\fR reads a (textual) table of contents and outputs a visual table of contents, or hierarchy chart. Input to \fIvtoc\fR consists of a sequence of entries, each describing a box to be drawn. An entry consists of a level number, an optional style field, a text string to be placed in the box, and a mark field to appear above the top right hand corner of the box. .H 1 "WHERE TO GO FROM HERE" The best way to learn about .I graphics is to log onto a \s-1PWB/UNIX\s+1 system and use it. Tutorials exist for \fIstat\fR(1) and \fIged\fR(1). [2] contains administrative information for \fIgraphics\fR. Reference information can be found in the \s-1PWB/UNIX\s+1 User's Manual under the following manual pages: .DS 1 \fIged\fR(1), the graphical editor; \fIgps\fR(5), a description of a graphical primitive string; \fIgraphics\fR(1), the entry point for \fIgraphics\fR; \fIgutil\fR(1), a collection of utility commands; \fIstat\fR(1), numerical manipulation and plotting commands; \fItek4000\fR(1), a collection of commands to manipulate Tektronix 4000 series terminals; and \fItoc\fR(1), routines to build tables of contents. .DE .H 1 "REFERENCES" .RL .LI .I "PWB/UNIX User's Manual" \*-Release 2.0., Bell Laboratories, 1979. .LI R. L. Chen and D. E. Pinkston, .I "Administrative Information for PWB/Graphics," Bell Laboratories Memorandum, 1979. .LE .sp .I "January 1980" .SK