The TikZ and PGF Packages
Manual for version 3.1.10
1Introduction
Welcome to the documentation of TikZ and the underlying pgf system. What began as a small LaTeX style for creating the graphics in my (Till Tantau’s) PhD thesis directly with pdfLaTeX has now grown to become a full-blown graphics language with a manual of over a thousand pages. The wealth of options offered by TikZ is often daunting to beginners; but fortunately this documentation comes with a number of slowly-paced tutorials that will teach you almost all you should know about TikZ without your having to read the rest.
I wish to start with the question “What is TikZ?” Basically, it just defines a number
of
TeX
commands that draw graphics. For example, the code \tikz \draw (0pt,0pt) -- (20pt,6pt); yields the
line
and the code \tikz \fill[orange] (1ex,1ex) circle (1ex); yields
. In a sense, when you use TikZ you “program” your graphics, just as you
“program” your document when you use
TeX. This also explains the name: TikZ is a recursive acronym in the tradition of “gnu’s Not Unix” and means “TikZ ist kein Zeichenprogramm”, which
translates to “TikZ is not a drawing program”, cautioning the reader as to what to
expect. With TikZ you get all the advantages of the “TeX-approach to typesetting” for your graphics: quick creation of simple graphics, precise positioning, the use of macros,
often superior typography. You also inherit all the disadvantages: steep learning curve, no wysiwyg,
small changes require a long recompilation time, and the code does not really “show” how things will look like.
Now that we know what TikZ is, what about “pgf”? As mentioned earlier, TikZ started out as a project to implement TeX graphics macros that can be used both with pdfLaTeX and also with the classical (PostScript-based) LaTeX. In other words, I wanted to implement a “portable graphics format” for TeX – hence the name pgf. These early macros are still around and they form the “basic layer” of the system described in this manual, but most of the interaction an author has these days is with TikZ – which has become a whole language of its own.
1.1 The Layers Below TikZ¶
It turns out that there are actually two layers below TikZ:
- System layer:
-
This layer provides a complete abstraction of what is going on “in the driver”. The driver is a program like dvips or dvipdfm that takes a .dvi file as input and generates a .ps or a .pdf file. (The pdftex program also counts as a driver, even though it does not take a .dvi file as input. Never mind.) Each driver has its own syntax for the generation of graphics, causing headaches to everyone who wants to create graphics in a portable way. pgf’s system layer “abstracts away” these differences. For example, the system command \pgfsys@lineto{10pt}{10pt} extends the current path to the coordinate (10pt, 10pt) of the current {pgfpicture}. Depending on whether dvips, dvipdfm, or pdftex is used to process the document, the system command will be converted to different \special commands. The system layer is as “minimalistic” as possible since each additional command makes it more work to port pgf to a new driver.
As a user, you will not use the system layer directly.
- Basic layer:
-
The basic layer provides a set of basic commands that allow you to produce complex graphics in a much easier manner than by using the system layer directly. For example, the system layer provides no commands for creating circles since circles can be composed from the more basic Bézier curves (well, almost). However, as a user you will want to have a simple command to create circles (at least I do) instead of having to write down half a page of Bézier curve support coordinates. Thus, the basic layer provides a command \pgfpathcircle that generates the necessary curve coordinates for you.
The basic layer consists of a core, which consists of several interdependent packages that can only be loaded en bloc, and additional modules that extend the core by more special-purpose commands like node management or a plotting interface. For instance, the beamer package uses only the core and not, say, the shapes modules.
In theory, TikZ itself is just one of several possible “frontends”. which are sets of commands or a special syntax that makes using the basic layer easier. A problem with directly using the basic layer is that code written for this layer is often too “verbose”. For example, to draw a simple triangle, you may need as many as five commands when using the basic layer: One for beginning a path at the first corner of the triangle, one for extending the path to the second corner, one for going to the third, one for closing the path, and one for actually painting the triangle (as opposed to filling it). With the TikZ frontend all this boils down to a single simple metafont-like command:
\draw (0,0) -- (1,0) -- (1,1) -- cycle;
In practice, TikZ is the only “serious” frontend for pgf. It gives you access to all features of pgf, but it is intended to be easy to use. The syntax is a mixture of metafont and pstricks and some ideas of myself. There are other frontends besides TikZ, but they are intended more as “technology studies” and less as serious alternatives to TikZ. In particular, the pgfpict2e frontend reimplements the standard LaTeX {picture} environment and commands like \line or \vector using the pgf basic layer. This layer is not really “necessary” since the pict2e.sty package does at least as good a job at reimplementing the {picture} environment. Rather, the idea behind this package is to have a simple demonstration of how a frontend can be implemented.
Since most users will only use TikZ and almost no one will use the system layer directly, this manual is mainly about TikZ in the first parts; the basic layer and the system layer are explained at the end.
1.2 Comparison with Other Graphics Packages¶
TikZ is not the only graphics package for TeX. In the following, I try to give a reasonably fair comparison of TikZ and other packages.
-
1. The standard LaTeX {picture} environment allows you to create simple graphics, but little more. This is certainly not due to a lack of knowledge or imagination on the part of LaTeX’s designer(s). Rather, this is the price paid for the {picture} environment’s portability: It works together with all backend drivers.
-
2. The pstricks package is certainly powerful enough to create any conceivable kind of graphic, but it is not really portable. Most importantly, it does not work with pdftex nor with any other driver that produces anything but PostScript code.
Compared to TikZ, pstricks has a similar support base. There are many nice extra packages for special purpose situations that have been contributed by users over the last decade. The TikZ syntax is more consistent than the pstricks syntax as TikZ was developed “in a more centralized manner” and also “with the shortcomings on pstricks in mind”.
-
3. The xypic package is an older package for creating graphics. However, it is more difficult to use and to learn because the syntax and the documentation are a bit cryptic.
-
4. The dratex package is a small graphic package for creating a graphics. Compared to the other package, including TikZ, it is very small, which may or may not be an advantage.
-
5. The metapost program is a powerful alternative to TikZ. It used to be an external program, which entailed a bunch of problems, but in LuaTeX it is now built in. An obstacle with metapost is the inclusion of labels. This is much easier to achieve using pgf.
-
6. The xfig program is an important alternative to TikZ for users who do not wish to “program” their graphics as is necessary with TikZ and the other packages above. There is a conversion program that will convert xfig graphics to TikZ.
1.3 Utility Packages¶
The pgf package comes along with a number of utility package that are not really about creating graphics and which can be used independently of pgf. However, they are bundled with pgf, partly out of convenience, partly because their functionality is closely intertwined with pgf. These utility packages are:
-
1. The pgfkeys package defines a powerful key management facility. It can be used completely independently of pgf.
-
2. The pgffor package defines a useful \foreach statement.
-
3. The pgfcalendar package defines macros for creating calendars. Typically, these calendars will be rendered using pgf’s graphic engine, but you can use pgfcalendar also typeset calendars using normal text. The package also defines commands for “working” with dates.
-
4. The pgfpages package is used to assemble several pages into a single page. It provides commands for assembling several “virtual pages” into a single “physical page”. The idea is that whenever TeX has a page ready for “shipout”, pgfpages interrupts this shipout and instead stores the page to be shipped out in a special box. When enough “virtual pages” have been accumulated in this way, they are scaled down and arranged on a “physical page”, which then really shipped out. This mechanism allows you to create “two page on one page” versions of a document directly inside LaTeX without the use of any external programs. However, pgfpages can do quite a lot more than that. You can use it to put logos and watermark on pages, print up to 16 pages on one page, add borders to pages, and more.
1.4 How to Read This Manual¶
This manual describes both the design of TikZ and its usage. The organization is very roughly according to “user-friendliness”. The commands and subpackages that are easiest and most frequently used are described first, more low-level and esoteric features are discussed later.
If you have not yet installed TikZ, please read the installation first. Second, it might be a good idea to read the tutorial. Finally, you might wish to skim through the description of TikZ. Typically, you will not need to read the sections on the basic layer. You will only need to read the part on the system layer if you intend to write your own frontend or if you wish to port pgf to a new driver.
The “public” commands and environments provided by the system are described throughout the text. In each such description, the described command, environment or option is printed in red. Text shown in green is optional and can be left out.
1.5 Authors and Acknowledgements¶
The bulk of the pgf system and its documentation was written by Till Tantau. A further member of the main team is Mark Wibrow, who is responsible, for example, for the pgf mathematical engine, many shapes, the decoration engine, and matrices. The third member is Christian Feuersänger who contributed the floating point library, image externalization, extended key processing, and automatic hyperlinks in the manual.
Furthermore, occasional contributions have been made by Christophe Jorssen, Jin-Hwan Cho, Olivier Binda, Matthias Schulz, Renée Ahrens, Stephan Schuster, and Thomas Neumann.
Additionally, numerous people have contributed to the pgf system by writing emails, spotting bugs, or sending libraries and patches. Many thanks to all these people, who are too numerous to name them all!
1.6 Getting Help¶
When you need help with pgf and TikZ, please do the following:
-
1. Read the manual, at least the part that has to do with your problem.
-
2. If that does not solve the problem, try having a look at the GitHub development page for pgf and TikZ (see the title of this document). Perhaps someone has already reported a similar problem and someone has found a solution.
-
3. On the website you will find numerous forums for getting help. There, you can write to help forums, file bug reports, join mailing lists, and so on.
-
4. Before you file a bug report, especially a bug report concerning the installation, make sure that this is really a bug. In particular, have a look at the .log file that results when you TeX your files. This .log file should show that all the right files are loaded from the right directories. Nearly all installation problems can be resolved by looking at the .log file.
-
5. As a last resort you can try to email me (Till Tantau) or, if the problem concerns the mathematical engine, Mark Wibrow. I do not mind getting emails, I simply get way too many of them. Because of this, I cannot guarantee that your emails will be answered in a timely fashion or even at all. Your chances that your problem will be fixed are somewhat higher if you mail to the pgf mailing list (naturally, I read this list and answer questions when I have the time).