Labelling graphics

“Technical” graphics (such as graphs and diagrams) are often labelled with quite complex mathematical expressions: there are few drawing or graphing tools that can do such things (the honourable exception being MetaPost, which allows you to program the labels, in (La)TeX, in the middle of specifying your graphic).

Placing “labels” on graphics produced by all those other tools is what we discuss here. (Note that the term “label” should be liberally interpreted; many of the techniques were designed for use when applying labels to figures, but they may be used equally well to draw funny faces on a figure … or anything.

The time-honoured psfrag package can help, if your image is included as an (encapsulated) PostScript file. Place an unique text in your graphic, using the normal text features of your tool, and you can ask psfrag to replace the text with arbitrary (La)TeX material. Psfrag’s “operative” command is \psfrag{<Orig text>}{<Repl text>}, which instructs the system to replace the original (“unique”) text with the TeX-typeset replacement text. Optional arguments permit adjustment of position, scale and rotation; full details may be found in pfgguide in the distribution.

Since psfrag works in terms of (encapsulated) PostScript files, it needs extra work for use with pdfLaTeX. Two techniques are available, using pst-pdf package in a mode designed to do this work; and using pdfrack.

The Pst-pdf package can support this “extra work” usage. In fact, the pst-pdf support package auto-pst-pdf offers a configuration setting precisely for use with psfrag.

If you have the “right” environment (see below), you could try the pdfrack script bundle. The script aims to cut each figure out of your source, using it to produce a small LaTeX file with nothing but the figure inclusion commands. Each of these figure files is then processed to PostScript, compiled using the \psfrag commands, and the resulting output converted to PDF again.

Pdfrack is written to use the Unix Bourne shell (or equivalent); thus your environment needs to be a Unix-based system, or some equivalent such as cygwin under windows. (What is more, pdfrack’s author is rather disparaging about his package; the present author has never tried it.)

The psfragx package goes one step further than psfrag: it provides a means whereby you can put the psfrag commands into the preamble of your EPS file itself. Psfrag has such a command itself, but deprecates it; psfragx has cleaned up the facility, and provides a script laprint for use with Matlab to produce appropriately tagged output. (In principle, other graphics applications could provide a similar facility, but apparently none does.)

Emacs users may find the embedded editor iTe a useful tool for placing labels: it’s a (La)TeX-oriented graphical editor written in Emacs Lisp. You create iteblock environments containing graphics and text, and may then invoke iTe to arrange the elements relative to one another.

Another useful approach is overpic, which overlays a picture environment on a graphic included by use of \includegraphics. This treatment lends itself to ready placement of texts and the like on top of a graphic. The package can draw a grid for planning your “attack”; the distribution comes with simple examples.

The lpic package is somewhat similar to overpic; it defines an environment lpic (which places your graphic for you): within the environment you may use the command \lbl to position LaTeX material at appropriate places over the graphic.

Pinlabel is another package whose author thought in the same sort of way as that of overpic; the documentation explains in detail how to plan your “labelling attack” — in this case by loading your figure into a viewer and taking measurements from it. (The package discusses direct use of ghostscript as well as customised viewers such as gsview or gv.)

Pstricks can of course do everything that overpic, lpic or pinlabel can, with all the flexibility of PostScript programming that it offers. This capability is exemplified by the pst-layout package, which seems to be a superset of both overpic and lpic.

Similarly, pgf/TikZ has all the power needed, but no explicit package has been released.

The pstricks web site has a page with several examples of labelling which will get you started; if pstricks is an option for you, this route is worth a try.

The confident user may, of course, do the whole job in a picture environment which itself includes the graphic. I would recommend overpic or the pstricks approach, but such things are plainly little more than a convenience over what is achievable with the do-it-yourself approach.

FAQ ID: Q-labelfig