Add fig.add_artist method

ImportanceOfBeingErnest · ImportanceOfBeingErnest · commit e60a0f3d35de · 2018-07-14T01:18:08.000+02:00
diff --git a/doc/users/next_whats_new/fig_add_artist_method.rst b/doc/users/next_whats_new/fig_add_artist_method.rst
@@ -0,0 +1,16 @@
+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
@@ -1045,6 +1045,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
@@ -1,5 +1,6 @@
 import sys
 import warnings
+import io
 
 from matplotlib import rcParams
 from matplotlib.testing.decorators import image_comparison
@@ -373,6 +374,34 @@ def test_figure_repr():
     assert repr(fig) == "<Figure size 100x200 with 0 Axes>"
 
 
+def test_add_artist():
+    fig, ax = plt.subplots(dpi=100)
+    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.dpi_scale_trans,
+                    facecolor='crimson')
+    for a in [l1, l2, r1, r2, r3]:
+        fig.add_artist(a)
+    l2.remove()
+    buf1 = io.BytesIO()
+    fig.savefig(buf1)
+
+    fig2, ax2 = plt.subplots(dpi=100)
+    l1 = plt.Line2D([.2, .7], [.7, .7], transform=fig2.transFigure)
+    r1 = plt.Circle((20, 20), 100, transform=None, clip_on=False, zorder=20)
+    r2 = plt.Circle((.7, .5), .05, transform=fig2.transFigure)
+    r3 = plt.Circle((4.5, .8), .55, transform=fig.dpi_scale_trans,
+                    facecolor='crimson', clip_on=False, zorder=20)
+    for a in [l1, r1, r2, r3]:
+        ax2.add_artist(a)
+    buf2 = io.BytesIO()
+    fig2.savefig(buf2)
+
+    assert buf1.getvalue() == buf2.getvalue()
+
+
 @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):
