Scaling and including PostScript graphics is a breeze--if the PostScript file is correctly formed. Even if it is not, however, the file can usually be accommodated with just a little more work. The most important feature of a good PostScript file--from the standpoint of including it in another document--is an accurate bounding box comment.
Every well-formed PostScript file has a comment describing where on the page the graphic is located, and how big that graphic is. This information is given in terms of the lower left and upper right corners of a box just enclosing the graphic, and is thus referred to as a bounding box. These coordinates are given in PostScript units (there are precisely 72 PostScript units to the inch) with respect to the lower left corner of the sheet of paper.
To see if a PostScript file has a bounding box comment, just look at the first few lines of the file. (PostScript is standard ASCII, so you can use any text editor to do this.) If within the first few dozen lines there is a line of the form
%%BoundingBox: 0 1 2 3
(with any numbers), chances are very good that the file is Encapsulated PostScript and will work easily with dvips. If the file contains instead a line like
%%BoundingBox: (atend)
the file is still probably Encapsulated PostScript, but the bounding box (that dvips needs to position the graphic) is at the end of the file and should be moved to the position of the line above. This can be done with that same text editor, or with a simple Perl script.
If the document lacks a bounding box altogether, one can easily be added. Simply print the file. Now, take a ruler, and make the following measurements. All measurements should be in PostScript units, so measure it in inches and multiply by 72. Alternatively, the `bbfig' program distributed with dvips in the `contrib' directory can be used to automate this process.
From the left edge of the paper to the leftmost mark on the paper is llx, the first number. From the bottom edge of the paper to the bottommost mark on the paper is lly, the second number. From the left edge of the paper to the rightmost mark on the paper is urx, the third number. The fourth and final number, ury, is the distance from the bottom of the page to the uppermost mark on the paper.
Now, add a comment of the following form as the second line of the document. (The first line should already be a line starting with the two characters `%!'; if it is not, the file probably isn't PostScript.)
%%BoundingBox: llx lly urx ury
Or, if you don't want to modify the file, you can simply write these numbers down in a convenient place and use them when you import the graphic.
If the document does not have such a bounding box, or if the bounding box is given at the end of the document, please complain to the authors of the software package that generated the file; without such a line, including PostScript graphics can be tedious.
Now you are ready to include the graphic into a TeX file. Simply add to the top of your TeX file a line like
\input epsf
(or, if your document is in LaTeX or SliTeX, add the `epsf' style option, as was done to the following line).
\documentstyle[12pt,epsf]{article}
This only needs to be done once, no matter how many figures you plan to include. Now, at the point you want to include the file, enter a line such as
\epsffile{foo.ps}
If you are using LaTeX or SliTeX, you may need to add a `\leavevmode' command immediately before the `\epsffile' command to get certain environments to work correctly. If your file did not (or does not currently) have a bounding box comment, you should supply those numbers you wrote down as in the following example:
\epsffile[100 100 500 500]{foo.ps}
(in the same order they would have been in a normal bounding box comment). Now, save your changes and run TeX and dvips; the output should have your graphic positioned at precisely the point you indicated, with the proper amount of space reserved.
The effect of the `epsffile' macro is to typeset the figure as a TeX `vbox' at the point of the page that the command is executed. By default, the graphic will have its `natural' width (namely, the width of its bounding box). The TeX box will have depth zero and a `natural' height. The graphic will be scaled by any `dvi' magnification in effect at the time.
Any PostScript graphics included by any method in this document (except `bop-hook' and its ilk) are scaled by the current `dvi' magnification. For graphics included with `epsffile' where the size is given in TeX dimensions, this scaling will produce the correct, or expected, results. For compatibility with old PostScript drivers, it is possible to turn this scaling off with the following TeX command:
\special{! /magscale false def}
Use of this command is not recommended because it will make the `epsffile' graphics the wrong size if global magnification is used in a `dvi' document, and it will cause any PostScript graphics to appear improperly scaled and out of position if a `dvi' to `dvi' program is used to scale or otherwise modify the document.
You can enlarge or reduce the figure by putting
\epsfxsize=dimen
right before the call to `epsffile'. Then the width of the TeX box will be dimen and its' height will be scaled proportionately. Alternatively you can force the vertical size to a particular size with
\epsfysize=dimen
in which case the height will be set and the width will be scaled proportionally. If you set both, the aspect ratio of the included graphic will be distorted but both size specifications will be honored.
By default, clipping is disabled for included EPSF images. This is because clipping to the bounding box dimensions often cuts off a small portion of the figure, due to slightly inaccurate bounding box arguments. The problem might be subtle; lines around the boundary of the image might be half their intended width, or the tops or bottoms of some text annotations might be sliced off. If you want to turn clipping on, just use the command
\epsfclipon
and to turn clipping back off, use
\epsfclipoff
A more general facility for sizing is available by defining the `epsfsize' macro. You can redefine this macro to do almost anything. This TeX macro is passed two parameters by `epsffile'. The first parameter is the natural horizontal size of the PostScript graphic, and the second parameter is the natural vertical size. This macro is responsible for returning the desired horizontal size of the graph (the same as assigning `epsfxsize' above).
In the definitions given below, only the body is given; it should be inserted in
\def\epsfsize#1#2{body}
Some common definitions are:
If you want TeX to report the size of the figure as a message on your terminal when it processes each figure, give the command
\epsfverbosetrue
Often in order to get a particular graphic file to work, a certain header file might need to be sent first. Sometimes this is even desirable, since the size of the header macros can dominate the size of certain PostScript graphics files. The dvips program provides support for this with the `header=' special command. For instance, to ensure that `foo.ps' gets downloaded as part of the header material, the following command should be added to the TeX file:
\special{header=foo.ps}
The dictionary stack will be at the `userdict' level when these header files are included.
For these and all other header files (including the headers required by dvips itself and any downloaded fonts), the printer VM budget is debited by some value. If the header file has, in its first 1024 bytes, a line of the form
%%VMusage: min max
then the maximum value is used. If it doesn't, then the total size of the header file in bytes is used as an approximation of the memory requirements.
For simple graphics, or just for experimentation, literal PostScript graphics can be included. Simply use a `\special' beginning with a double quote (`"') (no closing `"').
For instance, the following (simple) graphic: was created by typing:
\vbox to 100bp{\vss % a bp is the same as a PostScript unit \special{" newpath 0 0 moveto 100 100 lineto 394 0 lineto closepath gsave 0.8 setgray fill grestore stroke}}
(You are responsible for leaving space for such literal graphics.) Literal graphics are discouraged because of their nonportability.
Similarly, you can define your own macros for use in such literal graphics through the use of literal macros. Literal macros are defined just like literal graphics, only you begin the special with an exclamation point instead of a double quote. These literal macros are included as part of the header material in a special dictionary called `SDict'. This dictionary is the first one on the PostScript dictionary stack when any PostScript graphic is included, whether by literal inclusion or through the `epsffile' macros.
There are other ways to include graphics with dvips. One is to use an existing package, such as `emtex', `psfig', `tpic', or `METAPOST', all of which `dvips' supports.
Other facilities are available for historical reasons, but their use is discouraged, in hope that some `sane' form of PostScript inclusion shall become standard. The main advantage of the `epsffile' macros is that they can be adapted for whatever form of special eventually becomes standard, and thus only minor modifications to that one file need to be made, rather than revising an entire library of TeX documents.
Most of these specials use a flexible key and value scheme:
\special{psfile=filename.ps[key=value]*}
This will download the PostScript file called `filename.ps' such that the current point will be the origin of the PostScript coordinate system. The optional key/value assignments allow you to specify transformations on the PostScript.
The possible keys are:
The dimension parameters are all given in PostScript units. The `hscale' and `vscale' are given in non-dimensioned percentage units, and the rotation value is specified in degrees. Thus
\special{psfile=foo.ps hoffset=72 hscale=90 vscale=90}
will shift the graphics produced by file `foo.ps' right by one inch and will draw it at 0.9 times normal size. Offsets are given relative to the point of the special command, and are unaffected by scaling or rotation. Rotation is counterclockwise about the origin. The order of operations is to rotate the figure, scale it, then offset it.
For compatibility with older PostScript drivers, it is possible to change the units that `hscale' and `vscale' are given in. This can be done by redefining `@scaleunit' in `SDict' by a TeX command such as
\special{! /@scaleunit 1 def}
The `@scaleunit' variable, which is by default 100, is what `hscale' and `vscale' are divided by to yield an absolute scale factor.
All of the methods for including graphics we have described so far enclose the graphic in a PostScript save/restore pair, guaranteeing that the figure will have no effect on the rest of the document. Another type of special command allows literal PostScript instructions to be inserted without enclosing them in this protective shield; users of this feature are supposed to understand what they are doing (and they shouldn't change the PostScript graphics state unless they are willing to take the consequences). This command can take many forms, because it has had a torturous history; any of the following will work:
\special{ps:text} \special{ps::text} \special{ps::[begin]text} \special{ps::[end]text}
(with longer forms taking precedence over shorter forms, when they are used). Note that `ps::' and `ps::[end]' do not do any positioning, so they can be used to continue PostScript literals started with `ps:' or `ps::[begin]'. There is also the command
\special{ps: plotfile filename}
which will copy the commands from filename verbatim into the output (but omitting lines that begin with %). An example of the proper use of literal specials can be found in the file `rotate.tex' which makes it easy to typeset text turned 90 degrees.
To finish off this section, the following examples are presented without explanation:
\def\rotninety{\special{ps:currentpoint currentpoint translate 90 rotate neg exch neg exch translate}}\font\huge=cmbx10 at 14.4truept \setbox0=\hbox to0pt{\huge A\hss}\vskip16truept\centerline{\copy0 \special{ps:gsave}\rotninety\copy0\rotninety\copy0\rotninety \box0\special{ps:grestore}}\vskip16truept
\vbox to 2truein{\special{ps:gsave 0.3 setgray}\hrule height 2in width\hsize\vskip-2in\special{ps:grestore}\font\big=cminch\big \vss\special{ps:gsave 1 setgray}\vbox to 0pt{\vskip2pt \line{\hss\hskip4pt NEAT\hss}\vss}\special{ps:0 setgray}% \hbox{\raise2pt\line{\hss NEAT\hss}\special{ps:grestore}}\vss}
Some caveats are in order when using the above forms. Make sure that each `gsave' on a page is matched with a `grestore' on the same page. Do not use `save' or `restore'. Use of these macros can interact with the PostScript generated by dvips if care is not taken; try to understand what the above macros are doing before writing your own. The `\rotninety' macro especially has a useful trick that appears again and again.
PostScript is an excellent page description language--but it does tend to be rather verbose. Compressing PostScript graphics files can often reduce them by more than a factor of five. For this reason, if the filename parameter to one of the graphics inclusion techniques starts with a backtick (``'), the filename is instead interpreted as a command to execute that will send the actual file to standard output. Thus,
\special{psfile="`zcat foo.ps.Z"}
will include the uncompressed version of `foo.ps'. Since such a command is not accessible to TeX, if you use this facility with the `EPSF' macros, you need to supply the bounding box parameter yourself, as in
\epsffile[72 72 540 720]{"`zcat screendump.ps.Z"}
to include `screendump.ps'. Of course, the commands to be executed can be anything, including using a file conversion utility such as `tek2ps' or whatever is appropriate.
This extension is not portable to other DVI-to-PostScript translators.
Go to the first, previous, next, last section, table of contents.