## How To Embed UML in LaTeX

I finally found a way to encode a UML diagram inside a LaTeX document! I’ve been looking for something like this for some time now. Usually I resort to using an external tool that has EPS and PDF export, like Umlet or XFig (don’t laugh – XFig has an excellent vector output). It is not too convenient, though, to switch between writing an article (or a lecture) and editing a diagram. Plus, editing the diagram manually takes more time then just typing it in. So I was looking for some tool that would have the following qualities:

1. Textual
2. (Relatively) easy to use
3. Can be embedded directly into a LaTeX document (the text itself, not the image)
4. Support more then just class diagrams
5. High quality graphical output: Vector format (not raster), aligned, manhattan and step paths (I.e, squared arrows, like in the GOF book)
6. Does some of the layout work for you

I ruled out several posibilites. Cumbersome CASE tools, like Rational Rose et. al., were banned: They’re not textual, produce poor output and require too much work to produce a single diagram. Dot-based tools are textual and does all the layout for you, but do not support step paths and require some work to embed in a LaTeX file. Some LaTeX libs, like XyPic, produce amazing vector graphics, but are very difficult to master. However, this is not a ranting post. Solutions follow.

The trick that I found was to combine MetaUML with the Emp package. MetaUML withstand most of my standards: It’s textual, supports several UML diagrams, has all sorts of paths and alignments and produces high-quality vector graphics. It does some of the layout, using Metapost’s linear equations solver. It’s not as easy to use as Umlet or Dot – Metapost is, in a matter of fact, a programming language. However, if you’re in need of insering UML diagrams into an academic article, you can probably handle a few lines of code. The Emp package gives the final touch: It allows you to embed Metapost code (and hence, MetaUML) inside a LaTeX document, so you won’t have to juggle several files.

Here is how it’s done.

First, import the Emp package:

\usepackage{emp}

If you want to use PDFLaTeX, you have to add rules to handle Metapost files:

\ifx\pdftexversion\undefined \usepackage[dvips]{graphicx} \else \usepackage[pdftex]{graphicx} \DeclareGraphicsRule{*}{mps}{*}{} \fi

Emp need to produce a file to put the Metapost code in it. The simplest way is to wrap your entire document in a single Emp file, and import MetaUML in it:

\begin{document} \begin{empfile} \begin{empcmds} input metauml; \end{empcmds} % The rest of the document here \end{empfile} \end{document}

Now you can use the emp environment to put MetaUML diagrams inside your document:

\begin{figure} \centering \begin{emp}[classdiag](20, 20) Class.A("A")()(); Class.B("B")()(); B.e = A.w + (-20, 0); drawObjects(A, B); link(inheritance)(B.e -- A.w); \end{emp} \caption{A class diagram} \end{figure}

There is one thing that you have to pay attention to. Metapost does not limit the scope of variables to their figures, so if you want to re-use a variable, you have to save it first:

\begin{figure} \centering \begin{emp}[classdiag2](20, 20) save A; % This is important Class.A("A1")()(); drawObject(A); \end{emp} \caption{Another class diagram} \end{figure}

Making this whole thing work is a bit trickey. You have to run LaTeX to produce the Metapost file, then to run Metapost itself, and then to re-run LaTeX to include the generated image files. However, if you’re used to LaTeX’s crooked build order anyway, this might even seem natural to you.

I’m still working on it. I also want to take another look at PGF/Tikz – It seems promising, although it does not come with its-own UML lib. More details to follow!

Posted Tuesday, March 3rd, 2009 under Software Engineering.

Tags: ,

1. Waiting for the new details

2. Brilliant guide, just what I’ve been looking for. Thanks a lot.

3. Hej,
I’d like to use your idea of embedding metafont in emp. You say that “You have to run LaTeX to produce the Metapost file, then to run Metapost itself, and then to re-run LaTeX to include the generated image files.”
What is the produced Metapost file supposed to look like? It does not seem to work for me. Would you mind providing some more details and eventually telling me what I am supposed to get after running latex? What I get so far is a compiled latex file, with the figure caption shown, but no figure. no warning neither.

Thanks.
Dagmar

4. Sorry, right after posting the comment,
I found this file: http://tex.loria.fr/prod-graph/metapost-wilson2000.pdf
which immediately helped

Working now.
Thanks again.

5. Thanks for sharing that, Dagmar. I’m glad it works for you!

6. This looks beautifully promising. Thank you very much for sharing this.

7. David Topham says:

This is very interesting, thank you for letting us know.

8. Hannes Molsen says:

This is a very nice solution! Thanks for sharing!

For everyone using TeXniccenter with MikTeX (pretty common combination…) here are some hints:

using the example from above, you simply have to go to your output profiles (Alt + F7), Postprocessing, New.
Type in a name, i.e. “MetaUML”, choose mpost.exe as application (located usually in your miktex distribution: miktex\bin\mpost.exe), and use %tm as argument.

This works very well for me!

Another hint:

If you are playing around you will most likely call your files test.tex or so. Don’t ever give them a name than somewhat related with the metauml package. I.e. metauml.tex or boxes.tex are very bad. These filenames (as metauml.mp an so on) exist in the metapost distribution and are included every time you “compile”. You would end up in an infinite include loop with the following error message: MetaPost capacity exceeded, sorry [text input levels=20].

So long, have fun with uml AND state charts AND use case and so on… amazing package!

9. Thanks a lot, this is a great uml diagram embedding for my next articles and I think to all users who were read that.

However your processing steps are not complete, this is why I am going to share my experience on an Ubuntu-based (Linux) os.

We have to make several compilation through the commands pdflatex, mpost and again pdflatex.

if your latex file is called example.tex, type the following commands:

1) pdflatex example.tex
2) mpost example.mp
3) pdflatex example.tex

and then all is ready to be seen on your example.pdf file.

HF.

10. Johann Spies says:

I get this working in the ‘article’ documentclass but not in beamer when emp.sty complains about a4 not being available.

11. “Duplicate comment detected; it looks as though you’ve already said that!” — WTF?

You could also use Dia (http://live.gnome.org/Dia) which has build-in UML support. You can export the diagram in several LaTeX notations like PDF/TikZ, MetaPost or PSTricks.

12. Still useful after all this time Thanks!

U share this typesetting for my miktex installation, it does pdflatex twice for the \tableofcontents rendering:

@pdflatex -synctex=1 “%1.tex” && mpost “%1.mp” && pdflatex -synctex=1 “%1.tex”

Furthermore, I installed(extracted) the 0.2.5 version of metaUML to {installdir}\MiKTeX 2.9\metapost\base\

And one onther thing: I use UMLGraph and a maven plugin to generate (I’m a lazy, backwards engineering student) my class diagrams. And what do you know… there is a dot2tex program that can convert the output of UMLGraph to LaTeX. Sure gonna give it a try as well.

Thanks and greetings to you me kind sir

13. You might want to have a look at the mpgraphics package.
http://tug.ctan.org/pkg/mpgraphics

hf