TEX and graphics — the psfig package

How do you include figures and diagrams in TEX documents? In traditional publishing you’d probably reserve some space with a \vbox and paste in a carefully handdrawn, photoreduced, cropped illustration. But this is 1988 and Desktop Publishing is all the rage, so you want to do everything electronically. And you can’t help feeling rather envious of those people with Pagemaker and its friends who seem to be able to do this sort of thing at the click of a mouse button. After all, aren’t we TEX users supposed to be at the leading edge of electronic publishing? How come the Macintosh people can do it and we can’t? Well, the simple answer is just one word — PostScript. (Wake up, Malcolm!) If you have a PostScript device all the software you need for scaling, translating, and clipping your graphics is actually present in the printer — all you have to do is to invoke these functions with the right parameters. This is what the psfig package achieves automatically. If you don’t have a PostScript printer or typesetter for your TEX output — get one!

psfig originates from the University of Pennsylvania and was advertised in TEXhax early last year. It consists of a set of TEX macros that you can \input at the start of a Plain TEX job or declare as a LaTEX style option. psfig assumes that your diagrams exist as separate PostScript files on the system you use for TEXing. This lets you prepare your figures using whatever software you might care to use, provided that the end result is a file of PostScript. At Daresbury there is widespread use of the ghost-80 graphics package from ukaea Culham, and also sas-graph, which can both generate PostScript, and there are tricks for capturing PostScript output from MacDraw and other graphics programs running on PCs. psfig also likes your PostScript file to have a “bounding box” comment near the beginning. This tells psfig the ‘natural’ size of the PostScript figure — i.e. the coordinates of the bottom left and upper right corners of the figure in the initial PostScript coordinate frame. If the software used to create the figure does not generate a suitable bounding box comment you can edit one in by hand or supply the information when you tell TEX to place the figure.

Suppose you have an picture in the file mypic.ps and you want it centred horizontally and scaled to be just 3 inches high. A simple way to achieve this is to say

                                             \centerline{\psfig{figure=mypic.ps,height=3in}}

The \psfig macro reads and parses the lines of the mypic.ps file looking for its bounding box comment. This enables it to compute the desired width of the figure (keeping its aspect ratio constant) and to reserve a \vbox of exactly the right size. Within the \vbox psfig inserts \special control sequences which propagate scaling information and the name of the included PostScript file to the dvi file.

More sophisticated effects can be achieved with further arguments in the \psfig call. These include: ⋆ overriding the figure’s bounding box comment; ⋆ anamorphic scaling of the figure by giving both a

                                                 width= and a height= argument;

⋆ specifying explicitly the size of the \vbox that TEX reserves for the figure. This can be used to overlap figures and text, for example;

⋆ clipping the figure to an explicit bounding box. This could be used to extract just a part of a larger figure;

⋆ a draft mode where space is reserved for figures but the figures are suppressed from the output; ⋆ inclusion of a PostScript prologue file such as the notorious LaserPrep procedures needed for the correct interpretation of MacDraw, Mac-Chart, etc., output.

Portrait of the author on a windy day

The picture at left originates from the following PostScript fragment. It is 6 inches square.

                                                %%BoundingBox: 72 216 504 648
                                                72 72 scale
                                                /picstr 64 string def
                                                /imageshow {image showpage}def
                                                1 3 translate 6 6 scale
                                                128 128 8
                                                [128 0 0 128 0 0]
                                                {currentfile picstr readhexstring pop}
                                                imageshow
                                                967B8D9AA3A7B9B9B9B077614B343027
                                                27303D42463D3D343434343434302C2C
                                                % 1020 lines of hex digits omitted
                                                534B5358585358585353585861535861
                                                5858615C5C535C585C61655C5C61615C

Mapping the original picture (left) into the TEX page (right)

psfig requires surprisingly little support from a dvi to PostScript device driver. Essentially just two \specials are needed: one assumes that its argument is a fragment of PostScript to be propagated unchanged to the output, and the second assumes that its argument is the name of a file of PostScript which is to be included, also unmodified, in the output. The first type of \special is used to establish the PostScript environment (principally the current transformation matrix) in which the PostScript included by the second \special is executed. The work of transforming the original figure is done by the graphic transformation machinery in the printer when the output is printed. This is in distinct contrast to the code needed in, say, a dvi to LN03 device driver to achieve the same effect, and exemplifies the power and generality of the PostScript language.

To sum up, the psfig package is a practical way of integrating figures with TEX documents. Figures can be originated using any software package that can output PostScript. It requires only elementary device driver support for \specials. We have found it quite adequate for scientific papers and technical manuals requiring, for example, graphs of experimental data or schematic diagrams. It’s tolerably simple to use and works quite nicely with the LaTEX figure environment. Of course, psfig is firmly in the PostScript world. The LaTEX picture environment and the PicTEX package are device independent but the former supports only a limited range of vector orientations and circle diameters and the latter, though general, is restricted to relatively simple line graphics if TEX’s memory capacity is not to be exceeded. Under unix, tpic does for TEX what pic and its friends do for troff, but appears to be available only to licencees of at&t’s ditroff typesetting software. The TEXtyl system avoids overloading TEX by passing graphics primitives transparently in \specials and relying on a dvi postprocessor to expand them into a (large) \special-free dvi file. But for my money Post-Script is really the only choice today if you must have integrated text and graphics.

David Brightly