This chapter describes the general graphical concepts of WIP. Many of WIP's commands are used to set the device type, the device's environment, location and limits of the border, and annotate the plot with labels. Most of these commands are called only one time; others several times. These concepts and some of the commands needed to put them to use are described in the sections that follow.
Plotting devices in WIP provide the destination for the plot. In this sense, any graphics device, whether a computer terminal, a high resolution laser printer, or even a file may be considered a WIP device. An initial device is selected when WIP first begins but new devices may be selected at any time during the interactive session.
There are several ways that the initial device may be chosen when starting WIP. The following list indicates the different ways an initial WIP device is selected:
.wipinit file
(see Appendix A on the use of this file),
it is loaded in place of the hard coded device.
A new device may be selected at any time in WIP. To specify a new device interactively, use the command device with the new device name as its argument. For example, the command
Devices have a standard PGPLOT format of ``file-name/device-type'' or ``device-name/device-type''. If the `file-name' or `device-name' contains a slash (/), it should be enclosed in double quotation marks. For example, the command
Table 3.1: A Sample of Available Plotting Devices
NOTE: The /retro and /tek4010 devices may have some problems with the cursor when used interactively (especially over a network) -- this is currently being investigated.
NOTE: The /xwindow and /xserve devices behave differently than other devices. These plotting devices start a server independently of WIP which is used to communicate with each plotting window. The server will stay present on the display long after a WIP session is complete. The difference between the /xwindow and /xserve drivers is that the /xserve remains on the screen after a WIP session. There may be multiple /xserve windows on a single display, each having a unique id number associated with it. The id number is used to identify the proper window to WIP. As with many X-window applications, the server associated with these two devices has several application defaults which may be set up in your X-resource file. These resources, acceptable values, and default values are shown in listing that follows. To target options at specific windows, replace the Win component of the specification with win#, where # is the id number of the window.
Files created for hardcopy devices must be spooled to the printer. Two commands and one string variable exist to simplify this for the user. The commands that spool a plot to a hardcopy device are hardcopy and phard . The string variable print is used to control how the plot file will be spooled to the printer.
The command hardcopy is used when the current device is a hardcopy (i.e. non-interactive) device and you are finished generating output to that device. This command closes the output file and releases it to be printed by WIP. Alternatively, the command phard may be used when the current device is an interactive device and the user desires to playback the list of current commands to a hardcopy device and then resume plotting on the initial interactive device. Both commands use the string variable print to describe how to spool the resulting plot file.
Since the method needed to spool the file to the selected printer
is site and device specific, a flexible method was needed to allow users
to spool their plots.
Generally, the command to send a plot to a printer is quite simple and
may be specified by a single statement.
The string variable print
contains the command needed for the system to plot the file `file-name'
and overrides the initial default value set when WIP was compiled.
For example, the default value for
print
on a Unix system is ``lpr %s'' where the ``%s''
represents a variable that is used
as a placeholder for the value of the plot file name.
The value for print may be customized for every instance of WIP if
it is defined in your .wipinit file
(see Appendix A on how to set up this command in this file).
Alternatively, the command
| lpr
| lpr %s
Sometimes, it is useful to do everything except spool the file to a printer. This might happen when generating color PostScript files and it is desired to screen preview the file before shipping them off to the printer. To override the printing command, set the print string to ``ignore'' as in the example:
Help is available on-line in WIP.
The location and name of the on-line help file is set when WIP is compiled.
Generally, this should never need to change.
However, there are two ways the location or name of this file can
be reassigned without having to recompile WIP.
The first is to set the environment variable
``WIPHELP'' .
The other way is for the user to do this via their .wipinit file
(see Appendix A for details).
In addition to this manual, there are three modes of help that are available within the interactive mode of WIP. The command help has an optional argument that, depending on its use and whether or not it is present, provides three different styles of help. They are:
commands and the names of the currently defined macros.
In addition to the on-line help, WIP also provides a way to see the current value of many of the attributes , coordinate system positions , user variables , and image characteristics . This may be done with either the command echo or the command show . The command echo enables the user to display, at the command line, the current value of almost any item available to WIP. The echo command will also evaluate expressions and print literal text. Multiple items may also be presented using only one echo command. Throughout the rest of this manual, several examples of the command echo will be presented. The command show displays not only many of the items listed above, but also the user variable ``name'' (shown in upper case) that is associated with their values (see the topics described in the Chapters of Part ii for a more detailed description on how to make use of these names).
There are two distinct coordinate systems in WIP. They are the Device and the World coordinates. The device, or viewport, coordinates represent positions on the device and are always in units that range between (0 -- 1). The world coordinates represent what the user usually associates as the limits or range of the plot. For example, a plot of height versus weight might have the abscissa (x-coordinate) represent weight and the ordinate (y-coordinate) height. The actual values of weight and height represent the world coordinates. Where these values map onto the device represent the device coordinates.
This rectangular region of the world coordinate space (termed the window ) is mapped onto a specified rectangle (termed the viewport ) on the view surface (the screen of an interactive display or a sheet of paper on a hardcopy plotter). The following list of commands affect either the world coordinate system or the position and size of the viewport.
There are several graphic characteristics of WIP that may be set by either the program or by the user. These have the special behavior that they will remain in effect until either the end of the plot or until they are changed again by the user. These characteristics include the color index, text font, line style and width, fill type, and character size expansion to name a few. Table 3.2 contains a list of the attributes, their default values, and the commands used in WIP to modify them. The values of the attributes listed in Table 3.2 remain intact until changed by another call to the controlling command with one exception: attributes identified with a `Yes' in the Reset column are reset to their default value every time a new device is selected or the user issues the reset command. The examples in Appendix E illustrate how to use several of these graphical attributes and Figure E.7 displays the first 32 graphical markers used by the command symbol .
Table 3.2: Graphical Attributes
Table 3.3 presents the predefined colors representations along with the corresponding Red-Green-Blue (RGB) and Hue-Lightness-Saturation (HLS) intensities. All but one of the color intensities have values that are in the inclusive range of 0.0 -- 1.0, with 1.0 being the maximum intensity. The exception is Hue which is a cyclic quantity expressed as an angle in degrees and has the inclusive range of 0 -- 360. If the three RGB intensities are the same, the color is a shade of gray.
Table 3.3: Default Color Representations
Fundamental to the display of graphics in WIP is an item called a box. Boxes are constructs that border a plot and may identify the scale along a particular axis. There are several possible arrangements of the arguments to the command box that will lead to very different borders. Many of the attributes listed in section 3.4 also affect the resulting appearance of the box.
Prior to calling the box command, the world coordinates, or limits, should be set. Refer to section 3.3 for a collection of commands which allow the user to specify the world coordinates of the plot.
Two other characteristics of the border may be specified prior to a call to box: the major tick mark interval and the number of minor tick marks per major tick. Use the command ticksize to input the major interval and number of minor ticks for each axis. If the major tick mark interval is specified as 0 (the default), then box will calculate its own interval. Likewise, if the number of minor tick marks per major tick mark is set to 0 (the default), then box will attempt to calculate a ``nice'' interval. Setting the number of minor tick marks to 1 will inhibit any minor tick marks (except for logarithm) regardless of the arguments to the command box. The units of the arguments to ticksize are the same used to specify the limits of the world coordinates.
There are two arguments to the command box which determine how WIP will display the border. Each argument consists of one or more letters (case independent; no intervening spaces) which tell WIP how to construct the box. The current letters (and their meanings) used to construct an argument to box are shown in Table 3.4.
Table 3.4: Box Option Characters
Unrecognized letters are quietly ignored as are any multiple occurrences of letters. To call box with arguments for only one axis, use the null argument (0); this will suppress any drawing along the unused axis. For example, to produce a standard box but only along the y-axis, use
By calling box with one group of arguments, then changing one or more attributes, and then calling box again with different arguments, one can produce a box with considerable variation. The following list of commands provides such an example.
Two string variables associated with the x and y axis arguments of box are xbox and ybox , respectively. If the box command is called without any arguments, these strings are substituted in their place. Appendix A shows how to have these strings loaded as the defaults every time WIP is run.
WIP provides many commands which will display a string of characters. Strings may be altered dramatically by judicious use of many of the graphical attributes shown in Table 3.2. The commands that are used to write labels or titles on the plot are shown in the list below along with a brief description. Use help cmd (where cmd is one of the following commands) or see Appendix D for a more detailed description of each of the following commands.
All of the text commands above (except id) require a label as an argument. This label may be modified by any of the escape sequences shown in Table 3.5.
Table 3.5: Label Escape Sequences
About half of the escape sequences listed in Table 3.5 remain in effect until the end of the string or until another escape sequence terminates its scope. The following list of commands illustrates the use of a few of the text commands along with several escape sequences.
(1950).
N.
By far, the most flexible text command is mtext. The first four arguments to mtext specify where the label will appear on the viewport; the remaining arguments represent the label to display. The first argument is a character describing along which viewport side the label will appear. The character must be either `b', `l', `t', or `r' to specify, respectively, the bottom, left, top, or right viewport side. In addition, an optional character `v' may be appended (as in `lv' or `rv') to the left or right character to specify that the label be presented perpendicular to the viewport side. The second argument to mtext is a displacement (in character height units) away from the viewport edge. Positive values position the label ``away'' from the edge; negative values move the label ``inside'' the viewport. The next two arguments (arguments three and four to mtext) specify the justification of the label. The first of these two arguments specifies a position along the viewport. This position is a value relative to the total extent of the viewport edge (i.e. running from 0 to 1 left to right and bottom to top). The second of these two arguments specifies how to justify the label relative to this position with a value of 0 indicating left justified; 0.5 centered; and 1 right justified.
Data files are simple ASCII text files that can be read to generate point and line graphics (i.e. 1-dimensional plots). The command data opens a file and prepares it for reading. The data is assumed to be column ordered with any two columns separated by a comma or blank space (or both). Currently, there is no restriction on the contents of the data in each column except that lines beginning with the comment character (#) are ignored. Non-existent and empty data files are warned about and then ignored.
Data is usually read in by column format into WIP with the commands xcolumn and ycolumn . The required argument to these commands is the column number from which to read the data (i.e. each line read is parsed into words and the command evaluates only the selected word). Incorrect data lines are usually printed out with a warning message.
Which lines are actually read from the data file may be restricted by the user. The command lines limits the range that the input data file is read from line L1 to L2, where L1 and L2 are the two required arguments given with the command. If the data file has fewer than L2 lines, reading is stopped at the end of the file.
In addition to the X and Y arrays discussed above, there are presently two other predefined arrays: the ERR and PSTYLE arrays. The ERR array is used to store error bar distances from the corresponding X and Y positions (see the command errorbar in Section 4.2) and the PSTYLE array is used to hold a symbol number for each X and Y position (see the command points in Section 4.2). The ERR and PSTYLE arrays are used by other commands for other purposes too; these usage variations will be identified when the specific commands are discussed later.
Another use of the data files is to assign strings to string variables . String variables are a type of User Variable and will be introduced in Chapter 8. The command string can be used to assign a word or a string to a string variable. The only line read in the data file is defined by the value of L1 (see above) and which (space separated) words are assigned to the string variable is determined by the arguments to the command. Use help string or see Appendix D for a detailed description of the arguments to this command.
There is a straightforward way to input data directly on the command line within WIP. If the argument to the data command is stdin, then the current mode is switched to a data input mode. WIP will stay in that mode until the string enddata appears on a line by itself. While in data input mode, every line is treated as input to this dynamic data set. When the input mode is terminated, the data may be read using any of the techniques described above. The data set created will remain active until either another data set is opened (with the data command) or the user exits from WIP.
The command cursor permits a simple means of interacting with the plot. Several keys have been assigned to the cursor command which allow complicated plotting commands to be easily constructed. Each command typed while interactively using the cursor can be saved in the command buffer (see Chapter 7 for a general description of macros and the command buffer) and may be edited (using the techniques described in section 7.4) or re-executed (with the command playback ). The keystroke commands that are currently recognized are shown in the list below and are not case sensitive.
There are a few commands in WIP which use the cursor to specify the
location where the command is to act.
Most significant is the command
putlabel,
which takes two arguments:
a justification value and a string to write.
The justification value ranges from 0 -- 1 where 0 means left
justification relative to the current cursor position, 1 means right
justification, and 0.5 means center the text on the cursor position.
However, WIP allows negative justifications.
Negative justifications signal WIP to
activate the cursor prior to displaying the text so that the user may
specify a new current cursor position.
The minus sign is just a flag to WIP, the justification that will
eventually reach the text displaying routine will still range
between 0 -- 1 (i.e. abs(justification)).
As an example, suppose a user were to type the command
There are a few instances, however, when the cursor command
will not function interactively (as shown in the previous example).
In these cases,
the cursor will only be used to return the cursor position selected;
the keystroke commands will be ignored.
These instances are when either of the
commands cursor
or
putlabel
are (i) executed from inside a macro ;
(ii) entered into the command buffer with the
command insert
;
or (iii) executed using the
command input .
For these special cases,
the cursor will only return the current cursor position
and ignore any subsequent keystrokes.