plot2ps is a utility for converting Unix plot files into postscript. The plot2ps utility reads plotting commands from named files or the standard input and writes postscript to the standard output. You can then print the postscript output on a printer, or edit it using the idraw graphics editor. You can also easily include the output in LaTeX documents using dvi2ps and the LaTeX command psfig.
Why is this useful? The plot file format is a commonly supported format for producing graphics on Unix systems. To produces figures for publication you might need to take these graphics and label them to make figures. This can be done using plot2ps and the idraw editor, an interactive `what you see is what you get' graphics editor. Last, dvi2ps makes it easy to include these figures in LaTeX documents. All of these steps are discussed in the following sections, followed by a discussion of the plot file format and the plot library functions.
plot2ps is a relatively simple utility in that there are few command line options to choose from. The Unix plot file format does not contain methods for specifying font or font size, so you must specify these things with options. There are no other options for controlling the picture.
The Unix plot file format is machine dependent on the byte order of unformatted, signed, two byte integer coordinates contained in plot commands. The `-high-byte-first' or `-low-byte-first' option specifies this order explicitly. plot2ps attempts to determine the byte order from commands early in the plot file, but the method is heuristic and is not foolproof. Several standard plot sizes specified by the open command are used to recognize byte order by plot2ps. If these sizes are recognized in byte reversed order, plot2ps adjusts accordingly. These sizes include 504x504, 2048x2048 (versatek plotters), 2100x2100, 3120x3120(tektronics 4010 terminals) and 4096x4096 (gsi 300 terminals).
The remaining command line options may be used specify an alternate postscript prologue and to print the licensing information.
Input plot files names may be specified anywhere on the command line. If no file names are specified, or the name `-' is specified, the standard input is read for plotting instructions. Only the font or font size options which precede a file name will affect the text for that file.
To produce a plot of data arranged in ordered pairs of x and y coordinates in an ASCII file, you can use:
graph <asciiDataFile | plot2ps | lpr -Plw
To create a simple postscript figure you can use:
echo 0 0 1 1 2 0 | spline | graph | plot2ps > test.ps
To edit the plot:
idraw test.ps
To use the previewer to look at the plot:
xps -c A4 test.ps
This is an example of LaTeX code which places the figure generated in the previous example in a page of text.
\documentstyle[]{article}
\input{psfig}
\begin{document}
\title{Title of the article.}
\author{The Author's name}
\maketitle
This is an example of how to include postscript figures in LaTeX documents.
\begin{figure}[h]
\centerline{\psfig{figure=test.ps,height=3in}}
\caption{Here is a description of the figure which will appear below it.}
\end{figure}
Note that the above figure was included using dvi2ps.
\end{document}
If the above LaTeX code is contained in a file called `mytext.tex'
you can use the commands
latex mytext
dvi2ps <mytext.dvi >mytext.ps
lpr -Plw mytext.ps
to format and print the example text.
psfig is a LaTeX command used to insert a postscript figure into a document.
psfig can be used to insert plot2ps generated postscript into a LaTeX document. The placement of the psfig command tells LaTeX where in the document to place the postscript, and arguments to the command give the name of the file containing the postscript, and the desired size of the figure. Arguments are separated by commas or blanks, and are of the form `keyword=value'. The following is a list of valid arguments for the psfig command:
atend.pl is a perl script which moves the bounding box comment from the trailer to the header. Although either is legal, most document perparation software, such as psfig, will only accept bounding box comments in the header. If you use psfig and the bbox option togeather, run atend.pl on the output of plot2ps before importing the graphics using psfig.
The dvi2ps utility mentioned previously is used convert dvi files generated by LaTeX into post-script. It also has support for inclusion of postscript figures into LaTeX documents. It is available via anonymous ftp from `june.cs.washington.edu' (128.95.1.4). Look for `tex/w_dvi2ps.tar.Z'.
The idraw utility mentioned previously is an interactive graphics editor which is distributed with InterViews. InterViews is available via anonymous ftp from `interviews.stanford.edu' (36.22.0.175) in the file `InterViews/2.5.tar.Z'.
The xps utility mentioned previously is a postscript previewer for X windows written by Crispin Goswell. xps is available via anonymous ftp from `ai.toronto.edu' (128.100.1.65) in `pub/X/xps.tar.Z' and from `qed.rice.edu' (128.42.4.38) in the file `pub/x11/xps.tar.Z'.
The original distribution of xps is available via anonymous ftp from `uunet.uu.net' (192.48.96.2) in the directory `comp.sources.unix/volume12/postscript'. You can also find xps on the host `j.cc.purdue.edu' (128.210.9.2) in the directory `comp.sources.Unix/volume12' in the files `v12i050.Z' through `v12i067.Z'. Patches for xps are also available via anonymous ftp from both `uunet.uu.net' in the directory mentioned above and `z.andrew.cmu.edu' (128.2.30.8) in the directory `psdiffs'.
Ghostscript is another postscript previewer supporting X windows. Version 1.2 does not yet support all of the features used by plot2ps. It is available via anonymous ftp from `prep.ai.mit.edu' (18.71.0.38) - Look for `pub/gnu/ghostscript-1.2.tar.Z'.
Many thanks to Richard Stallman for his helpful discussions of the program and documentation. Also, thanks to John Interrante for generously providing the postscript prologue and helpful comments on the program.
Libps is a library of Unix plot functions for drawing graphic object using postscript. Before drawing any objects or using any of the other functions, a program should call openpl. Before exiting and after all other libps calls a program should call closepl.
int alabel (char x_justify, char y_justify, char *label);
alabel takes three arguments x_justify, y_justify, and label and places the label according to the x and y axis adjustments specified in x_justify and y_justify respectively. x_justify is a character containing either `l', `c', or `r' for left, center or right justified with respect to the current x coordinate. y_justify is a character containing either `b', `c', or `t' for placing the bottom center or top of the label even with the current y coordinate. *label is a string containing the label. The current point is moved to follow the end of the text.
See section fontname on how to change the default font. See section fontsize on how to change the font size.
int arc (int x, int y, int x0, int y0, int x1, int y1)
arc takes six integer arguments specifying the coordinates of the center (x, y), beginning (x1, y1), and ending (x, y) of a circular arc. The current point becomes (x, y).
int circle (int x, int y, int r)
circle takes three integer arguments specifying the center (x, y) of the circle and its radius (r). The current point becomes (x, y).
int closepl ()
closepl takes no arguments. It merely outputs the postscript trailer containing a showpage command.
int color (int red, int green, int blue);
color sets the foreground color of all the following objects. The arguments red, green and blue indicate the intensity of red, green and blue components of the foreground color respectively. Each is a unsigned integer specifying an intensity in the range from 0 to 0xFFFF. A value of (0, 0, 0) represents black and a value of (0xFFFF, 0xFFFF, 0xFFFF) indicates white.
int cont (int x, int y)
cont takes two integer arguments specifying the coordinate (x, y) for the continuation of a line. This draws a line segment from the current point to the point (x, y). The current point then becomes (x, y).
int erase ()
erase normally erases all the graphics from the display before a plot is viewed. Since we start off with a blank page in postscript and idraw this function does nothing.
int fill (int level);
fill sets the intensity of the filler for closed paths. The argument level indicates the grey level of the fill pattern. It's value ranges from 1 to 0xFFFF. A value of 1 represents black and a value of 0xFFFF indicates white. A value of 0 represents no fill, or transparent.
int fontname (char *font_name);
fontname takes a single string argument, font_name, specifying the name of the font to be used for following text. The laser writer builtin fonts are supported:
courier-bold
courier-boldoblique
courier-oblique
courier
helvetica-bold
helvetica-boldoblique
helvetica-oblique
helvetica
symbol
times-bold
times-bolditalic
times-italic
times-roman
int fontsize (int size);
fontsize takes a single integer argument size in printer's points (1/72 inch) and sets the font size accordingly.
int label (char *s)
label takes a single string argument s and draws the text contained in s at the most recently used coordinate in the current font. By default the text is left justified and centered vertically with respect to the current coordinate.
int line (int x1, int y1, int x2, int y2)
line takes four integer arguments specifying the beginning (x1, y1) and ending (x2, y2) points of a line. The current point becomes (x2, y2).
See section linemod for how to specify the style or pattern of line.
int linemod (char *s)
linemod takes a single string arguement s containing the name of the line style desired. The names supported are longdashed, disconnected, dotdashed, dotted, solid and shortdashed. These correspond to the following patterns:
solid ----------------
longdashed -------
disconnected -
dotdashed ----------- -
dotted - - - - - - - -
shortdashed --
int move (int x, int y)
move takes two integer arguments specifying the coordinate (x, y) for the beginning of a new line. This is equivalent to lifting the pen on a plotter and moving it to a new position without drawing any line. The current point becomes (x, y).
int openpl ()
openpl normally opens the device. For postscript we just print out the postscript prologue. The following global variables defined in openpl specify what prologue is written to the output.
user_has_prologue is a flag. If it is non-zero then the open routine should output the user specified prologue contained in the file specified in the string users_prologue.
users_prologue is a string containing the file name for any user specified postscript prologue. This file is a substitute for the default prologue.
int point (int x, int y)
point takes a pair of integer arguments specifying the coordinate (x, y) for a single point. The current point then becomes (x, y).
int rotate (int w, int h, int angle);
rotate takes three integer arguments. The last argument, angle, specifies the angle in degrees counter-clockwise from the x (horizontal) axis following text. w and h are not currently used, but may be used in future.
int space (int x0, int y0, int x1, int y1)
space takes two pair of integers arguments specifying the lower, left-hand and upper, right-hand limits of the range of plot coordinates. The scaling of input to output coordinate conversion is adjusted to fit these ranges into the page. Note however that if the ranges of x and y coordinates are different the smallest scaling of the two is used to avoid affecting the aspect ratio of the plot. This means that although the plot is scaled to fit on the page, the axes are not streched with respect to each other.
The Unix plot file is a set of plotting commands and data. Each command is a single ascii character indicating which operation is to be performed. The data following a command is either a newline terminated ascii string or several signed, two byte integers in binary format. For example, the command to move the current point to the coordinate (3,5) would be m\000\003\000\005.
Note that the byte order of the binary representation of the signed, two byte integers is machine dependent, so on some machines, this command might appear as m\003\000\005\000. plot2ps tries to guess the byte order from the arguments to the openpl command and adjust the order accordingly.
The following table lists each single character commands followed by the name of the corresponding libps function called to handle the data and a description of the command and data.