Autodetect whether pgf can use \includegraphics[interpolate].

This is done by reusing the same LatexManager instance as the one used
for measuring text extents.

As an aside, this exposes an awkwardness in the implementation of
LatexManager -- after an error occurs, the instance needs to be
discarded (ideally, the instance would auto-create a new subprocess).
This is why _get_image_inclusion_command manually discards the cached
instance in such a case.

For recent setups where \includegraphics[interpolate=true] is available,
the cost of this PR is essentially just an additional
\usepackage{graphicx} executed once; for older setups, an additional
instantiation of a latex subprocess (only once).

This can't be tested on CI because Travis' version of latex is too old,
but can be manually tested by inspecting a resulting pgf output, and
possibly changing `interpolate=true` by a nonexistent option (e.g.
`foobar` and checking that there's fallback to \pgfimage in that case.

Author: anntzer

doc/api/next_api_changes/2019-08-28-AL.rst

@@ -0,0 +1,8 @@
+PGF backend changes
+```````````````````
+
+The pgf backend now includes images using ``\includegraphics`` instead of
+``\pgfimage`` if the version of ``graphicx`` is recent enough to support the
+``interpolate`` option (this is detected automatically).
+
+``RendererPgf.latexManager`` is deprecated.

lib/matplotlib/backends/backend_pgf.py

@@ -220,6 +220,8 @@ def _build_latex_header():
             # Include TeX program name as a comment for cache invalidation.
             # TeX does not allow this to be the first line.
             r"% !TeX program = {}".format(rcParams["pgf.texsystem"]),
+            # Test whether \includegraphics supports interpolate option.
+            r"\usepackage{graphicx}",
             latex_preamble,
             latex_fontspec,
             r"\begin{document}",
@@ -376,6 +378,22 @@ def get_width_height_descent(self, text, prop):
         return w, h + o, o
 
 
+@functools.lru_cache(1)
+def _get_image_inclusion_command():
+    man = LatexManager._get_cached_or_new()
+    man._stdin_writeln(
+        r"\includegraphics[interpolate=true]{%s}"
+        # Don't mess with backslashes on Windows.
+        % cbook._get_data_path("images/matplotlib.png").as_posix())
+    try:
+        prompt = man._expect_prompt()
+        return r"\includegraphics"
+    except LatexError:
+        # Discard the broken manager.
+        LatexManager._get_cached_or_new_impl.cache_clear()
+        return r"\pgfimage"
+
+
 class RendererPgf(RendererBase):
 
     def __init__(self, figure, fh, dummy=False):
@@ -397,8 +415,7 @@ def __init__(self, figure, fh, dummy=False):
         self.figure = figure
         self.image_counter = 0
 
-        # get LatexManager instance
-        self.latexManager = LatexManager._get_cached_or_new()
+        self._latexManager = LatexManager._get_cached_or_new()  # deprecated
 
         if dummy:
             # dummy==True deactivate all methods
@@ -413,6 +430,10 @@ def __init__(self, figure, fh, dummy=False):
                                      "pgf-to-pdf option", UserWarning)
                 self.__dict__["draw_image"] = lambda *args, **kwargs: None
 
+    @cbook.deprecated("3.2")
+    def latexManager(self):
+        return self._latexManager
+
     def draw_markers(self, gc, marker_path, marker_trans, path, trans,
                      rgbFace=None):
         # docstring inherited
@@ -660,8 +681,9 @@ def draw_image(self, gc, x, y, im, transform=None):
         interp = str(transform is None).lower()  # interpolation in PDF reader
         writeln(self.fh,
                 r"\pgftext[left,bottom]"
-                r"{\pgfimage[interpolate=%s,width=%fin,height=%fin]{%s}}" %
-                (interp, w, h, fname_img))
+                r"{%s[interpolate=%s,width=%fin,height=%fin]{%s}}" %
+                (_get_image_inclusion_command(),
+                 interp, w, h, fname_img))
         writeln(self.fh, r"\end{pgfscope}")
 
     def draw_tex(self, gc, x, y, s, prop, angle, ismath="TeX!", mtext=None):
@@ -724,7 +746,8 @@ def get_text_width_height_descent(self, s, prop, ismath):
         s = common_texification(s)
 
         # get text metrics in units of latex pt, convert to display units
-        w, h, d = self.latexManager.get_width_height_descent(s, prop)
+        w, h, d = (LatexManager._get_cached_or_new()
+                   .get_width_height_descent(s, prop))
         # TODO: this should be latex_pt_to_in instead of mpl_pt_to_in
         # but having a little bit more space around the text looks better,
         # plus the bounding box reported by LaTeX is VERY narrow