Merge pull request #1076 from pwuertz/pgf-backend

PGF backend for XeLaTeX/LuaLaTeX support

doc/users/index_text.rst

@@ -8,6 +8,7 @@ Working with text
     text_intro.rst
     text_props.rst
     mathtext.rst
+    pgf.rst
     usetex.rst
     annotations_intro.rst
 

doc/users/pgf.rst

@@ -0,0 +1,128 @@
+.. _pgf-tutorial:
+
+*********************************
+Typesetting With XeLaTeX/LuaLaTeX
+*********************************
+
+Using the ``pgf`` backend, matplotlib can export figures as pgf drawing commands
+that can be processed with pdflatex, xelatex or lualatex. XeLaTeX and LuaLaTeX
+have full unicode support and can use any fonts installed in the operating
+system, making use of advanced typographic features of OpenType, AAT and
+Graphite. Pgf pictures created by ``plt.savefig('figure.pgf')`` can be
+embedded as raw commands in LaTeX documents. Figures can also be directly
+compiled and saved to PDF with ``plt.savefig('figure.pdf')``.
+
+Matplotlib's pgf support requires a working LaTeX_ installation (such as
+TeXLive_), preferably including XeLaTeX or LuaLaTeX. If pdftocairo or
+ghostscript is installed, figures can optionally be saved to PNG images.
+The executables for all applications must be located on your :envvar:`PATH`.
+
+Rc parameters that control the behavior of the pgf backend:
+
+    =================  =====================================================
+    Parameter          Documentation
+    =================  =====================================================
+    pgf.preamble       Lines to be included in the LaTeX preamble
+    pgf.rcfonts        Setup fonts from rc params using the fontspec package
+    pgf.texsystem      Either "xelatex", "lualatex" or "pdflatex"
+    =================  =====================================================
+
+.. note::
+
+   TeX defines a set of secial characters, such as::
+
+     # $ % & ~ _ ^ \ { }
+
+   Generally, these characters must be escaped correctly. For convenience,
+   some characters (_,^,%) are automatically escaped outside of math
+   environments.
+
+.. _pgf-rcfonts:
+
+Font specification
+==================
+
+The fonts used for obtaining the size of text elements or when compiling
+figures to PDF are usually defined in the matplotlib rc parameters. You can
+also use the LaTeX default Computer Modern fonts by clearing the lists for
+``font.serif``, ``font.sans-serif`` or ``font.monospace``. Please note that
+the glyph coverage of these fonts is very limited. For extended unicode support
+the `Computer Modern Unicode <http://sourceforge.net/projects/cm-unicode/>`_
+fonts "CMU Serif", "CMU Sans Serif" are recommended.
+
+.. literalinclude:: plotting/examples/pgf_fonts.py
+   :end-before: plt.savefig
+
+.. image:: /_static/pgf_fonts.*
+
+
+.. _pgf-preamble:
+
+Custom preamble
+===============
+
+Full customization is possible by adding your own commands to the preamble.
+Use the ``pgf.preamble`` parameter if you want to configure the math fonts or
+for loading additional packages. Also, if you want to do the font configuration
+yourself instead of using the fonts specified in the rc parameters, make sure
+to disable ``pgf.rcfonts``.
+
+.. htmlonly::
+
+    .. literalinclude:: plotting/examples/pgf_preamble.py
+        :end-before: plt.savefig
+
+.. latexonly::
+
+    .. literalinclude:: plotting/examples/pgf_preamble.py
+        :end-before: import matplotlib.pyplot as plt
+
+.. image:: /_static/pgf_preamble.*
+
+
+.. _pgf-texsystem:
+
+Choosing the TeX system
+=======================
+
+The TeX system to be used by matplotlib is chosen by the ``pgf.texsystem``
+parameter. Possible values are ``'xelatex'`` (default), ``'lualatex'`` and
+``'pdflatex'``. Please note that when selecting pdflatex the fonts and
+unicode handling must be configured in the preamble.
+
+.. literalinclude:: plotting/examples/pgf_texsystem.py
+   :end-before: plt.savefig
+
+.. image:: /_static/pgf_texsystem.*
+
+.. _pgf-hangups:
+
+Possible hangups
+================
+
+* On Windows, the :envvar:`PATH` environment variable may need to be modified
+  to include the directories containing the latex, dvipng and ghostscript
+  executables. See :ref:`environment-variables` and
+  :ref:`setting-windows-environment-variables` for details.
+
+* Sometimes the font rendering in figures that are saved to png images is
+  very bad. This happens when the pdftocairo tool is not available and
+  ghostscript is used for the pdf to png conversion.
+
+.. _pgf-troubleshooting:
+
+Troubleshooting
+===============
+
+* Make sure what you are trying to do is possible in a LaTeX document,
+  that your LaTeX syntax is valid and that you are using raw strings
+  if necessary to avoid unintended escape sequences.
+
+* The ``pgf.preamble`` rc setting provides lots of flexibility, and lots of
+  ways to cause problems. When experiencing problems, try to minimalize or
+  disable the custom preamble before reporting problems.
+
+* If you still need help, please see :ref:`reporting-problems`
+
+.. _LaTeX: http://www.tug.org
+.. _TeXLive: http://www.tug.org/texlive/

doc/users/plotting/examples/pgf_fonts.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+
+import matplotlib as mpl
+mpl.use("pgf")
+pgf_with_rc_fonts = {
+    "font.family": "serif",
+    "font.serif": [],                   # use latex default serif font
+    "font.sans-serif": ["DejaVu Sans"], # use a specific sans-serif font
+}
+mpl.rcParams.update(pgf_with_rc_fonts)
+
+import matplotlib.pyplot as plt
+plt.figure(figsize=(4.5,2.5))
+plt.plot(range(5))
+plt.text(0.5, 3., "serif")
+plt.text(0.5, 2., "monospace", family="monospace")
+plt.text(2.5, 2., "sans-serif", family="sans-serif")
+plt.text(2.5, 1., "comic sans", family="Comic Sans MS")
+plt.xlabel(u"µ is not $\\mu$")
+plt.tight_layout(.5)
+
+plt.savefig("pgf_fonts.pdf")
+plt.savefig("pgf_fonts.png")

doc/users/plotting/examples/pgf_preamble.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+
+import matplotlib as mpl
+mpl.use("pgf")
+pgf_with_custom_preamble = {
+    "font.family": "serif", # use serif/main font for text elements
+    "text.usetex": True,    # use inline math for ticks
+    "pgf.rcfonts": False,   # don't setup fonts from rc parameters
+    "pgf.preamble": [
+         r"\usepackage{units}",        # load additional packages
+         r"\usepackage{metalogo}",        # load additional packages
+         r"\usepackage{unicode-math}", # unicode math setup
+         r"\setmathfont{XITS Math}",
+         r"\setmainfont{DejaVu Serif}", # font setup via preamble
+         ]
+}
+mpl.rcParams.update(pgf_with_custom_preamble)
+
+import matplotlib.pyplot as plt
+plt.figure(figsize=(4.5,2.5))
+plt.plot(range(5))
+plt.xlabel(u"unicode text: я, ψ, €, ü, \\unitfrac[10]{°}{µm}")
+plt.ylabel(u"\\XeLaTeX")
+plt.legend([u"unicode math: $λ=∑_i^∞ μ_i^2$"])
+plt.tight_layout(.5)
+
+plt.savefig("pgf_preamble.pdf")
+plt.savefig("pgf_preamble.png")

doc/users/plotting/examples/pgf_texsystem.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+
+import matplotlib as mpl
+mpl.use("pgf")
+pgf_with_pdflatex = {
+    "pgf.texsystem": "pdflatex",
+    "pgf.preamble": [
+         r"\usepackage[utf8x]{inputenc}",
+         r"\usepackage[T1]{fontenc}",
+         r"\usepackage{cmbright}",
+         ]
+}
+mpl.rcParams.update(pgf_with_pdflatex)
+
+import matplotlib.pyplot as plt
+plt.figure(figsize=(4.5,2.5))
+plt.plot(range(5))
+plt.text(0.5, 3., "serif", family="serif")
+plt.text(0.5, 2., "monospace", family="monospace")
+plt.text(2.5, 2., "sans-serif", family="sans-serif")
+plt.xlabel(u"µ is not $\\mu$")
+plt.tight_layout(.5)
+
+plt.savefig("pgf_texsystem.pdf")
+plt.savefig("pgf_texsystem.png")

doc/users/whats_new.rst

@@ -17,6 +17,15 @@ This page just covers the highlights -- for the full story, see the
 new in matplotlib-1.2
 =====================
 
+PGF/TikZ backend
+----------------
+Peter Würtz wrote a backend that allows matplotlib to export figures as
+drawing commands for LaTeX that can be processed by PdfLaTeX, XeLaTeX or
+LuaLaTeX using the PGF/TikZ package. Usage examples and documentation are
+found in :ref:`pgf-tutorial`.
+
+.. image:: /_static/pgf_preamble.*
+
 Locator interface
 -----------------
 

lib/matplotlib/__init__.py

@@ -1056,6 +1056,7 @@ def tk_window_focus():
     'matplotlib.tests.test_agg',
     'matplotlib.tests.test_axes',
     'matplotlib.tests.test_backend_svg',
+    'matplotlib.tests.test_backend_pgf',
     'matplotlib.tests.test_basic',
     'matplotlib.tests.test_cbook',
     'matplotlib.tests.test_colorbar',

lib/matplotlib/backend_bases.py

@@ -1807,6 +1807,7 @@ def get_width_height(self):
         'emf': 'Enhanced Metafile',
         'eps': 'Encapsulated Postscript',
         'pdf': 'Portable Document Format',
+        'pgf': 'LaTeX PGF Figure',
         'png': 'Portable Network Graphics',
         'ps' : 'Postscript',
         'raw': 'Raw RGBA bitmap',
@@ -1841,6 +1842,11 @@ def print_pdf(self, *args, **kwargs):
         pdf = self.switch_backends(FigureCanvasPdf)
         return pdf.print_pdf(*args, **kwargs)
 
+    def print_pgf(self, *args, **kwargs):
+        from backends.backend_pgf import FigureCanvasPgf # lazy import
+        pgf = self.switch_backends(FigureCanvasPgf)
+        return pgf.print_pgf(*args, **kwargs)
+
     def print_png(self, *args, **kwargs):
         from backends.backend_agg import FigureCanvasAgg # lazy import
         agg = self.switch_backends(FigureCanvasAgg)