Merge pull request #11234 from ImportanceOfBeingErnest/fig-add-artist

tacaswell · web-flow · commit ac58f1f9254d · 2018-07-19T19:59:23.000-04:00
ENG: Add Figure.add_artist method
diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst
@@ -190,6 +190,7 @@ specify a number that is close (i.e. ``ax.title.set_position(0.5, 1.01)``)
 and the title will not be moved via this algorithm.
 
 
+
 New convenience methods for GridSpec
 ------------------------------------
 
@@ -210,6 +211,23 @@ now call `.Figure.add_gridspec` and for the latter `.SubplotSpec.subgridspec`.
         fig.add_subplot(gssub[0, i])
 
 
+Figure has an `~.figure.Figure.add_artist` method
+-------------------------------------------------
+
+A method `~.figure.Figure.add_artist` has been added to the
+:class:`~.figure.Figure` class, which allows artists to be added directly
+to a figure. E.g.
+
+::
+
+    circ = plt.Circle((.7, .5), .05)
+    fig.add_artist(circ)
+
+In case the added artist has no transform set previously, it will be set to
+the figure transform (``fig.transFigure``).
+This new method may be useful for adding artists to figures without axes or to
+easily position static elements in figure coordinates.
+
 
 
 
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1048,6 +1048,42 @@ def fixlist(args):
         key = fixlist(args), fixitems(kwargs.items())
         return key
 
+    def add_artist(self, artist, clip=False):
+        """
+        Add any :class:`~matplotlib.artist.Artist` to the figure.
+
+        Usually artists are added to axes objects using
+        :meth:`matplotlib.axes.Axes.add_artist`, but use this method in the
+        rare cases that adding directly to the figure is necessary.
+
+        Parameters
+        ----------
+        artist : `~matplotlib.artist.Artist`
+            The artist to add to the figure. If the added artist has no
+            transform previously set, its transform will be set to
+            ``figure.transFigure``.
+        clip : bool, optional, default ``False``
+            An optional parameter ``clip`` determines whether the added artist
+            should be clipped by the figure patch. Default is *False*,
+            i.e. no clipping.
+
+        Returns
+        -------
+        artist : The added `~matplotlib.artist.Artist`
+        """
+        artist.set_figure(self)
+        self.artists.append(artist)
+        artist._remove_method = self.artists.remove
+
+        if not artist.is_transform_set():
+            artist.set_transform(self.transFigure)
+
+        if clip:
+            artist.set_clip_path(self.patch)
+
+        self.stale = True
+        return artist
+
     @docstring.dedent_interpd
     def add_axes(self, *args, **kwargs):
         """
diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py
@@ -3,7 +3,7 @@
 import platform
 
 from matplotlib import rcParams
-from matplotlib.testing.decorators import image_comparison
+from matplotlib.testing.decorators import image_comparison, check_figures_equal
 from matplotlib.axes import Axes
 from matplotlib.ticker import AutoMinorLocator, FixedFormatter
 import matplotlib.pyplot as plt
@@ -383,6 +383,32 @@ def test_warn_cl_plus_tl():
     assert not(fig.get_constrained_layout())
 
 
+@check_figures_equal(extensions=["png", "pdf", "svg"])
+def test_add_artist(fig_test, fig_ref):
+    fig_test.set_dpi(100)
+    fig_ref.set_dpi(100)
+
+    ax = fig_test.subplots()
+    l1 = plt.Line2D([.2, .7], [.7, .7])
+    l2 = plt.Line2D([.2, .7], [.8, .8])
+    r1 = plt.Circle((20, 20), 100, transform=None)
+    r2 = plt.Circle((.7, .5), .05)
+    r3 = plt.Circle((4.5, .8), .55, transform=fig_test.dpi_scale_trans,
+                    facecolor='crimson')
+    for a in [l1, l2, r1, r2, r3]:
+        fig_test.add_artist(a)
+    l2.remove()
+
+    ax2 = fig_ref.subplots()
+    l1 = plt.Line2D([.2, .7], [.7, .7], transform=fig_ref.transFigure)
+    r1 = plt.Circle((20, 20), 100, transform=None, clip_on=False, zorder=20)
+    r2 = plt.Circle((.7, .5), .05, transform=fig_ref.transFigure)
+    r3 = plt.Circle((4.5, .8), .55, transform=fig_ref.dpi_scale_trans,
+                    facecolor='crimson', clip_on=False, zorder=20)
+    for a in [l1, r1, r2, r3]:
+        ax2.add_artist(a)
+
+
 @pytest.mark.skipif(sys.version_info < (3, 6), reason="requires Python 3.6+")
 @pytest.mark.parametrize("fmt", ["png", "pdf", "ps", "eps", "svg"])
 def test_fspath(fmt, tmpdir):
