Add rasterized option to contourf (matplotlib#29582)

* allow rasterization

* use rasterized kwarg

* add to documentation

* Fix copied docstring

Co-authored-by: Ruth Comer <10599679+rcomer@users.noreply.github.com>

* first pass at test

* add image comparison

---------

Co-authored-by: Ruth Comer <10599679+rcomer@users.noreply.github.com>

Author: AdamOrmondroyd

lib/matplotlib/contour.py

@@ -24,6 +24,7 @@
 import matplotlib.cbook as cbook
 import matplotlib.patches as mpatches
 import matplotlib.transforms as mtransforms
+from . import artist
 
 
 def _contour_labeler_event_handler(cs, inline, inline_spacing, event):
@@ -767,6 +768,7 @@ def __init__(self, ax, *args,
                 edgecolor="none",
                 # Default zorder taken from Collection
                 zorder=kwargs.pop("zorder", 1),
+                rasterized=kwargs.pop("rasterized", False),
             )
 
         else:
@@ -1254,6 +1256,7 @@ def find_nearest_contour(self, x, y, indices=None, pixel=True):
 
         return (i_level, segment, index, xmin, ymin, d2)
 
+    @artist.allow_rasterization
     def draw(self, renderer):
         paths = self._paths
         n_paths = len(paths)
@@ -1681,6 +1684,13 @@ def _initialize_x_y(self, z):
 data : indexable object, optional
     DATA_PARAMETER_PLACEHOLDER
 
+rasterized : bool, optional
+    *Only applies to* `.contourf`.
+    Rasterize the contour plot when drawing vector graphics.  This can
+    speed up rendering and produce smaller files for large data sets.
+    See also :doc:`/gallery/misc/rasterization_demo`.
+
+
 Notes
 -----
 1. `.contourf` differs from the MATLAB version in that it does not draw

lib/matplotlib/tests/baseline_images/test_contour/contour_rasterization.pdf

@@ -837,3 +837,13 @@ def test_allsegs_allkinds():
         assert len(result) == 2
         assert len(result[0]) == 5
         assert len(result[1]) == 4
+
+
+@image_comparison(baseline_images=['contour_rasterization'],
+                  extensions=['pdf'], style='mpl20', savefig_kwarg={'dpi': 25})
+def test_contourf_rasterize():
+    fig, ax = plt.subplots()
+    data = [[0, 1], [1, 0]]
+    circle = mpatches.Circle([0.5, 0.5], 0.5, transform=ax.transAxes)
+    cs = ax.contourf(data, clip_path=circle, rasterized=True)
+    assert cs._rasterized