graph Application
plot Program
pic2plot Program
tek2plot Program
plotfont Utility
spline Program
ode Program
libplot, a Function Library
The GNU plotting utilities consist of eight command-line programs: the
graphics programs graph, plot, pic2plot,
tek2plot, and plotfont, and the mathematical programs
spline, ode, and double. Distributed with these
programs is GNU libplot, the library on which the graphics
programs are based. libplot is a function library for
device-independent two-dimensional vector graphics, including vector
graphics animations under the X Window System. There are versions
for both C and C++.
The graphics programs and libplot can export vector graphics in
the following ten formats.
xv.
xv.
idraw-editable Postscript format. Files in this format
may be sent to a Postscript printer, imported into another document, or
edited with the free idraw drawing editor. See section How to get idraw.
xfig drawing editor. See section How to get xfig.
xterm terminal
emulator program and the MS-DOS version of kermit.
plot program can translate it to any of the preceding formats.
Of the command-line graphics programs, the best known is graph,
which is an application for plotting two-dimensional scientific data.
It reads one or more data files containing datasets, and outputs a plot.
The above output formats are supported. The corresponding commands are
graph -T X, graph -T pnm, graph -T gif,
graph -T ai, graph -T ps, graph -T fig, graph
-T pcl, graph -T hpgl, graph -T tek, and graph.
graph without a `-T' option (referred to as `raw
graph') produces output in GNU metafile format.
graph can read datasets in both ASCII and binary format, and
datasets in the `table' format produced by the plotting program
gnuplot. It produces a plot with or without axes and labels.
You may specify labels and ranges for the axes, and the size and
position of the plot on the display. The labels may contain subscripts
and subscripts, Greek letters, and other special symbols; there is also
support for Cyrillic script (i.e., Russian) and Japanese. You may
specify the type of plotting symbol used for each dataset, and such
parameters as the style and thickness of the line (if any) used to
connect points in a dataset. The plotting of filled regions is
supported, as is the drawing of error bars. graph provides full
support for multiplotting. With a single invocation of graph,
you may produce a plot consisting of many sub-plots, either side by side
or inset. Each sub-plot will have its own axes and data.
graph -T X, graph -T tek, and raw graph have a
feature that most plotting programs do not have. They can accept input
from a pipe, and plot data points to the output in real time. For this
to occur, the user must specify ranges for both axes, so that
graph does not need to wait until the end of the input before
determining them.
The plot program is a so-called plot filter. It can translate
GNU graphics metafiles (produced for example by raw graph)
into any supported output format. The corresponding commands are
plot -T X, plot -T pnm, plot -T gif, plot
-T ai, plot -T ps, plot -T fig, plot -T pcl,
plot -T hpgl, plot -T tek, and plot. The
plot program is useful if you wish to produce output in several
different formats while invoking graph only once. It is also
useful if you wish to translate files in the traditional `plot(5)'
format produced by, e.g., the non-GNU versions of graph provided
with some operating systems. GNU metafile format is compatible with
plot(5) format.
The pic2plot program can translate from the pic language to any
supported output format. The pic language, which was invented at Bell
Laboratories, is used for creating box-and-arrow diagrams of the kind
frequently found in technical papers and textbooks. The corresponding
commands are pic2plot -T X, pic2plot -T pnm,
pic2plot -T gif, pic2plot -T ai, pic2plot -T ps,
pic2plot -T fig, pic2plot -T pcl, pic2plot -T hpgl,
pic2plot -T tek, and pic2plot.
The tek2plot program can translate from Tektronix format to any
supported output format. The corresponding commands are tek2plot
-T X, tek2plot -T pnm, tek2plot -T gif,
tek2plot -T ai, tek2plot -T ps, tek2plot -T fig,
tek2plot -T pcl, tek2plot -T hpgl, and tek2plot.
tek2plot is useful if you have an older application that produces
drawings in Tektronix format.
The plotfont program is a simple utility that displays a
character map for any font that is available to graph,
plot, pic2plot, or tek2plot. The 35 standard
Postscript fonts are available if the `-T X', `-T ai',
`-T ps', or `-T fig' options are used. The 45 standard PCL
5 fonts (i.e., "LaserJet" fonts) are available if the `-T ai',
`-T pcl' or `-T hpgl' options are used. In the latter two
cases (`-T pcl' and `-T hpgl'), a number of
Hewlett--Packard vector fonts are available as well. A set of
22 Hershey vector fonts, including Cyrillic fonts and a Japanese font,
is always available. When producing output for an X Window System
display, any of the graphics programs can use scalable X fonts.
Of the command-line mathematical programs, spline does spline
interpolation of scalar or vector-valued data. It normally uses either
cubic spline interpolation or exponential splines in tension, but like
graph it can function as a real-time filter under some
circumstances. Besides splining datasets, it can construct curves,
either open or closed, through arbitrarily chosen points in
d-dimensional space. ode provides the ability to
integrate an ordinary differential equation or a system of ordinary
differential equations, when provided with an explicit expression for
each equation. It supplements the plotting program gnuplot,
which can plot functions but not integrate ordinary differential
equations. The final command-line mathematical program, double,
is a filter for converting, scaling and cutting binary or ASCII data
streams. It is still under development and is not yet documented.
The libplot function library is discussed at length elsewhere in
this documentation. It gives C and C++ programs the ability to
draw such objects as lines, open and closed polylines, arcs (both
circular and elliptic), quadratic and cubic Bezier curves, circles and
ellipses, points, marker symbols, and text strings. The filling of
objects other than points, marker symbols, and text strings is supported
(fill color, as well as pen color, can be set arbitrarily). Text
strings can be drawn in any of a large number of fonts. The 35 standard
Postscript fonts are supported by the X Window System, Illustrator,
Postscript, and xfig drivers, and the 45 standard PCL 5 fonts
are supported by the Illustrator, PCL 5 and HP-GL/2 drivers. The
latter two also support a number of Hewlett--Packard vector fonts. All
drivers, including the PNM, GIF, Tektronix and metafile drivers, support
a set of 22 Hershey vector fonts.
The support for drawing text strings is extensive. Text strings may
include subscripts and superscripts, and may include characters chosen
from more than one font in a typeface. Many non-alphanumeric characters
may be included. The entire collection of over 1700 `Hershey glyphs'
digitized by Allen V. Hershey at the U.S. Naval Surface Weapons
Center, which includes many curious symbols, is built into
libplot. Text strings in the so-called EUC-JP encoding (i.e.,
the Extended Unix Code for Japanese) can be also be drawn. Such strings
may include both syllabic Japanese characters (Hiragana and Katakana)
and ideographic Japanese characters (Kanji). A library of 603
Kanji, including 596 of the 2965 frequently used Level 1 Kanji, is
built into libplot.
The drawing editors idraw and xfig are not distributed
along with the GNU plotting utilities. However, they are free software,
and you may readily obtain them elsewhere (see section Obtaining Auxiliary Software).
graph Application
Each invocation of graph reads one or more datasets from files
named on the command line or from standard input, and prepares a plot.
There are many command-line options for adjusting the visual appearance
of the plot.
See section graph command-line options, for documentation on all options.
The following sections explain how to use the most frequently used
options, by giving examples.
graph
By default, graph reads ASCII data from the files specified on
the command line, or from standard input if no files are specified. The
data are pairs of numbers, interpreted as the x and y
coordinates of data points:
0.0 0.0 1.0 0.2 2.0 0.0 3.0 0.4 4.0 0.2 5.0 0.6
Data points do not need to be on different lines, nor do the x and y coordinates of a data point need to be on the same line. However, there should be no blank lines in the input if it is to be viewed as forming a single dataset.
To plot such a dataset with graph, you could do
graph -T ps ascii_data_file > plot.ps
or equivalently
graph -T ps < ascii_data_file > plot.ps
This will produce an encapsulated Postscript file plot.ps, which
you may include in another document, display on a screen, or send
directly to a printer. (The `--page-size' option, or the
PAGESIZE environment variable, specifies the size of the printed
page. The default is "letter", i.e., 8.5in by 11in, but
"a4" or other ISO or ANSI page sizes can be specified instead.)
You may also do
graph -T fig < ascii_data_file > plot.fig
to produce a file plot.fig that you may edit with the the
free xfig drawing editor, or
graph -T ai < ascii_data_file > plot.ai
to produce a file plot.ai that you may edit with Adobe
Illustrator. If you do
graph -T hpgl < ascii_data_file > plot.plt
you will produce a file plot.plt in the Hewlett--Packard Graphics
Language (HP-GL/2) that you may send to a Hewlett--Packard plotter.
Similarly, you may use graph -T pcl to produce a file in PCL
5 format that may be printed on a LaserJet or other laser printer.
You may use graph -T X to pop up a window on an X
Window System display, and display the plot in it. For that, you
would do
graph -T X < ascii_data_file
If you use graph -T X, no output file will be produced; only
a window. The window will vanish if you type `q' or click your
mouse in it.
You may also use graph -T pnm to produce a PNM file (a "portable
anymap"), and graph -T gif to produce a pseudo-GIF file. If the
free image display application xv is available on your system,
you would use either of the two commands
graph -T pnm < ascii_data_file | xv - graph -T gif < ascii_data_file | xv -
to display the output file.
Another thing you can do is use graph -T tek to display a plot on
a device that can emulate a Tektronix 4014 graphics terminal.
xterm, the X Window System terminal emulator, can do this.
Within an xterm window, you would do
graph -T tek < ascii_data_file
xterm normally emulates a VT100 terminal, but when this command
is issued from within it, it will pop up a second window
(a `Tektronix window') and draw the plot in it. The Japanese
terminal emulator kterm should be able to do the same, provided
that it is correctly installed. Another piece of software that can
emulate a Tektronix 4014 terminal is the MS-DOS version of kermit.
graph may behave differently depending on the environment in
which it is invoked. We have already mentioned the PAGESIZE
environment variable, which affects the operation of graph -T ai,
graph -T ps, graph -T fig, graph -T pcl, and
graph -T hpgl. Similarly, the BITMAPSIZE environment
variable affects the operation of graph -T X, graph -T
pnm, and graph -T gif. The DISPLAY environment variable
affects the operation of graph -T X, and the TERM
environment variable affects the operation of graph -T tek.
There are also several environment variables that affect the operation
of graph -T pcl and graph -T hpgl. For a complete
discussion of the effects of the environment on graph, see
section Environment variables. The following remarks apply irrespective of
which output format is specified.
By default, successive points in the dataset are joined by solid line segments, which form a polygonal line or polyline that we call simply a `line'. You may choose the style of line (the `linemode') with the `-m' option:
graph -T ps -m 2 < ascii_data_file > plot.ps
Here `-m 2' indicates that linemode #2 should be used. If the dataset is rendered in monochrome, which is the default, the line can be drawn in one of five distinct styles. Linemodes #1 through #5 signify solid, dotted, dotdashed, shortdashed, and longdashed; thereafter the sequence repeats. If the `-C' option is used, the dataset will be rendered in color. For colored datasets, the line can be drawn in one of 25 distinct styles. Linemodes #1 through #5 signify red, green, blue, magenta, and cyan; all are solid. Linemodes #6 through #10 signify the same five colors, but dotted rather than solid. Linemodes #11 through #16 signify the same five colors, but dotdashed, and so forth. After linemode #25, the sequence repeats. Linemode #0, irrespective of whether the rendering is in monochrome or color, means that the line is not drawn.
If you wish to fill the polygon bounded by the line (i.e., shade it, or fill it with a solid color), you may use the `-q' option. For example,
echo .1 .1 .1 .9 .9 .9 .9 .1 .1 .1 | graph -T ps -C -m 1 -q 0.3 > plot.ps
will plot a square region with vertices (0.1,0.1), (0.1,0.9), (0.9,0.9), and (0.9,0.1). The repetition of the first vertex (0.1,0.1) at the end of the sequence of vertices ensures that the square will be closed: all four segments of its boundary will be drawn. The square will be drawn in red, since the colored version of linemode #1 is requested. The interior of the square will be filled with red to an intensity of 30%, as the `-q 0.3' option specifies. If the intensity were zero, the region would be filled with white, and if it were 1.0, the region would be filled with solid color. If the intensity were negative, the region would be unfilled, or transparent (the default).
You may choose the thickness (`width') of the line, whether it is filled or not, by using the `-W' option. For example, `-W 0.01' specifies that the line should have a thickness equal to 0.01 times the size of the display. Also, you may put symbols at each data point along the line by doing, for example,
graph -T ps -S 3 0.1 < ascii_data_file > plot.ps
where the first argument 3 indicates which symbol to plot. The optional second argument 0.1 specifies the symbol size as a fraction of the size of the `plotting box': the square within which the plot is drawn. Symbol #1 is a dot, symbol #2 is a plus sign, symbol #3 is an asterisk, symbol #4 is a circle, symbol #5 is a cross, and so forth. (See section Available marker symbols.) Symbols 1 through 31 are the same for all display types, and the color of a symbol will be the same as the color of the line it is plotted along.
Actually, you would probably not want to plot symbols at each point in the dataset unless you turn off the line joining the points. For this purpose, the `negative linemode' concept is useful. A line whose linemode is negative is not visible; however, any symbols plotted along it will have the color associated with the corresponding positive linemode. So, for example,
graph -T ps -C -m -3 -S 4 < ascii_data_file > plot.ps
will plot a blue circle at each data point. The circles will not be joined by line segments. By adding the optional second argument to the `-S' option, you may adjust the size of the circles.
graph will automatically generate abscissa (i.e., x)
values for you if you use the `-a' option. If this option is
used, no abscissa values should be given in the data file. The data
points will be taken to be regularly spaced along the abscissa. The two
arguments following `-a' on the command line will be taken as the
sampling interval and the abscissa value of the first data point. If
they are absent, they default to 1.0 and 0.0 respectively. For
example, the command
echo 0 1 0 | graph -T ps -a > plot.ps
produces exactly the same plot as
echo 0 0 1 1 2 0 | graph -T ps > plot.ps
graph will plot data with error bars, if the `-I e' option
is specified. If it is, the dataset should consist of triples
(x,y,error) rather than pairs (x,y). A
vertical error bar of the appropriate length will be plotted at each
data point. You may plot a symbol at each data point, along with the
error bar, by using the `-S' option in the usual way. The symbol
will be the same for each point in the dataset. You may use the
`-a' option in conjunction with `-I e', if you wish. If you
do, the dataset should contain no abscissa (i.e., x) values.
By default the limits on the x and y axes, and the spacing between the labeled ticks on each axis, are computed automatically. You may wish to set them manually. You may accomplish this with the `-x' and `-y' options.
echo 0 0 1 1 2 0 | graph -T ps -x -1 3 -y -1 2 > plot.ps
will produce a plot in which the x axis extends from -1
to 3, and the y axis from -1 to 2. By default,
graph tries to place about six numbered ticks on each axis. By
including an optional third argument to either `-x' or `-y',
you may manually set the spacing of these ticks, also. For example,
using `-y -1 2 1' rather than `-y -1 2' will produce a
y axis with labeled ticks at -1, 0, 1, and 2,
rather than at the locations that graph would choose by default,
which would be -1, -0.5, 0, 0.5, 1, 1.5, and 2. In
general, if a third argument is present then labeled ticks will be
placed at each of its integer multiples.
To make an axis logarithmic, you may use the `-l' option. For example,
echo 1 1 2 3 3 1 | graph -T ps -l x > plot.ps
will produce a plot in which the x axis is logarithmic, but the y axis is linear. To make both axes logarithmic, you would use `-l x -l y'. By default, the upper and lower limits on a logarithmic axis are powers of ten, and there are tick marks at each power of ten and at its integer multiples. The tick marks at the powers of ten are labeled. If the axis spans more than five orders of magnitude, the tick marks at the integer multiples are omitted.
If you have an unusually short logarithmic axis, you may need to increase the number of labeled ticks. To do this, you should specify a tick spacing manually. For example, `-l x -x 1 9 2' would produce a plot in which the x axis is logarithmic and extends from 1 to 9. Labeled ticks would be located at each integer multiple of 2, i.e., at 2, 4, 6, and 8.
You may label the x and y axes with the `-X' and `-Y' options, respectively. For example,
echo 1 1 2 3 3 1 | graph -T ps -l x -X "A Logarithmic Axis" > plot.ps
will label the log axis in the preceding example. By default the label for the y axis (if any) will be rotated 90 degrees, unless you use the `--toggle-rotate-y-label' option. You may specify a `top label', or title for the plot, by using the `-L' option. Doing, for example,
echo 1 1 2 3 3 1 | graph -T ps -l x -L "A Simple Example" > plot.ps
will produce a plot with a title on top.
The size of the x axis and y axis labels is specified with the `-f' option, and the size of the title is specified with the `--title-font-size' option. For example,
echo 1 1 2 3 3 1 | graph -T ps -X "Abscissa" -f 0.1 > plot.ps
will produce a plot in which the font size of the x axis label, and each of the numerical tick labels, is very large (0.1 times the size of the plotting box, i.e., the square within which the plot is drawn).
The font in which the labels specified with the `-X', `-Y',
and `-L' options are drawn can be specified with the `-F'
option. For example, `-F Times-Roman' will make the labels appear
in Times-Roman instead of the default font (which is Helvetica, unless
`-T pnm', `-T gif', `-T pcl', `-T hpgl' or `-T
tek' is specified). Font names are case-insensitive, so `-F
times-roman' will work equally well. The available fonts include 35
Postscript fonts (for all variants of graph other than
graph -T pnm, graph -T gif, graph -T pcl,
graph -T hpgl and graph -T tek), 45 PCL 5 fonts (for
graph -T ai, graph -T pcl and graph -T hpgl), a
number of Hewlett--Packard vector fonts (for graph -T pcl and
graph -T hpgl), and 22 Hershey vector fonts. The Hershey fonts
include HersheyCyrillic, for Russian, and HersheyEUC, for Japanese. For
a discussion of the available fonts, see section Available text fonts. The
plotfont utility will produce a character map of any available
font. See section The plotfont Utility.
The format of the labels drawn with the `-X', `-Y', and `-L' options may be quite intricate. Subscripts, superscripts, square roots, and switching fonts within a typeface are all allowed. The above examples do not illustrate this, but for details, see section Text string format and escape sequences.
Each of the preceding examples produced a plot containing the default sort of grid (a square box, with ticks and labels drawn along its lower edge and its left edge). There are actually several sorts of grid you may request. The `-g 0', `-g 1', `-g 2', and `-g 3' options yield successively fancier grids. What they yield, respectively, is no grid at all, a pair of axes with ticks and labels, a square box with ticks and labels, and a square box with ticks, labels, and grid lines. As you can see, `-g 2' is the default. There is also a `-g 4' option, which yields a slightly different sort of grid: a pair of axes that cross at the origin. This last sort of grid is useful if the x or y coordinates of the data points you are plotting are both positive and negative.
To rotate the plotting box by 90 degrees counterclockwise on your
graphics display, you would add `--rotation 90' to the graph
command line. You may also specify `--rotation 180', to produce an
upside-down plot, or `--rotation 270'.
To alter the linear dimensions of the plotting box, and also to position it in a different part of the display, you could do something like
graph -T ps -h .3 -w .6 -r .1 -u .1 < ascii_data_file > plot.ps
Here the `-h' and `-w' options specify the height and width of the plotting box, and the `-r' and `-u' options indicate how far up and to the right the lower left corner of the plotting box should be positioned. All dimensions are expressed as fractions of the size of the graphics display, which by convention is a square. By default, the height and width of the plotting box equal 0.6, and the `upward shift' and the `rightward shift' equal 0.2. So the above example will produce a plot that is half as tall as usual. Compared to its usual position, the plot will be shifted slightly downward and to the left.
Several command-line options specify sizes or dimensions as fractions of the size of the plotting box, rather than as fractions of the size of the display. For example, `-S 3 .01' specifies that the plotting symbols for the following dataset should be of type #3, and should have a font size equal to 0.01, i.e. 0.01 times the minimum dimension (height or width) of the plotting box. If the `-h' or `-w' options are employed to expand or contract the plot, such sizes or dimensions will scale in tandem. That is presumably the right thing to do.
The `-h', `-w', `-r', and -u options may be
combined with the `--rotation' option. If they appear together,
the plotting box is first positioned, and then rotated. In fact,
`--rotation' specifies how the plot should be mapped to the
graphics display, rather than how the plot is designed.
The `graphics display' is an abstraction. For graph -T X, it
is a window on an X display. For graph -T pnm and
graph -T gif, it is a square or rectangular bitmap. In these
three cases, the size of the graphics display can be set by using the
--bitmap-size option, or by setting the BITMAPSIZE
environment variable. For graph -T tek, the graphics display is
a square region occupying the central part of a Tektronix display.
(Tektronix displays are 4/3 times as wide as they are high.) For
graph -T ai and graph -T ps, by default it is a square
region centered on an 8.5in by 11in page (US letter
size), occupying its full width with allowance being made for margins.
For graph -T fig, by default it is a square region of the
same size, positioned in the upper left corner of an xfig
display. For graph -T pcl and graph -T hpgl, by
default it is a square region of the same size, with position and
orientation on the page being controlled by environment variables. The
page size used by graph -T ai, graph -T ps, graph -T
fig, graph -T pcl, and graph -T hpgl can be set by using
the --page-size option, or by setting the environment variable
PAGESIZE. For example, setting PAGESIZE to "a4" would
position the graphics display appropriately on an A4-size page
(21cm by 29.7cm).
It is frequently the case that several datasets need to be displayed on the same plot. If so, you may wish to distinguish the points in different datasets by joining them by lines of different types, or by using plotting symbols of different types.
A more complicated example would be the following. You may have a file containing a dataset that is the result of experimental observations, and a file containing closely spaced points that trace out a theoretical curve. The second file is a dataset in its own right. You would presumably plot it with line segments joining successive points, so as to trace out the theoretical curve. But the first dataset, resulting from experiment, would be plotted without such line segments. In fact, a plotting symbol would be plotted at each of its points.
These examples, and others like them, led us to define a set of seven attributes which define the way in which a dataset should be plotted. These attributes, which can be set by command-line options, are the following.
Color/monochrome (a choice of one or the other) is the simplest. This choice is toggled with the `-C' option. The `linemode' (i.e., line style) specifies how the line segments joining successive points should be drawn; it is specified with the `-m' option. Linemode #0 means no linemode at all, for example. `Linewidth' means line thickness; it is specified with the `-W' option. `Symbol type' and `symbol size', which are specified with the `-S' option, specify the symbol plotted at each point of the dataset. `Symbol font name' refers to the font from which plotting symbols #32 and above, which are taken to be characters rather than geometric symbols, are selected. It is set with the `--symbol-font-name' option, and is relevant only if `-S' is used to request such special plotting symbols. Finally, the polygonal line joining the points in a dataset may be filled, to create a filled or shaded polygon. The `fill fraction' is set with the `-q' option. A negative fill fraction means no fill, or transparent; zero means white, and 1.0 means solid, or fully colored.
The preceding seven attributes refer to the way in which datasets are plotted. Datasets may also differ from one another in the way in which they are read from files. The dataset(s) in a file may or may not contain error bars, for example. If a file contains data with error bars, the `-I e' option should occur on the command line before the file name. (The `-I' option specifies the input format for the following files.)
The following illustrates how datasets in three different input files could be plotted simultaneously.
graph -T ps -m 0 -S 3 file_1 -C -m 3 file_2 -C -W 0.02 file_3 > output.ps
The dataset in file_1 will be plotted in linemode #0, so
successive points will not be joined by lines. But symbol #3 (an
asterisk) will be plotted at each point. The dataset in file_2
will be plotted in color, and linemode #3 will be used. In color
plotting, linemode #3 is interpreted as a solid blue line. The second
`-C' on the command line turns off color for file_3. The
points in the third dataset will be joined by a black line with
thickness 0.02, as a fraction of the size (i.e., minimum dimension) of
the graphics display.
The above command line could be made even more complicated by specifying additional options (e.g., `-q' or `-I') before each file. In fact the command line could also include such standard options as `-x' or `-y', which specify the range of each axis. Such options, which refer to the plot as a whole rather than to individual datasets, should appear before the first file name. For example, you could do
graph -T ps -x 0 1 0.5 -m 0 -S 3 file_1 -C -m 3 file_2 > output.ps
Note that it is possible to include the special file name `-',
which refers to standard input, on the command line. So you may produce
a plot in part from files, and in part from input that is piped to
graph from another program.
Each input file may include more than one dataset. If so, the command line options preceding a file on the command line will take effect for all datasets in that file. There are two exceptions to this. By default, the linemode is incremented (`bumped') from one dataset to the next. This feature is usually quite convenient. For example, if you do
graph -T ps -m 3 file_1 > output.ps
the first dataset in file_1 will appear in linemode #3, the
second in linemode #4, etc. In fact if you do
graph -T ps file_1 file_2 ... > output.ps
without specifying linemode explicitly, the successive datasets read from the files on the command line will appear in linemode #1, linemode #2, .... If you do not like this feature, you may turn it off, or in general toggle it, by using the `-B' option.
You may also control manually the linemode and symbol type used for the datasets within any file. You would do this by including directives in the file itself, rather than on the command line. For example, if the line
#m=-5,S=10
appeared in an ASCII-format input file, it would be interpreted as a
directive to switch to linemode #-5 and symbol type #10 for the
following dataset. Future releases of graph may provide the
ability to set each of the seven dataset attributes in this way.
It is occasionally useful to display several plots at once on a single page, or on a single graphics display. We call such a composite plot a multiplot. One common sort of multiplot is a small plot inset into a larger one. Another sort is two or more plots side by side.
graph can draw multiplots consisting of an arbitrarily large
number of sub-plots. When multiplotting, graph draws each
sub-plot in its own `virtual display'. When an ordinary plot is drawn,
the virtual display is the same as the physical display. But when a
multiplot is drawn, the virtual display may be any smaller square
region. The following example illustrates the idea.
graph -T ps data_file_1 --reposition .35 .35 .3 data_file_2
Here data_file_1 is plotted in the usual way. The
`--reposition' option specifies that when data_file_2 is
plotted, it will be drawn within a virtual display. For the purposes of
the `--reposition' option, the physical display is a square with
lower left corner (0.0,0.0) and upper right corner (1.0,1.0). In those
coordinates, the virtual display will be a square of size 0.3 with lower
left corner (0.35,0.35). So the second sub-plot will be inset into
the first.
Just as the `-w', `-h', `-r', and `-u' options may be used to set the size and position of a plotting box within the physical display, so they may be used to set the size and position of a plotting box within a virtual display. For example,
graph -T ps data_file_1 --reposition .35 .35 .3 -w .4 -r .3 data_file_2
will yield a multiplot in which the second sub-plot is significantly different. Its plotting box will have a width only 0.4 times the width of the virtual display. However, the plotting box will be centered within the virtual display, since the distance between the left edge of the plotting box and the left edge of the virtual display will be 0.3 times the width of the virtual display.
By convention, before each sub-plot of a multiplot other than the first is drawn, a `blankout region' surrounding its plotting box is erased. (That is, it is filled with white.) This erasure prevents the sub-plots from overlapping and producing a messy result. By default, the blankout region is a rectangular region 30% larger in each dimension than the plotting box for the sub-plot. This is appropriate if the sub-plot is a small one that is inset into the first sub-plot. It may not be appropriate, however, if you are preparing a multiplot in which several sub-plots appear side by side. You may use the `--blankout' option to adjust this parameter. For example, specifying `--blankout 1.0' will make the blankout region for a sub-plot coincide with its plotting box. Specifying `--blankout 0.0' will prevent any blanking out from occurring. The blankout parameter may differ from sub-plot to sub-plot.
It should be emphasized that every sub-plot in a multiplot is a plot in
its own right. All the usual options (`-m', `-S', `-x',
`-y', etc.) can be applied to each sub-plot separately. The
options for a sub-plot should occur on the graph command line
immediately after the `--reposition' option that applies to it.
Each sub-plot may be prepared from more than a single dataset, also.
The names of the data files for each subplot should occur on the command
line before the following `--reposition' option, if any.
By default, graph reads datasets in ASCII format. But it can
also read datasets in any of three binary formats (single precision
floating point, double precision floating point, and integer).
These three input formats are specified by the `-I d', `-I f',
and `-I i' options, respectively.
There are two advantages to using binary data: 1) graph runs
significantly faster because the computational overhead for converting
data from ASCII to binary is eliminated, and 2) the input files may
be significantly smaller. If you have very large datasets, using
binary format may reduce storage and runtime costs.
For example, you may create a single precision binary dataset as output from a C language program:
#include <stdio.h>
void write_point (float x, float y)
{
fwrite(&x, sizeof (float), 1, stdout);
fwrite(&y, sizeof (float), 1, stdout);
}
You may plot data written this way by doing:
graph -T ps -I f < binary_data_file > plot.ps
@ifnottex
The inclusion of multiple datasets within a single binary file is
supported. If a binary file contains more than a single dataset,
successive datasets should be separated by a single occurrence of the
the largest possible number. For single precision datasets this is the
quantity FLT_MAX, for double precision datasets it is the
quantity DBL_MAX, and for integer datasets it is the quantity
INT_MAX. On most machines FLT_MAX is approximately
3.4x10^38, DBL_MAX is approximately 1.8x10^308, and
INT_MAX is 2^32-1.
If you are reading datasets from more than one file, it is not required that the files be in the same format. For example,
graph -T ps -I f binary_data_file -I a ascii_data_file > plot.ps
will read binary_data_file in `f' (binary single precision)
format, and ascii_data_file in `a' (normal ASCII) format.
There is currently no support for reading and plotting binary data with
error bars. If you have data with error bars, you should supply the data
to graph in ASCII, and use the `-I e' option.
graph can also read data files in the ASCII `table' format
produced by the gnuplot plotting program. For this, you should
use the `-I g' option. Such a data file may consist of more than
one dataset.
To sum up: there are six supported data formats, `a' (normal
ASCII), `e' (ASCII with error bars), `g' (the ASCII `table'
format produced by gnuplot), `f' (binary single precision),
`d' (binary double precision), and `i' (binary integer).
Input files may be in any of these six formats.
graph command-line options
The graph program reads one or more datasets from files named on
the command line or from standard input, and prepares a plot. The
output format or display type is specified with the `-T' option.
By default, graph reads ASCII data from the files specified on
the command line. The data are pairs of numbers, interpreted as the
x and y coordinates of data points. If no file names
are specified, or the file name `-' is specified, the standard
input is read. The output file is written to standard output, unless
the `-T X' option is specified. In that case the graph is
displayed in a window on an X Window System display, and there is no
output file.
There are many command-line options for adjusting the visual appearance of the plot. The relative order of file names and command-line options is important. Only the options that precede a file name on the command line take effect for that file.
The following sections list the possible options. Each option that takes an argument is followed, in parentheses, by the type and default value of the argument. There are five sorts of option.
graph, i.e., relevant only if no
display type or output format is specified with the `-T' option.
(See section Raw graph options.)
@ifnottex
The behavior of graph is also affected by a number of environment
variables, so there is a section discussing them as well.
The following options affect an entire plot. They should normally occur at most once, and should appear on the command line before the first file name. If a multiplot is being drawn, they may (with the exception of the `-T' option) occur more than once. If so, the second and later occurrences should be placed on the command line immediately after each `--reposition x y' option.
idraw-editable Postscript, the format used by the xfig
drawing editor, the Hewlett--Packard PCL 5 printer language, the
Hewlett--Packard Graphics Language (by default, HP-GL/2), Tektronix
format, and device-independent GNU graphics metafile format.
graph -T pnm, graph
-T gif, graph -T pcl, graph -T hpgl, graph -T tek,
and raw graph, for all of which "HersheySerif" is the default.)
Set the font used for the axis and tick labels, and for the plot title
(if any), to be font_name. The choice of font for the plot
title may be overridden with the `--title-font-name' option (see
below). Font names are case-insensitive. If the specified font is
not available, the default font will be used. Which fonts are available
depends on which `-T' option is used. For a list of all fonts, see
section Available text fonts. The plotfont utility will produce a character
map of any available font. See section The plotfont Utility.
graph not erase the
display device before it begins to plot.
This option is relevant only to graph -T tek and raw
graph. Tektronix displays and emulators are persistent, in the
sense that previously drawn graphics remain visible. So by repeatedly
using graph -T tek -s, you can build up a multiplot.
graph is to act as a real-time filter.
By default, the supplied limit(s) are strictly respected. However, the
`-R x' option may be used to request that they be rounded to the
nearest integer multiple of the spacing between labeled ticks. The
lower limit will be rounded downward, and the upper limit upward.
graph is to act as a real-time filter.
By default, the supplied limit(s) are strictly respected. However, the
`-R y' option may be used to request that they be rounded to the
nearest multiple of the tick spacing. The lower limit will be rounded
downward, and the upper limit upward.
graph -T X,
graph -T pnm, and graph -T gif. An unrecognized name
sets the color to the default. For information on what names are
recognized, see section Specifying Colors by Name. The environment variable
BG_COLOR can equally well be used to specify the background
color.
If the `-T gif' option is used, a transparent pseudo-GIF may be
produced by setting the TRANSPARENT_COLOR environment variable to
the name of the background color. See section Environment variables.
graph -T X,
graph -T pnm, and graph -T gif, for which the graphics
display size can be expressed in terms of pixels. The environment
variable BITMAPSIZE can equally well be used to specify the size.
The graphics display used by graph -T X is an X window. If
you choose a rectangular (non-square) window size, the fonts in the plot
will be scaled anisotropically, i.e., by different factors in the
horizontal and vertical direction. This requires an X11R6 display. Any
font that cannot be scaled in this way will be replaced by a default
scalable font, such as the Hershey vector font "HersheySerif".
For backward compatibility, the X resource Xplot.geometry,
which can be set by the user, may be used to set the window size,
instead of `--bitmap-size' or BITMAPSIZE.
libplot graphics library should be used. This is usually 1/850
times the size of the display, although if `-T X', `-T pnm',
or -T gif is specified, it is zero. By convention, a
zero-thickness line is the thinnest line that can be drawn. This is the
case in all output formats. Note, however, that the drawing editors
idraw and xfig treat zero-thickness lines as invisible.
graph -T tek does not support drawing lines with other than a
default thickness, and graph -T hpgl does not support doing
so if the environment variable HPGL_VERSION is set to a value
less than "2" (the default).
MAX_LINE_LENGTH
can also be used to specify the maximum line length. This option has no
effect on graph -T tek or raw graph, since they draw
polylines in real time and have no buffer limitations.
graph -T ai,
graph -T ps, graph -T fig, graph -T pcl, and
graph -T hpgl. "letter" means an 8.5in by 11in page.
Any ISO page size in the range "a0"..."a4" or ANSI page size in the
range "a"..."e" may be specified ("letter" is an alias for "a"
and "tabloid" is an alias for "b"). "legal", "ledger", and "b5"
are recognized page sizes also. The environment variable
PAGESIZE can equally well be used to specify the page size.
For graph -T ai and graph -T ps, the graphics display
within which the plot is drawn will be a square region centered on the
specified page, occupying its full width (with allowance being made for
margins). For graph -T fig, it will be a square region of the
same size, located in the upper left corner of an xfig display.
For graph -T pcl and graph -T hpgl, the graphics display
will be a square region of the same size, but may be positioned
differently. Fine control over its positioning on the page can be
accomplished by setting certain environment variables (see section Environment variables).
graph -T pnm, graph
-T gif, graph -T pcl, graph -T hpgl and graph -T
tek, for which "HersheySerif" is the default.) Set the font used for
the plot title to be font_name. Normally the font used for the
plot title is the same as that used for labeling the axes and the ticks
along the axes, as specified by the `-F' option. But the
`--title-font-name' option can be used to override this. Font
names are case-insensitive. If the specified font is not available, the
default font will be used. Which fonts are available depends on which
`-T' option is used. For a list of all fonts, see section Available text fonts. The plotfont utility will produce a character map of any
available font. See section The plotfont Utility.
The following options affect the way in which individual datasets are read from files, and drawn as part of a plot. They should appear on the command line before the file containing the datasets whose reading or rendering they will affect. They may appear more than once on a command line, if more than one file is to be read.
The following three options affect the way in which datasets are read from files.
gnuplot plotting program.
FLT_MAX, which is the largest possible
single precision floating point number. On most machines this is
approximately 3.4x10^38.
DBL_MAX, which is the largest possible
double precision floating point number. On most machines this is
approximately 1.8x10^308.
INT_MAX,
which is the largest possible integer. On most machines this is
2^31-1.
The following options affect the way in which individual datasets are drawn as part of a plot. These options set the six `attributes' (symbol type, symbol font, linemode, line thickness, fill fraction, and color/monochrome) that each dataset has.
libplot graphics
library. See section Available marker symbols. Symbol numbers greater than or equal
to 32 are interpreted as characters to be selected from a symbol font,
which can be set with the `--symbol-font-name' option (see below).
libplot graphics library should be used. This is
usually 1/850 times the size of the display, although if `-T X',
`-T pnm', or -T gif is specified, it is zero. By
convention, a zero-thickness line is the thinnest line that can be
drawn. This is the case in all output formats. Note, however, that the
drawing editors idraw and xfig treat zero-thickness lines
as invisible.
graph -T tek does not support drawing lines with other than a
default thickness, and graph -T hpgl does not support doing
so if the environment variable HPGL_VERSION is set to a value
less than "2" (the default).
graph -T tek, and it is
only partly effective in graph -T hpgl if the environment
variable HPGL_VERSION is set to "1".
-T tek is specified, in
which case it is "HersheySerif".) Set the symbol font, from which
plotting symbols numbered 32 and higher are selected, to be
symbol_font_name. Font names are case-insensitive. If the
specified font is not available, the default font will be used. Which
fonts are available depends on which `-T' option is used. For
example, if the `-T pcl' or `-T hpgl' option is used then
normally the Wingdings font, which is an alternative source of symbols,
becomes available. For a list of all fonts, see section Available text fonts. The
plotfont utility will produce a character map of any available
font. See section The plotfont Utility.
The following options are used for multiplotting (placing several plots on a display, or a page, at once).
graph -T tek
cannot clear regions, and graph -T hpgl cannot clear them if the
environment variables HPGL_VERSION and HPGL_OPAQUE_MODE
are set to non-default values (i.e., values other than "2" and
"yes", respectively).
graph options
The following option is relevant only to raw graph, i.e., is
relevant only if no display type or output format is specified with the
`-T' option. In this case graph outputs a graphics
metafile, which may be translated to other formats by invoking
plot. This option should appear on the command line before any
file names, since it affects the output of the plot (or multiplot) as a
whole.
META_PORTABLE to "yes".
The following options request information.
graph -T X, graph -T ai, graph -T ps,
and graph -T fig each support the 35 standard Postscript fonts.
graph -T ai, graph -T pcl, and graph -T hpgl
support the 45 standard PCL 5 fonts, and graph -T pcl and
graph -T hpgl support a number of Hewlett--Packard vector fonts.
All of the preceding, together with graph -T pnm, graph -T
gif, and graph -T tek, support a set of 22 Hershey vector fonts.
Raw graph in principle supports any of these fonts, since its
output must be translated to other formats with plot. The
plotfont utility will produce a character map of any available
font. See section The plotfont Utility.
graph and the plotting utilities
package, and exit.
The behavior of graph is affected by several environment
variables. We have already mentioned the environment variables
BITMAPSIZE, PAGESIZE, BG_COLOR, and
MAX_LINE_LENGTH. They serve as backups for the options
`--bitmap-size', `--page-size', `--bg-color', and
`--max-line-length'. The remaining environment variables are
specific to individual output formats.
graph -T X, which pops up a window on an X Window System
display and draws graphics in it, checks the DISPLAY
environment variable. The value of this variable determines the display
on which the window will be popped up.
graph -T pnm, which produces output in Portable Anymap
(PBM/PGM/PPM) format, is affected by the PNM_PORTABLE environment
variable. If its value is "yes", the output file will be in the
portable (human readable) version of PBM, PGM, or PPM format, rather
than the default (binary) version.
graph -T gif, which produces output in pseudo-GIF format, is
affected by two environment variables. If the value of the
INTERLACE variable is "yes", the pseudo-GIF output file will be
in interlaced format. Also, if the value of the
TRANSPARENT_COLOR environment variable is the name of a color
that appears in the output file, that color will be treated as
transparent by most applications that read GIF files. For information
on what color names are recognized, see section Specifying Colors by Name.
graph -T pcl, which produces PCL 5 output for
Hewlett--Packard printers and plotters, is affected by several
environment variables. The position of the graphics display on the page
can be adjusted by setting the PCL_XOFFSET and PCL_YOFFSET
environment variables, which may be specified in centimeters,
millimeters, or inches. For example, an offset could be specified
as "2cm" or "1.2in". Also, the display can be rotated 90 degrees
counterclockwise on the page by setting the PCL_ROTATE
environment variable to "yes". This is not the same as the rotation
obtained with the --rotation option, which sets the rotation
angle of the plot within the display. Besides "no" and "yes",
recognized values for the PCL_ROTATE variable are "0", "90",
"180", and "270". "no" and "yes" are equivalent to "0" and
"90", respectively.
The variable PCL_ASSIGN_COLORS is also recognized. It should be
set to "yes" when producing PCL 5 output for a color printer or
other color device. This will ensure accurate color reproduction by
giving the output device complete freedom in assigning colors,
internally, to its "logical pens". If it is "no" then the device will
use a fixed set of colored pens, and will emulate other colors by
shading. The default is "no" because monochrome PCL 5 devices,
which are much more common than colored ones, must use shading to
emulate color.
graph -T hpgl, which produces Hewlett--Packard Graphics Language
output, is also affected by several environment variables. The most
important is HPGL_VERSION, which may be set to "1", "1.5", or
"2" (the default). "1" means that the output should be generic
HP-GL, "1.5" means that the output should be suitable for the
HP7550A graphics plotter and the HP758x, HP7595A and HP7596A drafting
plotters (HP-GL with some HP-GL/2 extensions), and "2" means that
the output should be modern HP-GL/2. If the version is "1" or
"1.5" then the only available fonts will be vector fonts, and all lines
will be drawn with a default thickness (the `-W' option will not
work). Additionally, if the version is "1" then the filling of
arbitrary curves with solid color will not be supported (the `-q'
option may be used to fill circles and rectangles aligned with the
coordinate axes, though).
The position of the graph -T hpgl graphics display on the page
can be adjusted by setting the HPGL_XOFFSET and
HPGL_YOFFSET environment variables, which may be specified in
centimeters, millimeters, or inches. For example, an offset could be
specified as "2cm" or "1.2in". Also, the display can be rotated 90
degrees counterclockwise on the page by setting the HPGL_ROTATE
environment variable to "yes". This is not the same as the rotation
obtained with the --rotation option, which sets the rotation
angle of the plot within the display. Besides "no" and "yes",
recognized values for the HPGL_ROTATE variable are "0", "90",
"180", and "270". "no" and "yes" are equivalent to "0" and
"90", respectively. "180" and "270" are supported only if
HPGL_VERSION is "2" (the default).
Opaque filling and the drawing of visible white lines are
supported only if HPGL_VERSION is "2" (the default) and the
environment variable HPGL_OPAQUE_MODE is "yes" (the default).
If the value is "no" then opaque filling will not be used, and white
lines (if any), which are normally drawn with pen #0, will not
be drawn. This feature is to accommodate older HP-GL/2 devices.
HP-GL/2 pen plotters, for example, do not support opacity or the use
of pen #0 to draw visible white lines. Some older HP-GL/2 devices
reportedly malfunction if asked to draw opaque objects.
By default, graph -T hpgl will draw with a fixed set of pens.
Which pens are present may be specified by setting the HPGL_PENS
environment variable. If HPGL_VERSION is "1", the default
value of HPGL_PENS is "1=black"; if HPGL_VERSION is "1.5"
or "2", the default value of HPGL_PENS is
"1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan". The format
should be self-explanatory. By setting HPGL_PENS, you may
specify a color for any pen in the range #1...#31. For information
on what color names are recognized, see section Specifying Colors by Name. Pen #1
must always be present, though it need not be black. Any other pen in
the range #1...#31 may be omitted.
If HPGL_VERSION is "2" then graph -T hpgl will also be
affected by the environment variable HPGL_ASSIGN_COLORS. If
the value of this variable is "yes", then graph -T hpgl will not
be restricted to the palette specified in HPGL_PENS: it will
assign colors to "logical pens" in the range #1...#31, as
needed. The default value is "no" because other than color LaserJet
printers and DesignJet plotters, not many HP-GL/2 devices allow the
assignment of colors to logical pens.
graph -T tek, which produces output for a Tektronix terminal or
emulator, checks the TERM environment variable. If the value
of TERM is "xterm", "xterms", or "kterm", it is taken as a
sign that the current application is running in an X Window System
VT100 terminal emulator: an xterm. Before drawing graphics,
graph -T tek will emit an escape sequence that causes the
terminal emulator's auxiliary Tektronix window, which is normally
hidden, to pop up. After the graphics are drawn, an escape sequence
that returns control to the original VT100 window will be emitted. The
Tektronix window will remain on the screen.
If the value of TERM is "kermit", "ansi.sys", "ansissys",
"ansi.sysk", or "ansisysk", it is taken as a sign that the current
application is running in the VT100 terminal emulator provided by the
MS-DOS version of kermit. Before drawing graphics, graph
-T tek will emit an escape sequence that switches the terminal emulator
to Tektronix mode. Also, some of the Tektronix control codes emitted by
graph -T tek will be kermit-specific. There will be a
limited amount of color support, which is not normally the case (the 16
ansi.sys colors will be supported). After drawing graphics,
graph -T tek will emit an escape sequence that returns the
emulator to VT100 mode. The key sequence `ALT minus' can be
employed manually within kermit to switch between the two modes.
plot Programplot
The GNU plot filter plot displays GNU graphics metafiles or
translates them to other formats. It will take input from files
specified on the command line or from standard input. The `-T'
option is used to specify the desired output format. Supported output
formats include "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl",
"tek", and "meta" (the default).
The metafile format is a device-independent format for storage of vector
graphics. By default, it is a binary rather than a human-readable
format (see section The Graphics Metafile Format). Each of the graph, pic2plot,
tek2plot, and plotfont utilities will write a graphics
metafile to standard output if no `-T' option is specified on its
command line. The libplot graphics library may also be used to
produce metafiles. Metafiles may contain arbitrarily many pages of
graphics, but each metafile produced by graph contains only a
single page.
plot, like the metafile format itself, is useful if you wish to
preserve a vector graphics file, and display or edit it with more than
one drawing editor. The following example shows how you may do this.
To produce a plot of data arranged as alternating x and y
coordinates in an ASCII file, you may use graph as follows:
graph < ascii_data_file > test.meta
The file `test.meta' will be a single-page graphics metafile. Similarly, to create in metafile format a plot consisting of a simple figure, you may do:
echo 0 0 1 1 2 0 | spline | graph > test.meta
To display any such plot on an X Window System display, you would do
plot -T X test.meta
or
plot -T X < test.meta
To print the plot on a Postscript printer, you would do something like
plot -T ps < test.meta | lpr
To edit it with the free idraw drawing editor, you would do
plot -T ps < test.meta > test.ps idraw test.ps
To produce a "portable anymap" (a file in PBM, PGM, or PPM format, whichever is most appropriate) you would do
plot -T pnm < test.meta > test.pnm
and to produce a pseudo-GIF file, you would do
plot -T gif < test.meta > test.gif
Similarly, to produce a version of the plot that can be edited with Adobe Illustrator, you would do
plot -T ai < test.meta > test.ai
and to produce a version that can be edited with the free xfig
drawing editor, you would do
plot -T fig < test.meta > test.fig xfig test.fig
Other formats may be obtained by using plot -T pcl, plot -T
hpgl, and plot -T tek.
plot may behave differently depending on the environment in which
it is invoked. In particular, plot -T ai, plot -T ps,
plot -T fig, plot -T pcl, and plot -T hpgl are
affected by the environment variable PAGESIZE. plot -T
X, plot -T pnm, and plot -T gif are affected by the
environment variable BITMAPSIZE. The DISPLAY environment
variable affects the operation of plot -T X, and the
TERM environment variable affects the operation of plot -T
tek. There are also several environment variables that affect the
operation of plot -T pcl and plot -T hpgl. For a complete
discussion of the effects of the environment on plot, see
section Environment variables.
plot command-line options
The plot filter plot translates GNU graphics metafiles to other
formats. The `-T' option is used to specify the output format or
display type. Files in metafile format are produced by GNU
graph, pic2plot, tek2plot, plotfont, and
other applications that use the GNU libplot graphics library.
For technical details on the metafile format, see section The Graphics Metafile Format.
Input file names may be specified anywhere on the command line. That is, the relative order of file names and command-line options does not matter. If no file names are specified, or the file name `-' is specified, the standard input is read. The output file is written to standard output, unless the `-T X' option is specified. In that case the output is displayed in a window or windows on an X Window System display, and there is no output file.
The full set of command-line options is listed below. There are four sorts of option:
plot, i.e., relevant only if no
display type or output format is specified with the `-T' option.
Each option that takes an argument is followed, in parentheses, by the type and default value of the argument.
The following options set the values of drawing parameters.
idraw-editable Postscript, the format used by the xfig
drawing editor, the Hewlett--Packard PCL 5 printer language, the
Hewlett--Packard Graphics Language (by default, HP-GL/2), Tektronix
format, and device-independent GNU graphics metafile format.
plot -T
X or plot -T tek, which plot in real time, will separate
successive frames by screen erasures. plot -T pnm, plot -T
gif, plot -T ai, plot -T ps, plot -T fig,
plot -T pcl, and plot -T hpgl, which do not plot in real
time, will display only the last frame of any multi-frame page.
The default behavior, if `-p' is not used, is to display all pages.
For example, plot -T X displays each page in its own X
window. If the `-T pnm' option, the `-T gif' option, the
`-T ai' option, or the `-T fig' option is used, the default
behavior is to display only the first page, since files in PNM,
pseudo-GIF, AI, or Fig format may contain only a single page of
graphics.
Most metafiles produced by the GNU plotting utilities (e.g., by raw
graph) contain only a single page, consisting of two frames: an
empty one to clear the display, and a second one containing graphics.
graph. This is an
alternative form of multiplotting (see section Multiplotting: placing multiple plots on a single page).
plot -T X,
plot -T pnm, and plot -T gif, for which the graphics
display size can be expressed in terms of pixels. The environment
variable BITMAPSIZE can equally well be used to specify the size.
For backward compatibility, the X resource Xplot.geometry,
which can be set by the user, may be used to set the window size,
instead of `--bitmap-size' or BITMAPSIZE.
MAX_LINE_LENGTH
can also be used to specify the maximum line length. This option has no
effect on plot -T tek or raw plot, since they draw
polylines in real time and have no buffer limitations.
plot -T ai,
plot -T ps, plot -T fig, plot -T pcl, and
plot -T hpgl. "letter" means an 8.5in by 11in page.
Any ISO page size in the range "a0"..."a4" or ANSI page size in the
range "a"..."e" may be specified ("letter" is an alias for "a"
and "tabloid" is an alias for "b"). "legal", "ledger", and "b5"
are recognized page sizes also. The environment variable
PAGESIZE can equally well be used to specify the page size.
For plot -T ai and plot -T ps, the graphics display within
which the plot is drawn will be a square region centered on the
specified page, occupying its full width (with allowance being made for
margins). For plot -T fig, it will be a square region located of
the same size, located in the upper left corner of an xfig
display. For plot -T pcl and plot -T hpgl, the graphics
display will be a square region of the same size, but may be positioned
differently. Fine control over its positioning on the page may be
accomplished by setting certain environment variables (see section Environment variables).
The following options set the initial values of additional drawing parameters. All of these may be overridden by directives in the metafile itself. In fact, these options are useful mostly for plotting old metafiles in the pre-GNU `plot(5)' format, which did not include such directives.
plot -T X,
plot -T pnm, and plot -T gif. An unrecognized name
sets the color to the default. For information on what names are
recognized, see section Specifying Colors by Name. The environment variable
BG_COLOR can equally well be used to specify the background
color.
If the `-T gif' option is used, a transparent pseudo-GIF may be
produced by setting the TRANSPARENT_COLOR environment variable to
the name of the background color. See section Environment variables.
plot -T pnm, plot
-T gif, plot -T pcl, plot -T hpgl, plot -T tek,
and raw plot, for all of which "HersheySerif" is the default.)
Set the font initially used for text (i.e., for `labels') to
font_name. Font names are case-insensitive. If the specified
font is not available, the default font will be used. Which fonts are
available depends on which `-T' option is used. For a list of all
fonts, see section Available text fonts. The plotfont utility will produce a
character map of any available font. See section The plotfont Utility.
libplot graphics library should be used. This is
usually 1/850 times the size of the display, although if `-T X',
`-T pnm', or -T gif is specified, it is zero. By
convention, a zero-thickness line is the thinnest line that can be
drawn. This is the case in all output formats. Note, however, that the
drawing editors idraw and xfig treat zero-thickness lines
as invisible.
plot -T tek does not support drawing lines with other than a
default thickness, and plot -T hpgl does not support doing so
if the environment variable HPGL_VERSION is set to a value less
than "2" (the default).
The following option is relevant only to raw plot, i.e., relevant
only if no output type is specified with the `-T' option. In this
case plot outputs a graphics metafile, which may be translated to
other formats by a second invocation of plot.
META_PORTABLE to "yes".
plot will automatically determine which type of GNU metafile
format the input is in. There are two types: binary (the default)
and portable (human-readable). The binary format is machine-dependent.
See section The Graphics Metafile Format.
For compatibility with older plotting software, the reading of input files in the pre-GNU `plot(5)' format is also supported. This is normally a binary format, with each integer in the metafile represented as a pair of bytes. The order of the two bytes is machine dependent. You may specify that input file(s) are in plot(5) format rather than ordinary GNU metafile format by using either the `-h' option ("high byte first") or the `-l' option ("low byte first"), whichever is appropriate. Some non-GNU systems support an ASCII (human-readable) variant of plot(5) format. You may specify that the input is in this format by using the `-A' option. Irrespective of the variant, a file in plot(5) format includes only one page of graphics.
The following options request information.
plot -T X, plot -T ai, plot -T ps,
and plot -T fig each support the 35 standard Postscript fonts.
plot -T ai, plot -T pcl, and plot -T hpgl
support the 45 standard PCL 5 fonts, and plot -T pcl and
plot -T hpgl support a number of Hewlett--Packard vector fonts.
All of the preceding, together with plot -T pnm, plot -T
gif, and plot -T tek, support a set of 22 Hershey vector fonts.
Raw plot in principle supports any of these fonts, since its
output must be translated to other formats with plot. The
plotfont utility will produce a character map of any available
font. See section The plotfont Utility.
plot and the plotting utilities
package, and exit.
The behavior of plot is affected by several environment
variables. We have already mentioned the environment variables
BITMAPSIZE, PAGESIZE, BG_COLOR, and
MAX_LINE_LENGTH. They serve as backups for the options
`--bitmap-size', `--page-size', `--bg-color', and
`--max-line-length'. The remaining environment variables are
specific to individual output formats.
plot -T X, which pops up a window on an X Window System
display and draws graphics in it, checks the DISPLAY
environment variable. The value of this variable determines the display
on which the window will be popped up.
plot -T pnm, which produces output in Portable Anymap
(PBM/PGM/PPM) format, is affected by the PNM_PORTABLE environment
variable. If its value is "yes", the output file will be in the
portable (human readable) version of PBM, PGM, or PPM format, rather
than the default (binary) version.
plot -T gif, which produces output in pseudo-GIF format, is
affected by two environment variables. If the value of the
INTERLACE variable is "yes", the pseudo-GIF output file will be
in interlaced format. Also, if the value of the
TRANSPARENT_COLOR environment variable is the name of a color
that appears in the output file, that color will be treated as
transparent by most applications that read GIF files. For information
on what color names are recognized, see section Specifying Colors by Name.
plot -T pcl, which produces PCL 5 output for Hewlett--Packard
printers and plotters, is affected by several environment variables.
The position of the graphics display on the page can be adjusted by
setting the PCL_XOFFSET and PCL_YOFFSET environment
variables, which may be specified in centimeters, millimeters, or
inches. For example, an offset could be specified as "2cm" or "1.2in".
Also, the display can be rotated 90 degrees counterclockwise on the
page by setting the PCL_ROTATE environment variable to "yes".
Besides "no" and "yes", recognized values for this variable are "0",
"90", "180", and "270". "no" and "yes" are equivalent to "0"
and "90", respectively.
The variable PCL_ASSIGN_COLORS is also recognized. It should be
set to "yes" when producing PCL 5 output for a color printer or
other color device. This will ensure accurate color reproduction by
giving the output device complete freedom in assigning colors,
internally, to its "logical pens". If it is "no" then the device will
use a fixed set of colored pens, and will emulate other colors by
shading. The default is "no" because monochrome PCL 5 devices,
which are much more common than colored ones, must use shading to
emulate color.
plot -T hpgl, which produces Hewlett--Packard Graphics Language
output, is also affected by several environment variables. The most
important is HPGL_VERSION, which may be set to "1", "1.5", or
"2" (the default). "1" means that the output should be generic
HP-GL, "1.5" means that the output should be suitable for the
HP7550A graphics plotter and the HP758x, HP7595A and HP7596A drafting
plotters (HP-GL with some HP-GL/2 extensions), and "2" means that
the output should be modern HP-GL/2. If the version is "1" or
"1.5" then the only available fonts will be vector fonts, and all lines
will be drawn with a default thickness (the `-W' option will not
work). Additionally, if the version is "1" then the filling of
arbitrary curves with solid color will not be supported (circles and
rectangles aligned with the coordinate axes may be filled, though).
The position of the plot -T hpgl graphics display on the page can
be adjusted by setting the HPGL_XOFFSET and HPGL_YOFFSET
environment variables, which may be specified in centimeters,
millimeters, or inches. For example, an offset could be specified as
"2cm" or "1.2in". Also, the display can be rotated 90 degrees
counterclockwise on the page by setting the HPGL_ROTATE
environment variable to "yes". Besides "no" and "yes", recognized
values for this variable are "0", "90", "180", and "270". "no"
and "yes" are equivalent to "0" and "90", respectively. "180" and
"270" are supported only if HPGL_VERSION is "2" (the
default).
Opaque filling and the drawing of visible white lines are
supported only if HPGL_VERSION is "2" (the default) and the
environment variable HPGL_OPAQUE_MODE is "yes" (the default).
If the value is "no" then opaque filling will not be used, and white
lines (if any), which are normally drawn with pen #0, will not
be drawn. This feature is to accommodate older HP-GL/2 devices.
HP-GL/2 pen plotters, for example, do not support opacity or the use
of pen #0 to draw visible white lines. Some older HP-GL/2 devices
reportedly malfunction if asked to draw opaque objects.
By default, plot -T hpgl will draw with a fixed set of pens.
Which pens are present may be specified by setting the HPGL_PENS
environment variable. If HPGL_VERSION is "1", the default
value of HPGL_PENS is "1=black"; if HPGL_VERSION is "1.5"
or "2", the default value of HPGL_PENS is
"1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan". The format
should be self-explanatory. By setting HPGL_PENS, you may
specify a color for any pen in the range #1...#31. For information
on what color names are recognized, see section Specifying Colors by Name. Pen #1
must always be present, though it need not be black. Any other pen in
the range #1...#31 may be omitted.
If HPGL_VERSION is "2" then plot -T hpgl will also be
affected by the environment variable HPGL_ASSIGN_COLORS. If
the value of this variable is "yes", then plot -T hpgl will not
be restricted to the palette specified in HPGL_PENS: it will
assign colors to "logical pens" in the range #1...#31, as
needed. The default value is "no" because other than color LaserJet
printers and DesignJet plotters, not many HP-GL/2 devices allow the
assignment of colors to logical pens.
plot -T tek, which produces output for a Tektronix terminal or
emulator, checks the TERM environment variable. If the value
of TERM is "xterm", "xterms", or "kterm", it is taken as a
sign that the current application is running in an X Window System
VT100 terminal emulator: an xterm. Before drawing graphics,
plot -T tek will emit an escape sequence that causes the terminal
emulator's auxiliary Tektronix window, which is normally hidden, to
pop up. After the graphics are drawn, an escape sequence that
returns control to the original VT100 window will be emitted. The
Tektronix window will remain on the screen.
If the value of TERM is "kermit", "ansi.sys", "ansissys",
"ansi.sysk", or "ansisysk", it is taken as a sign that the current
application is running in the VT100 terminal emulator provided by the
MS-DOS version of kermit. Before drawing graphics, plot -T
tek will emit an escape sequence that switches the terminal emulator to
Tektronix mode. Also, some of the Tektronix control codes emitted by
plot -T tek will be kermit-specific. There will be a
limited amount of color support, which is not normally the case (the 16
ansi.sys colors will be supported). After drawing graphics,
plot -T tek will emit an escape sequence that returns the
emulator to VT100 mode. The key sequence `ALT minus' can be
employed manually within kermit to switch between the two modes.
pic2plot Programpic2plot is used for
The pic2plot program takes one or more files in the pic language,
and either displays the figures that they contain on an X Window
System display, or produces an output file containing the figures. Many
graphics file formats are supported.
The pic language is a `little language' that was developed at Bell Laboratories for creating box-and-arrow diagrams of the kind frequently found in technical papers and textbooks. A directory containing documentation on the pic language is distributed along with the plotting utilities. On most systems it is installed as `/usr/share/pic2plot' or `/usr/local/share/pic2plot'. The directory includes Brian Kernighan's original technical report on the language, Eric Raymond's tutorial on the GNU implementation, and some sample pic macros contributed by W. Richard Stevens.
The pic language was originally designed to work with the troff
document formatter. In that context it is read by a translator called
pic, or its GNU counterpart gpic. Since extensive
documentation on pic and gpic is available, this section
simply gives an example of an input file, and mentions some extra
features supported by pic2plot.
A pic file contains one or more figures, each of the box-and-arrow type. Each figure is begun by a line reading .PS, and ended by a line reading .PE. Lines that are not contained in a .PS....PE pair are ignored. Each figure is built from geometrical objects, such as rectangular boxes, circles, ellipses, quarter circles ("arcs"), polygonal lines, and splines. Arcs, polygonal lines, and spline may be equipped with arrowheads. Any object may be labeled with text.
Objects are usually positioned not by specifying their positions in absolute coordinates, but rather by specifying their positions relative to other, previously drawn objects. The following figure is an example.
.PS box "START"; arrow; circle dashed filled; arrow circle diam 2 thickness 3 "This is a" "big, thick" "circle" dashed; up arrow from top of last circle; ellipse "loopback" dashed arrow dotted from left of last ellipse to top of last box arc cw radius 1/2 from top of last ellipse; arrow box "END" .PE
If you put this example in a file and run `pic2plot -T X' on the
file, a window containing the figure will be popped up on your X
display. Similarly, if you run `pic2plot -T ps' on the file, a
Postscript file containing the figure will be written to standard
output. The Postscript file may be edited with the idraw drawing
editor. Other graphics formats such as PNM format, pseudo-GIF format,
or Fig format (which is editable with the xfig drawing editor)
may be obtained similarly. You would use the options `-T pnm',
`-T gif', and `-T fig', respectively.
The above example illustrates some of the features of the pic language. By default, successive objects are drawn so as to touch each other. The drawing proceeds in a certain direction, which by default is left-to-right. The `up' command changes this direction to bottom-to-top, so that the next object (the arrow extending from the top of the big circle) will point upward rather than to the right.
Objects have sizes and other attributes, which may be set globally, or specified on a per-object basis. For example, the diameter of a circle may be specified, or the radius of an arc. An arc may be oriented clockwise rather than counterclockwise by specifying the `cw' attribute. The line style of most objects may be altered by specifying the `dashed' or `dotted' attribute. Also, any object may be labeled, by specifying one or more text strings as attributes. A text string may contain escape sequences that shift the font, append subscripts or superscripts, or include non-ASCII characters and mathematical symbols. See section Text string format and escape sequences.
Most sizes and positions are expressed in terms of `virtual inches'.
The use of virtual inches is peculiar to pic2plot. The graphics
display used by pic2plot, i.e., its drawing region, is defined to
be a square, 8 virtual inches wide and 8 virtual inches high.
If the page size for the output file is the "letter" size, which is the
default for Postscript output, virtual inches will the same as real
inches. But a different page size may be specified; for example, by
using the `--page-size a4' option. If so, a virtual inch will
simply equal one-eighth of the width of the graphics display.
By default, each figure is centered in the graphics display. You may turn off centering, so that you can use absolute coordinates, by using the `-n' option. For example, a figure consisting only of the object `arrow from (8,8) to (4,4)' will be positioned in the absence of centering so that the tip of the arrow is at the center of the display. Its tail will be at the upper right corner.
The thickness of lines is not specified in terms of virtual inches. For
compatibility with gpic, it is measured in terms of virtual
points. The example above, which specifies the `thickness'
attribute of one of the objects, illustrates this. There are 72
virtual points per virtual inch.
If there is more than one figure to be displayed, they will appear in different X windows, or on successive pages of the output file. Some output formats (such as PNM, pseudo-GIF, Il