next up previous contents index
Next: 4 Basic Plotting Up: Part I: General Concepts Previous: 2 The User Interface

3 General Graphics Concepts


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.

3.1 Graphical Devices


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:

  1. An initial device command has been set up to be    device /xwindow. This initial device was fixed when WIP was compiled.
  2. If a default device is provided in your .wipinit   file (see Appendix A on the use of this file), it is loaded in place of the hard coded device.
  3. If the ``-d device'' flag appears on the command line (see Appendix B for a further description of command line options), it will always override any other initial device selected.

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

device /ps

selects the landscape version of the PostScript driver as the new device.

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

device "/dev/tty"/tek

sets the current device to a Tektronix terminal and sends the output to the device named ``/dev/tty''. Usually there exists a default `file-name' or `device-name' (see Table 3.1). The part after the slash (required) identifies the plotter device type (`device-type'). This could be, for example, ``/tek'' for plotting on a Tektronix terminal, or ``/ps'' to generate a PostScript output file. If the device command argument is ``?'' (no preceding slash), then WIP generates a list of all currently recognized device types. The command ldev   will also generate the list of the currently recognized device types. Table 3.1 lists a few of the typically recognized devices and a short description about each.

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.

Either True or False; the default is False. If true, it allows the window manager to provide a way to destroy the window; even while being used.
Either True or False; the default is False. By default, the /xserve window remains mapped when WIP finishes. If this option is true, the window will become iconic until opened by another WIP session.
Any number; the default is 100. This sets the maximum number of colors to try to allocate on startup. Useful for stopping ``colormap flashing''.
Any number; the default is 16. Rejects colormaps with fewer than this number of color entries.
Any one of: default, monochrome, PseudoColor, DirectColor, StaticColor, TrueColor, GrayScale, or StaticGray. The default value is default (any visual will do). This resource indicates the visual that should be tried first.
Either True or False; the default is False. If true, this sets the default active cursor to cross hairs.
Either True or False; the default is True. If false, the server window will be hidden.
An icon geometry format: +X+Y that specifies where the server icon should appear.
An icon geometry format: +X+Y that specifies where the window icon should appear.
A window geometry format: WIDTHxHEIGHT+X+Y. The default is something like 867x670.

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

set print myprog %s | lpr

illustrates how a particular instance for the value of print  may be defined by using the command set . Chapter 8 provides more details about the use the set command. In this example, the string variable print has been defined to run the program myprog with the plot file as its only argument and then pipe the result to the standard printer. Note the use of the %s variable to insure that the file is passed to the program myprog rather than appended to the end of the command. If the %s was not used, the resulting command would have been the same as if the user typed:
set print myprog | 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:

set print ignore

This will cause the spool and hardcopy commands to perform all of the post-processing on the hardcopy file but to ignore the print statement. Setting the print variable to an empty string will have the same effect.

3.2 Help, Echo, and Show


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:

help ? --
Lists the names of all currently available

commands and the names of the currently defined macros.

help --
Lists each command along with a one line description of what the command is suppose to do and the necessary and/or optional arguments.
help cmd --
Provides a complete description of the command cmd. Appendix D provides the equivalent of this option for every available command.

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).

3.3 Coordinate Systems


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.

3.4 Attributes


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

3.5 Boxes


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

box 0 bcnstv    # Draw only a y-axis box.

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.

limits 0 10 0 100    # Set the World coordinates.
lstyle 1    # Set the line style to a solid line.
color 2    # Set the color index to red.
box bcst bcst    # Draw the sides and tick marks.
color 4    # Set the color index to blue.
box n nv    # Numerically label the tick marks.
color 14    # Set the color index to dark gray.
lstyle 2    # Set the line style to a dashed line.
box g g    # Draw grid lines at each tick mark.

As another example, the command
box bcnsthz bcnstvdyz

illustrates how to use the box command with astronomical coordinates (i.e. right ascension for the x axis and declination for the y axis). The first argument (bcnsthz) tells box to draw the bottom and top edge of the frame, draw minor and major tick marks, and numerically label the tick marks using time labeling and hour, minute, and second superscripts. The second argument (bcnstvdyz) is the same as the first except that it suppresses any day formatting, orients the label vertically, and requests time labeling with degree, minute, and second superscripts.

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.

3.6 Text


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.

id --
   displays identification information at the bottom of the current plot page.
label --
    writes a string at the current pen position.
mtext --
    writes a string relative to a side of the viewport.
putlabel --
    writes a string at the current pen position but justified by a requested amount. If this amount is negative, the cursor  is used to specify a new current pen position (see Section 3.8).
xlabel --
    writes a centered string below the bottom of the current box.
ylabel --
    writes a centered string left of the left edge of the current box.gif

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.

xlabel \ga (1950)    # Labels x axis as (1950).

label HC\d3\uN    # Makes the label HCN.
mtext t 2 .5 .5 Title    # Label at top center of the panel.

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.  

3.7 Data Files


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.

Dynamic Data Files


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.

3.8 Cursor Interaction


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.

A --
Display the present cursor position and, if an image is loaded, the image intensity at that position,
D --
Draw to the current cursor position.
M --
Move to the present cursor position.
P --
Draw a point of the current symbol type at the present cursor position.
S --
Toggle the ability to save the keystrokes that follow as commands.
X --
Exit the interactive cursor routine.
? --
Present the list of current keystroke commands (this is the same as the command help cursor).

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)).gif As an example, suppose a user were to type the command

putlabel -0.5 A string to center

The cursor would then become active and allow the user to move to any position on the screen. Now, suppose the user moved the cursor to the position (5, 8) and hit any key. In this case, the keystroke commands are ``turned off'' and the first key hit by the user terminates the cursor routine. The string entered would appear centered at the position (5, 8) just as if the user had typed the following two lines:
move 5 8

putlabel 0.5 A string to center.

In fact, if this command were typed interactively (or when reading an input file off the command line ), these latter two commands are exactly what would be saved in the user's command buffer .

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.

next up previous contents index
Next: 4 Basic Plotting Up: Part I: General Concepts Previous: 2 The User Interface