[ Back to the main page on labels and TEX ]

Importing EPS files

Here we'll see how to produce suitable PostScript files from label files, then incorporate them along with the figure file into a single PostScript file. This method is a variation of a technique suggested by Adobe Systems for assembling into one figure almost any collection of one-page PostScript figures.

In brief

First make an eps file from each of your label tex files. Download this template as a .ps file into which you will embed your original figure file and all these label .eps files. Make changes at locations (A), (B), (C), (D), (E). If you get confused, read on.

Outline

Start with

and follow these steps:

Some additional points:

Bounding boxes

In order to be incorporated into a TEX file, your figure file must draw on no more than one page, and have a bounding box declaration in it.

A bounding box declaration is a line occurring near the beginning of the file (usually its second line), looking something like this:

%%BoundingBox: 100 150 400 200

It is not actually part of the PostScript code producing the figure, but a special kind of comment which allows programs other than PostScript to manipulate the figure. The numbers here must be integers. They amount to pairs of coordinates, the first two of the point at the lower left, and the second two of the upper right, of a box which bounds the figure in the sense that all of the figure is contained in the box. The coordinate system here is the default PostScript coordinate system, which place the origin at the lower left of the page, and in which the unit of length is an Adobe point or 1/72 of an inch. (In exceptional cases the initial bounding box declaration may refer to the end of the file for the true declaration.) The figure above, for example, is located on the page like this:

If the figure file does not have a bounding box, you can put one in yourself after reproducing the figure and deciding yourself where a bounding box should be located. Occasionally there will be a bounding box declaration in the figure file but it will be far too large (say, a whole page), in which you case you should modify it.

The conditions imposed here (one page, bounding box) are the minimal requirements that a PostScript file must satisfy in order to be an EPS (Encapsulated PostScript) file file. Full qualification as an EPS file imposes a number of other conditions as well, but in practice you can ignore them. You can see here the text of a complete EPS file (which draws a graph on a simple grid). Its first two lines are 

%!PS-Adobe-3.0 EPSF-3.0
%%BoundingBox: 0 0 159 87

so that its figure is no more than 159 points wide and 87 points high. In some situations the contents of the first line are also important, but usually you don't have to worry about it.

The essence of an Encapsulated PostScript file is that it be ... well, encapsulated. In other words that it be somehow a compact, well insulated figure, which sets up its own graphics environment and cleans up after itself, and also tells the outside world how big it is.

At any rate, if you can view your file as you want to before putting the labels in, you ought to be able to add the labels without difficulty.

Making the file

You want each of your label files to produce just a label, no extra space or formatting or page numbers. In plain this can be accomplished easily, by beginning your file with

\nopagenumbers
\parindent=0pt
\parskip=0pt

If your label is actually rather large, you will probably want to set the \hsize as well, in order to limit the width of your text. Keep in mind, however, that the final output should not be more than one page long.

There are undoubtedly ways to deal with these problems in other versions of , but I suspect it's more work.

Making the files into EPS files

Once you have a TEX file which produces a small part of a page, the next step in the process is to produce PostScript versions of the labels from the .dvi file. There are probably several possible programs that do this, but I am going to add this as a requirement:

You must have the program dvips available on your system.

Dvips is a very fine program, written by Tom Rokicki (once a student, I believe, of Don Knuth) and easily available without cost. It converts .dvi files to .ps (PostScript) files. It can be installed on nearly all systems, and if you aren't using it already you probably should be. Normally it converts to a .ps file, but it has an option -E that converts a .dvi file of one page to an EPS file. This option must be used here, and with it the option -o which will produce an .eps file rather than send output to a printer. Here is an example of the correct usage:

dvips -E label.dvi -o label.eps

After using dvips on your label .dvi files, you will have a collection of label .eps files, in addition to the original figure file. Now the original problem is reduced to a more general one: How can you import or embed one EPS file into another, allowing yourself some control over where it is embedded?

Problems with fonts

You will not really have much control over the size or shape of your final output, because if the figure is embedded in a file it might be magnified or rotated or even sheared. Therefore:

Your version of dvips should use PostScript scalable fonts.

This is in fact not absolutely necessary, but if you don't use scalable fonts you'll often get weird pixelly characters in your labels.

Normal CM font: Scalable version:

Up until a while ago this was not an easy condition to satisfy, but the Blue Sky Research and Y&Y have now released their PostScript versions of the CM and AMS fonts for public distribution---for example through the American Mathematical Society. How to install them does not seem to be quite as well documented as it might be, but it is not an impossible task. One technical matter is that dvips should embed just the characters that your label uses into the .eps file, but this is the default behaviour in recent releases.

Embedding your labels

For every figure you import there will be two places where you have to enter something. In the first, you have to make an adjustment of cordinates. In the second, you must embed your figure files into the combined file. Take a look at where this is remarked on in the template. Most of the time, you will want to work on your labels and their embedding a bit before things are perfect. If your combined file is huge, this will be a nuisance. So while you are working out things you will just want to put in a PostScript line like

(label.eps) run

to have PostScript do the embedding. But when you are finished you must replace this place-holder by the full file label.eps.

Setting coordinates for the embedding

Just in front of the embedded copy of a figure or label file, you will probably have to write some PostScript to set up the coordinate system so the figure is embeded at the correct place. But of a very simple kind, usually effecting only suitable translations. The PostScript command translate shifts the origin of your coordinate system. As with almost all PostScript commands, the coordinates you want to translate by come first, like this:

72 72 translate

Since the units here are Adobe points, the effect of this is to move the origin of your coordinate system up one inch and one inch to the right, so that drawing something at the location (0, 0) after the translation will place it up and to the right of where it would have been drawn before the transformation.

Normally, you will want to embed a label at a point whose coordinates you know (or can figure out easily) relative to the lower left corner of the figure into which it is being embedded. Doing this will require some translations taking into account the bounding boxes of the label and the figure files. Suppose the bounding boxes are like this:

Figure file:

%%BoundingBox: llx0 lly0 urx0 ury0
Label file:
%%BoundingBox: llx lly urx ury

Suppose you want to place the label at the point with coordinates x y relative to the figure's lower left corner. Then the correct lines to put in the combined file just before you import the label are: 

llx0 lly0 translate
x y translate
-llx -lly translate

(All the symbols llx etc stand for numbers, of course.) You are not restricted to simple translations in the coordinate setup. There are in fact wide range of options, but they will require more sophisticated use of PostScript. Other coordinate adjustments you might do include

Almost anything is legitimate at this point which only uses the bounding box of the inclusion, as opposed to detailed knowledge of what the inclusion is.

Adjusting the label

It almost always takes some experimenting to get the label placed correctly in the figure, or in other words to get those numbers (x, y) correct. You can use either ghostview (UNIX) or GSView (other platforms) to help you out with this---open the original figure and notice that somewhere on the screen appears the coordinates of the cursor in Adobe coordinates. Note that the cursor location is in absolute coordinates in the figure fle. So if you decide to place the label at the point (x, y) your coordinate lines before the label will be 

x y translate
-llx -lly translate

The structure of the combined file

We must build a single EPS file which contains copies of the figure file and all the label EPS files, cemented together with a little PostScript code. It is not to difficult to figure out how to do this from scratch once you get the idea, if you understand some of the more arcane features of production PostScript. But in fact Adobe has told us exactly what to do in the book Programming the Display PostScript System with X. This file can be put together easily enough with your favourite word processor, but if you do a lot of this sort of thing you'll want to automate the construction. Even if you are going to use a tool to do it automatically, you'll probably want to read the next section to understand what's going on.

I will exhibit just below the outline of a file which you can use as a template for your combined file. You will have to add to it in a small number of places in any particular instance. In other words, this template contains the glue into which you have to stick your own figure and labels. You do not have to know more than a very small amount of PostScript in order to realize what to do, but a few remarks will probably help you understand what you are doing. (1) Lines beginning with a % are comments. (2) A line beginning with %% is a special kind of comment which is used by programs (or people) who want to do some sort of manipulation of PostScript files (as we are doing). The %! at the beginning of any PostScript program is a sort of magic indicator to the operating system. Your files will be sandwiched in the template between the lines 


BeginEPSF
...
EndEPSF

The things in the template you will have to add are (1) the overall bounding box and, for each file you want to embed, (2) the coordinate setup and (3) the file inclusion.

The template file itself

I have included here a template file for importing several figures into one. You can start the process by saving this file and then modifying it to make your final figure. In this file are distributed a number of comments indicating what is going on, and what you have to do is noted at (A), (B), (C), (D). I have reproduced a modified form of this template below with these comments put in colour. 


%!PS-Adobe-3.0 EPSF-3.0
%%BoundingBox: llx lly urx ury

% The bounding box above 
% should be the bounding box of the complete figure,
% usually that of the main figure.

%%Pages: 1

%%EndComments
%%BeginProlog

% This comment replaces
% a collection of definitions you don't need to see or understand.
% The point is to isolate each of the included files from each other.

%%EndProlog

%%Page: 1 1

/pagesave save def

BeginEPSF

% Make here whatever 
% coordinate changes you need to in order
% to arrange your figure file correctly.
% Normally you just leave this blank.

%%BeginDocument: [figure file name]

% Embed the figure file here.

%%EndDocument
EndEPSF

BeginEPSF

% Change coordinates to embed the first label.
% Normally you would put here a sequence
% llx0 lly0 translate
% where llx0 lly0 is the lower left corner of the figure
% x y translate
% x y is relative location of the label
% -llx -lly translate
% where llx lly is the lower left of the label

%%BeginDocument: [first label file name]

% Embed first label file.

%%EndDocument
EndEPSF

% Do the same for more labels if necessary.

pagesave restore showpage
%%EOF

Some examples

I have put a few extended examples here.

Automating the construction

You can do all this by hand, so to speak, but the process can be easily automated to some extent, say by a PERL script. Another point is each label produced by dvips will contain some {prolog files, usually tex.pro and texps.pro. They take up a fair amount of space, and should be replaced by a single copy at the beginning of the combined PostScript file. This too can be done automatically by PERL. Here are the two PERL scripts:

These are written for UNIX. Depending on your system, you may have to change the first line to locate the PERL executable. Type which perl to see what to put there instead of /bin/perl.

In the templates produced by the first script, places where you will probably want to add something are marked % Insert? so you can locate them easily.

Does it have to be so clumsy?

Adobe used to include in its UNIX distribution of Display PostScript a utility called import which did exactly what we want to do here: it allowed you to open an EPS file in a window, then import another one into it. You could perform translation, scaling, and rotation with a mouse. You could then save the enhanced figure as an EPS file. Terrific! But it doesn't seem to have been well supported---the C source code in the copy I got required some rewriting (ugh) and the program always seemed a bit erratic. Nonetheless it showed what can be done, at least in principle.

Why don't ghostview and GSView have similar options Import and Export?

References

Written by Bill Casselman.