Improve documentation on rasterization

timhoffm · timhoffm · commit a22d219026dc · 2020-11-18T01:07:13.000+01:00
diff --git a/examples/misc/rasterization_demo.py b/examples/misc/rasterization_demo.py
@@ -1,20 +1,35 @@
 """
-==================
-Rasterization Demo
-==================
+=================================
+Rasterization for vector graphics
+=================================
 
-Rasterization is a method where an image described in a vector graphics
-format is being converted into a raster image (pixels).
+Rasterization converts vector graphics into a raster image (pixels).
 
 Individual artists can be rasterized for saving to a vector backend
 such as PDF, SVG, or PS as embedded images.  This can be useful to
 reduce the file size of large artists, while maintaining the
 advantages of vector graphics for other artists such as the axes
-and annotations.  For instance a complicated `~.Axes.pcolormesh` or
+and texts.  For instance a complicated `~.Axes.pcolormesh` or
 `~.Axes.contourf` can be made significantly simpler by rasterizing.
-Note that the size and resolution of the rasterized artist is
-controlled by its physical size and the value of the ``dpi`` kwarg
-passed to `~.Figure.savefig`.
+
+Rasterization is disabled by default. There are two ways to enable it, which
+can also be combined:
+
+- Set `~.Artist.set_rasterized` on individual artists, or use the keyword
+  argument *rasterized* when creating the artist.
+- Set `.Axes.set_rasterization_zorder` to rasterize all artists with a zorder
+  less than the given value.
+
+The storage size and the resolution of the rasterized artist is determined by
+its physical size and the value of the ``dpi`` parameter passed to
+`~.Figure.savefig`.
+
+.. note::
+
+    The image of this example shown in the HTML documentation is not a vector
+    graphics. Therefore, it cannot illustrate the rasterization effect. Please
+    run this example locally and check the generated graphics files.
+
 """
 
 import numpy as np
@@ -27,37 +42,34 @@
 xx = x*np.cos(theta) - y*np.sin(theta)  # rotate x by -theta
 yy = x*np.sin(theta) + y*np.cos(theta)  # rotate y by -theta
 
-# Plot the rasterized and non-rasterized plot
 fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(2, 2, constrained_layout=True)
 
-# Create a pseudocolor non-rastertized plot with a non-regular rectangular grid
+# pcolormesh without rasterization
 ax1.set_aspect(1)
 ax1.pcolormesh(xx, yy, d)
 ax1.set_title("No Rasterization")
 
-# Create a pseudocolor rastertized plot with a non-regular rectangular grid
+# pcolormesh with rasterization; enabled by keyword argument
 ax2.set_aspect(1)
 ax2.set_title("Rasterization")
 m = ax2.pcolormesh(xx, yy, d, rasterized=True)
 
-# Create a pseudocolor non-rastertized plot with a non-regular rectangular
-# grid and an overlapped "Text"
+# pcolormesh with an overlaid text without rasterization
 ax3.set_aspect(1)
 ax3.pcolormesh(xx, yy, d)
 ax3.text(0.5, 0.5, "Text", alpha=0.2,
          va="center", ha="center", size=50, transform=ax3.transAxes)
 ax3.set_title("No Rasterization")
 
-# Create a pseudocolor rastertized plot with a non-regular rectangular
-# grid and an overlapped "Text"
+# pcolormesh with an overlaid text without rasterization; enabled by zorder
+# Even though the text is below the rasterization_zorder, it is not rasterized
+# because Text objects do not support rasterization.
 ax4.set_aspect(1)
 m = ax4.pcolormesh(xx, yy, d, zorder=-20)
 ax4.text(0.5, 0.5, "Text", alpha=0.2, zorder=-15,
          va="center", ha="center", size=50, transform=ax4.transAxes)
-# Set zorder value below which artists will be rasterized
 ax4.set_rasterization_zorder(-10)
 ax4.set_title("Rasterization z$<-10$")
-# ax2.title.set_rasterized(True) # should display a warning
 
 # Save files in pdf and eps format
 plt.savefig("test_rasterization.pdf", dpi=150)
@@ -66,3 +78,19 @@
 if not plt.rcParams["text.usetex"]:
     plt.savefig("test_rasterization.svg", dpi=150)
     # svg backend currently ignores the dpi
+
+#############################################################################
+#
+# ------------
+#
+# References
+# """"""""""
+#
+# The use of the following functions, methods, classes and modules is shown
+# in this example:
+
+import matplotlib
+matplotlib.artist.Artist.set_rasterized
+matplotlib.axes.Axes.set_rasterization_zorder
+matplotlib.axes.Axes.pcolormesh
+matplotlib.pyplot.pcolormesh
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -887,9 +887,15 @@ def get_rasterized(self):
 
     def set_rasterized(self, rasterized):
         """
-        Force rasterized (bitmap) drawing in vector backend output.
+        Force rasterized (bitmap) drawing for vector graphics output.
 
-        Defaults to None, which implies the backend's default behavior.
+        Rasterized drawing is not supported by all artists. If you try to
+        enable this on an artist that does not support it, the command has no
+        effect and a warning will be issued.
+
+        This setting is ignored for pixel-based output.
+
+        See also :doc:`/gallery/misc/rasterization_demo`.
 
         Parameters
         ----------
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -2488,11 +2488,20 @@ def margins(self, *margins, x=None, y=None, tight=True):
 
     def set_rasterization_zorder(self, z):
         """
+        Set the zorder threshold for rasterization for vector graphics output.
+
+        All artists with a zorder below the given value will be rasterized if
+        they support rasterization.
+
+        This setting is ignored for pixel-based output.
+
+        See also :doc:`/gallery/misc/rasterization_demo`.
+
         Parameters
         ----------
         z : float or None
-            zorder below which artists are rasterized.  ``None`` means that
-            artists do not get rasterized based on zorder.
+            The zorder below which artists are rasterized.
+            If ``None`` rasterization based on zorder is deactivated.
         """
         self._rasterization_zorder = z
         self.stale = True
diff --git a/lib/matplotlib/tests/test_mathtext.py b/lib/matplotlib/tests/test_mathtext.py
@@ -11,6 +11,18 @@
 from matplotlib import cbook, mathtext
 
 
+
+def test_mathtext_cmr10_minus_sign():
+    # cmr10 does not contain a minus sign and used to issue a warning
+    # RuntimeWarning: Glyph 8722 missing from current font.
+    mpl.rcParams['font.family'] = 'cmr10'
+    fig, ax = plt.subplots()
+    ax.plot(range(-1, 1), range(-1, 1))
+    with pytest.warns(None) as record:
+        fig.canvas.draw()
+    assert len(record) == 0, (f"Got {len(record)} warnings:\n" + "\n".join(
+                                  str(e.message) for e in record))
+
 # If test is removed, use None as placeholder
 math_tests = [
     r'$a+b+\dot s+\dot{s}+\ldots$',
