Docs: multiplot

Introduction

Multiplot (E1) is a general purpose plotting program that is used to plot simple graphical elements such as lines, rectangles, and text, as well as virtual image files created with the "save:" plotfilter. The commands and options available in multiplot provide a core set of graphics commands that are present in most of the ERPSS graphics programs, and this document should be used as a reference for these commands.

Getting Started

The basic syntax for multiplot is:

where the plotdevice parameter specifies which of the many plotting devices should be used, and the inputfile parameter specifies the name of a file that contains a set of plotting commands. The input file may be specified as "none" if no input file is to be used or as "-" if input should be acquired from the standard input (i.e., the keyboard or a pipe from another command). A set of options may then occur, and finally a set of plotting commands may be entered on the command line.

The Plotting Environment

In the ERPSS software system, the graphics programs do not directly control graphics devices. Rather, they send abstract commands to device-specific "filter" programs which convert the abstract commands into device-specific plotting actions. As a result, the images produced by a graphics program will look the same on any graphics device, insofar as the hardware allows (e.g., not all devices support color). All of the graphics devices have an aspect ratio of 4:3, which means that one dimension is 4/3 larger than the other. The filter programs allow either the long dimension or the short dimension to be the bottom edge: when the long dimension is the bottom, the device is said to be in "landscape" mode; when the short dimension is the bottom, the device is said to be in "portrait" mode. Positions along the horizontal dimension always range from 0 to 1 in the multiplot program, whether in landscape or portrait mode. Positions along the vertical dimension have the same physical scale as positions along the horizontal dimension, so the values range between 0 and .75 for landscape mode and between 0 and 1.33 for portrait mode.

The User Interface

Multiplot uses the standard ERPSS command interface, which is described in detail (i.e., in technobabble) in the ERPSS Command Interface Programming Guide. The present documentation will provide a simpler, english description.

In UNIX, a user typically issues a command by typing its name at the UNIX prompt, possibly followed by a list of mandatory and/or optional arguments (an argument is a text string such as '-k', 'data.1', or '40.87'). The arguments are separated by spaces or tabs, and any argument that contains spaces or tabs must be enclosed in quotes. The ERPSS command interface uses this same basic format (with some modifications and enhancements), and applies it to commands that are understood by specific programs.

The format of mandatory and optional arguments is more constrained for ERPSS commands than is required by UNIX, which results in greater consistency between programs. A command should be directly followed by a fixed number of mandatory arguments (if there are any), and the mandatory arguments may be followed by a variable number of optional arguments (if there are any). The format for mandatory arguments may differ between commands, but they will always consist of single strings and will usually occur in a fixed order. Optional arguments may occur in any order and typically have one of two forms. In one form, the option is simply named, and carries a value implicitly (e.g., the string "thin" may be specified for a thin line width). In the second form, a value is stated explicitly in the form "option=value" (e.g., the argument "color=4" would specify that the color parameter should have the value "4"). An option's name may be prepended with the '-' character in order to be consistent with the typical UNIX command conventions (e.g., the option "-x" is equivalent to the option "x").

An example of a multiplot command that uses the standard command format is the line command. It's syntax is: 


	line x1 y1 x2 y2 [options]
For this command, x1, y1, x2, and y2 represent the two points defining the endpoints of the line, and are mandatory arguments. There are several optional arguments, including: 

	verythin thin medium thick verythick megathick	(line width)
	solid dotted dashed dotdash			(line type)
	color=						(line color)
To draw a thick dotted line from (0,0) to (1,1) using color #3, the command would be: 

	line 0 0 1 1 color=3 thick dotted
Since optional parameters may occur in any order, the command could also be written: 

	line 0 0 1 1 dotted thick color=3
The initial invocation of an ERPSS program from the UNIX command line usually uses the same format as the commands that are given to the program after it has been invoked. For example, the default color used by multiplot can be changed from 1 to 4 by invoking the program with the "color=4" option: 

	multiplot mvc none color=4
It is possible to put multiple commands on a single line. In the common UNIX shells, this is achieved by interposing semicolons between commands. The ERPSS command interface is somewhat simpler: a new command may begin immediately after the last option for the previous command, with only a space or tab preceding the new command. This difference allows the differentiation of multiple UNIX commands and multiple program-specific commands. For example, the following set of commands may be given at the UNIX prompt: 

	multiplot mvc inputfile line 0 0 1 1 dotted ; ls -l
The multiplot and ls (1) commands will be interpreted as UNIX commands, because multiplot is the first argument on the command line and because ls is the first argument after a semicolon. The line command will be interpreted as a command for the multiplot program, because it follows the arguments of a multiplot command without an interposing semicolon.

Comments can be included by beginning an argument with the '#' character. Comments can begin at the beginning of a line, or at the beginning of any argument in the middle of a line, as the following examples show: 


	#This is a comment
	# This is also a comment
	# The following line has two commands and a comment
	line 0 0 1 1 dotted  line .5 0 .5 1 solid #Comment starts here
Most command-oriented ERPSS programs allow or require the user to specify a file that contains a list of commands. If the filename is '-', the standard input (usually the keyboard) is used. If the filename is 'none', no file is read. Most programs will also allow readfile or rf commands to be placed in a command file, which specify that commands should be read from the named file before the remaining commands in the current file are read. Again, '-' may be used to specify the standard input, thereby allowing some commands to be contained in files and some commands to be entered from the keyboard.

Multiplot Commands

Common Options

Many of the multiplot (E1) commands share a common set of options that control line style, line thickness, text size, etc. For all commands that utilize lines (e.g., line, text, rect), the following options are available (default values are shown in parentheses): 


	Thickness:  verythin thin medium thick verythick megathick    (thin)
	Style:      solid dotted dashed dotdash             (solid)
	Color:      color=value                             (1)
For example, to specify a dotted line, the user may simply place the word dotted at the end of a command. Likewise, to specify color #7, color=7 would be used. The range of colors will depend upon the plotting device that is used.

For commands that draw text, the following options are available in addition to the line options: 


	Font:       simplex duplex complex italic  (simplex)
	Size:       textsize=value  (3.0)
	Origin:     laborigin=value lo=value (LT)
The text size can be any positive number, and may be a fractional value (e.g., textsize=5.7). The label origin specifies the orientation of the text and where it will be plotted relative to the current position. The label origin value is specified by a string of from one to five ASCII characters. This encoding is a bit tricky, since there are 34 possibilties to be encoded, but is intended to be mnemonic, and works like this: Imagine that a rectangle encloses some text. The label origin specifies some point on, in, or outside of the rectangle and serves as the reference location for the positioning of the text. When one moves to a particular location on the drawing surface and then issues a text command, the reference point becomes the current location, and text is drawn relative to that point. The 9 basic locations for the reference point are depicted schematically thus:

Note that these 9 label origins are encoded with a combination of the letters L (left), M (middle), R (right), T (top), and B (bottom). This encoding allows the letters to occur in any order. As an example, to center some text immediately above a particular coordinate, one would specify the labelorigin attribute as laborigin=MB, since the reference point would be in the middle of the bottom of the rectangle.

Two other letters are combined with these 5 to complete the full set of label origins. They are: V, which causes the text to be plotted vertically, one character on top of another, and E, which adds an additional half-character-width of extra space around the text in the imaginary rectangle (for example, LME would place the reference point one half of a character space to the left of the beginning of the text).

Default Values

One set of default values is stored for all line-oriented commands, except for text and grid commands, which have their own default values. The default values can be changed with the following commands: 


	linestyle [line_options]
	gridstyle [line_options]
	textstyle [line_options text_options]
When a line or text option is specified for any command other than these style commands, the optional values are only used for the current command, and multiplot then reverts to the default values. For example, the following set of commands would cause a thick dotted line to be drawn, followed by a thin dotted rectangle: 

	linestyle thin dotted
	line .2 .4 .8 .4 thick
	rect .5 .7 .9 .2

Drawing Lines and Shapes

The following commands draw basic line-oriented objects: 


	point x y [line_options]
	line x1 y1 x2 y2 [line_options]
	moveto x y
	lineto x y [line_options]
	arrow x1 y1 x2 y2 length angle [line_options]
	arc mid_x mid_y radius start_degrees stop_degrees [line_options]
	rect left top right bottom [line_options fill=\fIvalue\fB]
	startpgon
	endpgon
	drawpgon x y [line_options fill=\fIvalue\fB]
The mandatory x and y parameters should be positions on the plotting device, which typically range from 0 to 1.33 (as described above). When an arc is drawn, the mid_x and mid_y values represent the center of the circle on which the arc falls, and the radius parameter represents the radius of this circle in the same units as the x and y values. The start_degrees and stop_degrees parameters represent the starting and stopping points of the arc; 0 degrees is at the rightmost point of the circle, and degrees increase in the counter-clockwise direction.

The arrow command draws a line from x1,y1 to x2,y2 and then places an arrow head at x2,y2; the lines comprising the arrow heads are length screen units long and subtend angle degrees. When rectangles or polygons are drawn, they are simply outlined unless a fill pattern is specified with the fill= option. Fill patterns are integers, and a display of the available patterns can be created with the showpatterns (E8) program.

Arbitrary polygons can be drawn by first defining the polygon with a series of line commands and then drawing it with the drawpgon command. The startpgon command is used to begin defining a polygon, and the definition is terminated with the endpgon command. Between these commands, the intervening drawing commands will define the vertices of the polygon, but will not cause any actual drawing to occur on the plotting device. After the polygon has been defined, it can be outlined or filled at any time (until another polygon is defined -- only one can be defined at any given moment). A polygon should be defined with the point (0,0) at its center, because the x and y values required for the drawpgon command are used as an offset for the polygon, not as its absolute position. For example, the following set of commands will define a diamond and fill it using pattern 20 and color 4, centered at (.25,.60): 


	startpgon
	line +.00 +.20 -.20 +.00
	lineto +.00 -.20
	lineto +.20 +.00
	lineto +.00 +.20
	endpgon
	drawpgon .25 .60 fill=20 color=4

Drawing Text and Specifying Data Files

The format of the text command is:

The string specified by "string" is plotted at the location specified by x and y. The orientation of the string and its placement relative to the x,y position will depend on the current label origin setting, as described above. Several special characters (mostly greek alphabet and mathematical symbols) are available. These are accessed in the same manner employed by nroff (1). Appendix A lists the special characters that are available.

Translation, Rotation, and Scaling

Multiplot allows the user to specify translation (movement of an image to a different origin), rotation (movement of an image around the origin), and scaling (shrinking or expanding an image). For example, if you have a set of commands that draw a series of lines and rectangles, and you decide that you want them all moved to a different part of the screen, you can specify a translation offset before the commands, and this offset will be added onto the coordinates for all subsequent commands. There are four parameters that are used to control the translation, rotation, and scaling, and these are controlled by the following options (default values are in parentheses): 


	Translation:   xoffset=xvalue yoffset=yvalue
               		 offset=xvalue,yvalue  (0,0)
	Rotation:      rotate=value  (0 degrees)
	Scaling:       xscale=xvalue yscale=yvalue
               		 scale=xvalue,yvalue  (1,1)
	Object Center: xcenter=xvalue ycenter=yvalue
               		 center=xvalue,yvalue  (Center of plot device)

The translation, rotation, and scaling of the images within the current file can be specified with the translate (or trans) command, using the options described above. For example, the following command will cause all subsequent images to be drawn at 50% scale, offset by .2 units in the x dimension, and rotated 45 degrees: 


	translate xoffset=.2 scale=.5,.5 rotate=45

The translation of an image is simple: the specified offset is simply added onto the coordinates of an image. Rotation and scaling are somewhat more complex. When an actual physical object is rotated, there is a center of rotation, and parts of the object nearer to the center move a shorter linear distance than parts near the edge. Likewise, when an object shrinks or expands, parts near the center move a smaller amount than parts near the edge. Because of these factors, it is usually necessary to tell multiplot where the center of the object is in addition to the amount of rotation and scaling. That is the purpose of the center=, xcenter=, and ycenter= options.

The translation offset is always added onto the current offset, so an offset of (.1,.5) specified by a translate command will produce an actual offset of (.4,.2) if a previous translate command specified an offset of (.3,-.3). The options for scaling, rotating, and centering are not additive, however, and the values specified in previous translate commands are ignored.

Reading Command and Image Files

Multiplot can plot data from two types of files: command files and virtual image files. A command file is simply a file with standard multiplot commands. A virtual image file contains an abstract specification of an image, and is created with the save (E5) plotfilter. Both of these file types can be plotted with the application of translation, rotation, and scaling, as described above.

Two commands are available for plotting the contents of a command file (they have different names, but are functionally identical): 


	readfile filename [trans/rot/scale/center_options]
	rf filename [trans/rot/scale/center_options]
To plot a virtual image file, the following command is used: 

	vfile filename [trans/rot/scale/center_options]

It is possible to nest files within files; in other words, one command file may contain a readfile command that opens a second command file, which may itself contain a readfile command that opens a third command file, etc. When files are nested in this manner, the current translation values from the first file are added to those specified in the second file, etc. However, rotation and scaling factors are not combined in this fashion; any rotation or scaling factors within a file completely override any rotation or scaling factors specified externally.

Specifying Color Palettes

On devices with flexible color mapping, such as X-windows plotfilters, it is possible to load a palette file that specifies the mapping between color numbers (as specified in color= options) and the actual plotted color. These palette files are created by the editpal (E8) program. A set of basic palette files can be found in /usr/erpss/lib/palettes, and among these is "def16.pal", which is the default palette. This default palette is loaded when multiplot starts up, and the palette can subsequently be changed with the palette command: 


	palette filename
Multiplot (E1) will search for the named file in the current directory first, and if the file is not found the search will continue in /usr/erpss/lib/palettes (this allows standard palettes to be accessed without specifying the whole pathname). If a palette file is specified for a plot device that is inappropriate for the palette (e.g., a monochrome X-window or a pen plotter), a warning message is printed and the palette command is ignored.

Newpage, Pause, and Nopause

The command newpage can be used to clear the screen on a video device or load a new page for a hard copy device. When a video device is used, it is usually appropriate for the program to pause before clearing the screen so that the user has an opportunity to see the contents of the screen before it is cleared. The pause command causes the program to wait for the user to type a return character before continuing to read commands.

When the nopause command is given, subsequent pause commands are ignored. This command can be used when a plot with multiple pages is sent to a printer or plotter to defeat the pausing between pages which is pointless on a hardcopy device. Note that this command can be specified on the UNIX command line so that a single format file can be used for plotting on the screen or on a hardcopy device.

Help and Quit Commands

Multiplot will quit reading the current file (or keyboard) if it encounters the end of file (which can be simulated with the ctrl-D key from the keyboard), or if it encounters the commands "quit", "q", or "exit". The commands "help" or "?" will cause a list of the available commands to be printed.

List of Options and Commands

The following is a list of all of the options and commands that are available in multiplot. Except for the commands flagged with asterisks, all of these commands are standard commands that are (or will be) available in all ERPSS graphics programs.

Acknowledgements

This version of multiplot was based on two programs written by Ron Ohst, ploterps (E1) and the original version of multiplot. Much of the code for the graphics and many of the ideas for the user interface were borrowed (i.e., stolen) from these programs. Jon Hansen also made several valuable suggestions about the design and implementation of the user interface.

Appendix A

Special Characters for the Text Command


	\\(de     degree                  \\(dg     dagger
	\\(**     math star               \\(sc     section
	\\(*a     alpha                   \\(*b     beta
	\\(*g     gamma                   \\(*d     delta
	\\(*e     epsilon                 \\(*z     zeta
	\\(*y     eta                     \\(*h     theta
	\\(*i     iota                    \\(*k     kappa
	\\(*l     lambda                  \\(*m     mu
	\\(*n     nu                      \\(*c     xi
	\\(*o     omicron                 \\(*p     pi
	\\(*r     rho                     \\(*s     sigma
	\\(*t     tau                     \\(*u     upsilon
	\\(*f     phi                     \\(*x     chi
	\\(*q     psi                     \\(*w     omega
	\\(*A     ALPHA                   \\(*B     BETA
	\\(*G     GAMMA                   \\(*D     DELTA
	\\(*E     EPSILON                 \\(*Z     ZETA
	\\(*Y     ETA                     \\(*H     THETA
	\\(*I     IOTA                    \\(*K     KAPPA
	\\(*L     LAMBDA                  \\(*M     MU
	\\(*N     NU                      \\(*C     XI
	\\(*O     OMICRON                 \\(*P     PI
	\\(*R     RHO                     \\(*S     SIGMA
	\\(*T     TAU                     \\(*U     UPSILON
	\\(*F     PHI                     \\(*X     CHI
	\\(*Q     PSI                     \\(*W     OMEGA
	\\(sr     square root             \\(>=     >=
	\\(<=     <=                      \\(->     right arrow
	\\(mu     multiply                \\(di     divide
	\\(+-     plus minus              \\(-+     minus plus
	\\(if     infinity                \\(pd     partial derivative
	\\(gr     gradient                \\(is     integral sign
	\\(es     empty set               \\(mo     member of
	\\(li     line integral sign      \\(cp     continued product sign
	\\(dp     dot product             \\(cs     continued sum
	\\(t2     alternate theta         \\(<<     large open angular bracket
	\\(>>     large close angular bracket
MULTIPLOT
Tutorial Introduction and Reference Manual
Steve Luck


© 2005 UCSD ERP Lab
Please send comments and suggestions to the ERPSS Webmaster