matplotlib · tacaswell · Jun 20, 2023 · Jun 20, 2023 · Jun 20, 2023 · Jun 15, 2023
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -299,11 +299,24 @@ jobs:
           rm -rf ~/.cache/matplotlib
         if: matrix.delete-font-cache
 
+      - name: extract baseline images
+        run: |
+          mkdir -p /tmp/test_images/matplotlib/tests
+          cp -r lib/matplotlib/tests/baseline_images /tmp/test_images/matplotlib/tests
+          mkdir -p /tmp/test_images/mpl_toolkits/axes_grid1/tests/
+          cp -r lib/mpl_toolkits/axes_grid1/tests/baseline_images /tmp/test_images/mpl_toolkits/axes_grid1/tests/
+          mkdir -p /tmp/test_images/mpl_toolkits/axisartist/tests/
+          cp -r lib/mpl_toolkits/axisartist/tests/baseline_images /tmp/test_images/mpl_toolkits/axisartist/tests/
+          mkdir -p /tmp/test_images/mpl_toolkits/mplot3d/tests/
+          cp -r lib/mpl_toolkits/mplot3d/tests/baseline_images /tmp/test_images/mpl_toolkits/mplot3d/tests/
+
       - name: Run pytest
         run: |
           python -mpytest -raR -n auto \
             --maxfail=50 --timeout=300 --durations=25 \
             --cov-report=xml --cov=lib --log-level=DEBUG --color=yes
+        env:
+          MPLTESTIMAGEPATH: /tmp/test_images/
 
       - name: Filter C coverage
         run: |

diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst
@@ -303,6 +303,8 @@ project that leads to a scientific publication, please follow the
 Coding guidelines
 =================
 
+.. _coding_guidelines-API_changes:
+
 API changes
 -----------
 

diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst
@@ -96,8 +96,66 @@ and then use ``rng`` when generating the random numbers.
 
 The seed is John Hunter's birthday.
 
-Writing an image comparison test
---------------------------------
+Image Comparison tests
+----------------------
+
+As noted in :ref:`coding_guidelines-API_changes` we consider any changes to the
+visual output of Matplotlib to be an API change.  To ensure that our visual
+output is consistent we make heavy use of image comparison tests in the
+automated test suites.  By default, and with only a few exceptions, the tests
+compare the expected and test output with zero tolerance which means the output
+of Matplotlib is stable at the pixel level across time, platform, and
+architecture.
+
+For Agg, which directly produces raster output, we directly compare the output
+with saved png.  For vector outputs we use an external tool (inkscape for svg
+and ghostscript for eps/pdf) to convert both the baseline and test image to a
+raster that we can compare.  However, different versions of FreeType slightly
+shift the placement and size of the rendered text which in turn causes our
+tests to fail.  Thus, we have historically run the test suite with a fixed
+version of FreeType.
+
+In the past we stored a complete set of the test images, against a specific
+version of FreeType, in the main source repository.  While highly effective,
+this was not a sustainable over the long term as the pinned version of FreeType
+will eventually need to be updated.  Further, while our wheels are built with
+the pinned version of FreeType, most other down-stream packages (such as
+conda-forge and the Linux distributions) use what ever their currently
+supported Freetype is this many of our users are using a version of FreeType
+that we do not test.
+
+We now use a combination of testing for self-consistency with files generated
+on a developers computer and sets of canonical baseline images generated with
+every release.
+
+
+Generate local baseline images from upstream branch
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+Adding a test image
+^^^^^^^^^^^^^^^^^^^
+
+
+Update a test image
+^^^^^^^^^^^^^^^^^^^
+
+
+Build Matplotlib with a specific FreeType
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+Fetch the baseline images for a Matplotlib Release and FreeType version
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+Generate the baseline images for a Matplotlib Release and FreeType version
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+
+Writing an image comparison test [TODO fix]
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Writing an image-based test is only slightly more difficult than a simple
 test. The main consideration is that you must specify the "baseline", or
@@ -140,6 +198,7 @@ See the documentation of `~matplotlib.testing.decorators.image_comparison` and
 `~matplotlib.testing.decorators.check_figures_equal` for additional information
 about their use.
 
+
 Creating a new module in matplotlib.tests
 -----------------------------------------
 

diff --git a/lib/matplotlib/cbook.py b/lib/matplotlib/cbook.py
@@ -192,9 +192,11 @@ def __getstate__(self):
                           for s, d in self.callbacks.items()},
             # It is simpler to reconstruct this from callbacks in __setstate__.
             "_func_cid_map": None,
+            "_cid_gen": next(self._cid_gen)
         }
 
     def __setstate__(self, state):
+        cid_count = state.pop('_cid_gen')
         vars(self).update(state)
         self.callbacks = {
             s: {cid: _weak_or_strong_ref(func, self._remove_proxy)
@@ -203,6 +205,7 @@ def __setstate__(self, state):
         self._func_cid_map = {
             s: {proxy: cid for cid, proxy in d.items()}
             for s, d in self.callbacks.items()}
+        self._cid_gen = itertools.count(cid_count)
 
     def connect(self, signal, func):
         """Register *func* to be called when signal *signal* is generated."""

diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -105,6 +105,17 @@ def current(self):
         """Return the active axes, or None if the stack is empty."""
         return max(self._axes, key=self._axes.__getitem__, default=None)
 
+    def __getstate__(self):
+        return {
+            **vars(self),
+            "_counter": max(self._axes.values(), default=0)
+        }
+
+    def __setstate__(self, state):
+        next_counter = state.pop('_counter')
+        vars(self).update(state)
+        self._counter = itertools.count(next_counter)
+
 
 class SubplotParams:
     """

diff --git a/lib/matplotlib/testing/conftest.py b/lib/matplotlib/testing/conftest.py
@@ -15,6 +15,7 @@ def pytest_configure(config):
         ("markers", "backend: Set alternate Matplotlib backend temporarily."),
         ("markers", "baseline_images: Compare output against references."),
         ("markers", "pytz: Tests that require pytz to be installed."),
+        ("markers", "generate_images: Flag to generate matplotlib baseline images."),
         ("filterwarnings", "error"),
         ("filterwarnings",
          "ignore:.*The py23 module has been deprecated:DeprecationWarning"),