pen - VPLOT graphics output filters for all devices
pen plot_file1 [plot_file2 ...] [options]
Pen < Plot1.h [Plot2.h ...] [options]
Pen filters accept input in the vplot graphical metalanguage and translate it into code for any of about 20 graphics output devices including graphics terminals, laser printers, electrostatic plotters, and dot-matrix line printers. Interactive input (mouse, cursor keys, keyboard) is not yet supported.
The output of a pen filter can be sent to a plot device or saved as a file of device-language commands. If the output is not redirected it is understood that you want to plot on the standard output device.
There are now many different pen filters for different devices. These programs differ only in the device-dependent output routines. They share a common vplot interpreter, and most filters make use of common intermediate-level code. This manual entry describes those options that are implemented in the device independent part and thus are common to all pen filters.
Pen has many options. Though many of these are included mostly for backward compatibility with older versions of vplot, they also add quite a lot of flexibility to the system.
Those options for which the default is device- or host-dependent are marked with an `X', since the default varies from machine to machine or device to device.
All options have the form a=b, where `a' is the name of the option being set and `b' is the value it is being set to. Alternatively, commonly used sets of options may be listed in a parameter file and par=parameter_file_name can be put as an option on the command line. The last occurrence of any given option on the command line is the one that is used (see also man getpar.) The form a= has the effect of causing the option `a' to be unset.
String is an input file containing vplot-format plot commands.
The `in=' is optional; any text on the command line which
doesn't contain an `=' is assumed to be an input file.
The standard input is also read. It is valid to have inputs
in all three of these forms at the same time;
they will be read in order.
This is not quite the same as concatenating the files and then
processing the result, as the clipping window, fatness,
current color number, text justification mode, text font,
text precision, text overlay mode, and plot style get
reset to the default at the start of each new input file
(and at the start of each frame within a file).
(Non-sep filter versions only: numvplot=0 controls how many
extra input file specifications of the form inX=stringX,
where X runs from 1 to numvplot, will be searched for.)
Some pen filters may support several related, but not
identical, devices. This variable allows you to tell
the pen filter the exact device type that you are using.
The work station type variable can also be set via the
environment variable WSTYPE. The command line takes
precedence. Normally the presence of any options
on the command line inhibits self-documentation. The
wstype option, if alone on the command line, will not.
This is an amount to translate the plot, in inches, in the
horizontal and vertical directions, respectively.
This is independent of all other scaling and origin setting.
These are useful when including graphics into a paper via TeX.
The program vppen (a special sort of pen filter) can be used
to calculate an appropriate hshift and vshift.
If specified, the coordinate given (in inches)
is forced to be in the middle of your screen.
In combination with the interact option, this allows you
to zoom in on an interesting part of your plot
without having it zoom off the screen. This is independent
of everything except translation (hshift and vshift).
Number of seconds to wait in between plots. -1 means to
prompt and stop and wait for a carriage return before
continuing.
Base line thickness. Add this fatness to all vectors drawn.
Fatnesses are measured in units of 1/200'th of an
inch. A fatness of 1 or 2 may very well have no effect on a
low resolution device, but it will on a high resolution one.
scales as does fatmult.
Fatness multiplication factor. This is mainly useful when
you want to turn off fatness for speed of plotting. This
option can also be set via the environment variable FATMULT.
Pattern multplication factor. This multiplies the size of
patterns inside polygons, both bit patterns and hatch patterns.
Like FATMULT, can be set via an environmental variable
PATTERNMULT. If you set ``patternmult=0'' then polygons
will only be filled solidly or not at all.
Amounts by which to stretch the plot.
stretches both axes equally,
xscale (X only) and (yscale) Y only
Again, this is vplot's X and Y, not
necessarily the screen's if the plot has been rotated.
Fatnesses, patterns, dashed line pattern lengths,
and marker sizes do NOT scale geometrically along
with the rest of the plot. Patterns and dashed line
lengths do not scale at all except by their own special
scaling options given below.
Markers, text fatnesses, and vector fatnesses scale with
screen size and with the scale option, but not with xscale
and yscale.
Special scaling options that control specific things are
txscale, which scales only text size;
mkscale, which scales only markers;
dashscale, which scales only dashed line patterns;
fatmult, which scales all fatnesses; and
patternmult, which scales only patterns.
Note text will not stretch differentially with
xscale and yscale unless the default option
txsquare=y is overridden.
These options can be used to control shading of polygons.
If shading is turned off, the interior is not filled.
(`A' style polygons normally do not have any outline. If
shade=n, one will be drawn so that you can still see where
the polygon is.) For devices that support polygons filled
with patterns, the overlay option sets the default
overlay mode: n = replace, y = overlay. This can be
reset during plotting by the overlay command in vplot.
The difference between these two options is whether color
zero is treated as transparent or not. This option also
applies to raster. Not all devices will support all overlay
options. On some devices that do support both overlay options
(in particular those that simulate raster in software)
overlay=y may be much faster than the default.
This option sets the default coordinate system.
(It is overridden if the coordinate system for the
frame is set by the VP_SETSTYLE command in
the vplot file.) The default is the origin in the
lower left corner, y vertical and x horizontal.
sets the origin in the upper left corner of
the plot with y horizontal and x positive downwards.
is the same as standard but with `size=absolute'
implied as well. Other possibilities are `old' and
`mazama', both obsolete standards. This option can
also be set using the environment variable PLOTSTYLE.
Default text font, text precision, and text overlay mode.
Alternate font file. If txsquare=y, then xscale and yscale
will not be allowed to distort text.
If txsquare=n, text will stretch consistently with everything
else. These are described in more detail in vplottext.
Window=n
turns off all clipping windows (except that of the edge of
the screen). This is useful if you have accidentally
clipped your plot away to nothing, and can't figure out
what's going wrong.
Frame=y
shows you where your windows are, by outlining them in white.
(The first window should always simply frame the screen, but
often one side or another is clipped by the device because the
device's coordinates are off by one.)
xwmin, xwmax, ywmin, ywmax
allow you to specify a global clipping window in addition
to any specified in the Vplot. The window's position is
given in vplot units of inches. (The 4 corners of the
window specified will be translated into device coordinates,
and the smallest rectangle with sides perpendicular to the
edge of the screen containing these 4 points will be used
as a global clipping window.)
Together with concatenation of vplot files and hshift and
vshift, this gives a primitive sort of cut and paste
capability.
rotate=0
Global rotation of entire plot by this many degrees
clockwise, about the origin. Vshifts and/or hshifts
may be needed to keep the plot from rotating off the
screen. Since clipping windows must be standard up-down
left-right rectangles, they cannot rotate correctly
except to multiples of 90 degrees. The smallest clipping
window that is possible that contains the desired
clipping window will be used in this case.
Erase=y
forces an erase at the start of each input file, and
follows the vplot literally thereafter.
Erase=literal
does not force an erase at the start.
Erase=n
ignores ALL erases.
Erase=once
forces one erase at the start of plotting and thereafter
ignores all erases. These options are especially useful
when combining several vplot files.
``Forcing an erase at the start'' creates an erase as the
very first thing in the input plot file, but only if the
plot file didn't already start with one.
Break=b
treats the Vplot `break' command as a chance to pause,
but not to erase.
Break=e
makes `break' and `erase' synonymous.
Break=i
ignores break commands completely.
size=relative
scales the plot workspace, a 10.24 inch high by 13.65
inch wide rectangle, to fit the size of the screen.
size=absolute
scales to real inches. Hardcopy devices with large or
semi-infinite plotting surfaces should default to
size=absolute, while screen devices and ``page-oriented''
hardcopy devices like laserwriters default to size=relative.
Echoing is typically turned off for the duration of plotting
for most (but not all) pen filters.
echo=y
forces echoing to be left on, and
echo=n
forces it to be turned off in case the default picked
by the pen filter is inappropriate.
Some filters by default pause at the end of plotting (usually with a beep) and wait for a carriage return. This is so you can see the last frame of the plot before the text is turned back on, obliterating it. For some devices this is not necessary, and there is no default pause at the end. Should the default not be appropriate (for example when plotting from within a shell repeatedly): endpause=y or endpause=n can be used to force this `end pause' on or off.
If this is set to yes any piped input will be copied to a temporary file before being used. It is typically turned off as most filters read the input only once. Any filter that may reread the data should turn this on.
cachepipe=y
Turns on the copying of the piped input to a temporary file.
cachepipe=n
Turns off the copying of the piped input to a temporary file.
mono=n
If mono=y, the plot will come out in black and white,
possibly speeding up the plotting and allowing the use of
such monochrome features as dithering and halftoning on
color screen devices.
For mono=y (monochrome devices), dithering is a means of representing a continuous-tone grey image. See the manual page for vplot raster for a discussion of dithering methods. If dither=0, no special treatment will be given to raster colors. (This means that all the points in the raster image will be shaded except those with color 0.) Available dithering methods are:
1 Random Dither
2 Ordered Dither
3 Minimized Average Error Method
4 Digital Halftoning Method
Devices that do their own dithering may not support all of these methods.
This parameter applies only when using dithering
(described above) to plot grey rasters on a monochrome
device. It has been observed that grey scale reproduction
on hardcopy devices is quite different than that on
graphics displays. Briefly, the transition from black to
white occurs more rapidly on a display device, leaving
both ends of the grey scale clipped at black or white.
This nonlinearity in the perceived grey scale is a useful
feature that can be simulated on a hardcopy device by use
of the greyc parameter. Greyc values less than 1. alter
the grey scale to simulate this nonlinearity. The smaller
the greyc value, the more rapidly the transition from black
to white occurs. See the vplot raster manual page for a more
complete discussion of this parameter and how to use it.
This parameter also applies only when using dithering
to plot grey rasters on monochrome devices. It has been
noted that grey rasters come out significantly darker
than expected on a hardcopy device than when they are
displayed on a graphics screen. This parameter applies
a correction based on the assumption that this darkening
is due to the overlap of pixels on the hardcopy device.
Pixc values less than 1. shift the grey color scale
toward white to compensate for the darkening due to pixel
overlap. See the vplot raster manual page for a more
complete discussion of this parameter and how to use it.
Color 0 is the background color on all devices. For
monochrome paper plotters, this is usually WHITE,
the color of the paper. On these devices color 7 (WHITE)
comes out as BLACK since it has to be the opposite of
color 0. If invras=y, this convention is reversed for
the purposes of dithered raster, so that color 0 is black
and color 7 is white despite the fact that this color
scheme is the reverse of that used for vectors on the same
plot. This option has no effect on raster that is not dithered.
If wantras=n, all raster data will be displayed
as a solid white block. This shows where the raster
data is, but on most devices will plot significantly
faster. This allows you to get the general layout of
your plot right without having to wait hours for the raster
data to plot on your screen.
If interact=file_name is specified, at the end of each
plot the cursor will be turned on and you may pick points
around the screen. The Vplot coordinates of these points
will be stored into the file file_name. Picking the far
upper-right hand corner of the screen will end the picking.
(The may also be device-dependent ways to end the picking,
such as hitting Escape or q.) Many of the pen options are
specified in Vplot coordinates, in inches. This option
allows you to find the coordinates of specific points of
interest. It is a primitive sort of interaction, but useful.
This option can also be quite useful for low-level hand editing
of Vplot files in conjunction with ``plas -i'' and ``pldb -i''.
If all else fails, selfdoc=y will force pen to self document
no matter what it thinks it should do.
(This applies to the non-SEP version only.)
If the signal option is set to anything, then no signal
catching will be done. Useful for debugging.
These options allow various sorts of linear transformations
on the color table. The first three numbers are the amounts
that red, green, and blue on the input will be mapped into
the given color. The last number is an additive constant.
For example, to reverse the color red, you would do
red=-1.,0.,0.,1. This would cause a black to white grey
scale to come out from red to cyan. Any values for these
parameters are allowed; colors are clipped to fully
saturated or fully off. Note this option only affects
explicitly user-defined colors.
This allows a printer ``gamma'' correction for the
given color. A large number makes the overall color
scale darker, a small number makes the overall color
scale brighter. Nonpositive powers are not valid.
Note this option only affects explicitly user-defined colors.
The colormask option is used to ``turn off'' certain
color planes in the device. This option is useful if
you wish to submit color figures to printers, who
often require the plot to be broken up into 4 different
``color planes''. It is somewhat limited. It only affects
colors set by the user, so if you want it to affect the
default colors 0 through 7 you'll have to set these yourself.
(You can easily create a file to do this using plas.
Prepend this to your plot file.) Each of the first 4 ``y/n''
toggles controls a color plane. ``Masked off'' color planes
are set to the value of the corresponding plane of the current
background color, color 0, which is always left untouched.
(So make sure to set color 0 first thing!) The 4 color planes
will be red, green, blue, and white if the background
color is black; and cyan, magenta, yellow, and black if
the background color is white. The 5th ``y/n'' toggle controls
whether the planes are plotted in color. (This option should
not be used if more than one plane is on (in which case it is
undefined) or if the 4th plane is on (in which case it is
unnecessary).)
The original filter was pen, written by Rob Clayton, who also invented vplot. Originally it was only possible to do vectors and that on only one device. Vplot has since been expanded beyond recognition, and is supported on about 20 devices. Michel Debiche, Glenn Kroeger, Chuck Karish, Steve Cole, and especially Joe Dellinger have all worked on Vplot at one time or another.
This documentation was written by Joe Dellinger.
Please read the official Vplot copyright notice, which is contained in the Vplot manual page.
There are a few ``magic numbers'' referred to in this documentation. These are defined in ``vplot.h'', and are subject to change.
Vplot was never intended to be used in an interactive way, but does OK for hard-copy purposes. It would be nice if someone out there took Vplot apart and rebuilt it again in an interactive framework, using a standardized meta-language. (We did not use a standard meta-language because none existed at the time Vplot was started, circa late 70's. Since then Vplot has slowly grown, for the most part staying backwards compatible.)
Pen has a huge number of options supporting backwards compatibility, and would need twice as many to make absolutely everyone happy. Most of the completely arcane ones have finally died a merciful death.
Not all devices support all the primitives, but at least the software capability exists. Several generic software routines inside `pen' should be redone when possible, as I was just learning C when I wrote them. They seem to work reliably, however. We use vplot a lot and haven't seen bugs in the device-independent code in a long time now. Bugs in device-dependent code is another story. (There is a tendency for people to only support a device to the extent that it does what they themselves need, which creates problems when someone else comes along and tries to do something else with it.)
Why are we still using inches? Everything should be changed to centimeters! (Except that, strangely enough, every device we have here has a screen resolution that is defined by the manufacturer in terms of pixels per INCH! So how serious is the US on standardizing with the rest of the world anyway?)
Bona-fide bugs that I know about but haven't bothered to fix are listed in the file `known_bugs'. There are also such files in device subdirectories where appropriate.
graphics/vplot