Merge pull request #3061 from rhattersley/add-image

pelson · pelson · commit 4a54114946c6 · 2014-05-15T16:52:52.000+01:00
Add Axes.add_image() for consistency.
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,8 @@
+2014-05-14 Added Axes.add_image() as the standard way to add AxesImage
+           instances to Axes. This improves the consistency with
+           add_artist(), add_collection(), add_container(), add_line(),
+           add_patch(), and add_table().
+
 2014-05-02 Added colorblind-friendly colormap, named 'Wistia'.
 
 2014-04-27 Improved input clean up in Axes.{h|v}lines
diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst
@@ -166,6 +166,13 @@ Larry Bradley fixed the :func:`~matplotlib.pyplot.errorbar` method such
 that the upper and lower limits (*lolims*, *uplims*, *xlolims*,
 *xuplims*) now point in the correct direction.
 
+More consistent add-object API for Axes
+```````````````````````````````````````
+Added the Axes method :meth:`~matplotlib.axes.Axes.add_image` to put image
+handling on a par with artists, collections, containers, lines, patches,
+and tables.
+
+
 Date handling
 -------------
 
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -4537,7 +4537,6 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
 
         im.set_data(X)
         im.set_alpha(alpha)
-        self._set_artist_props(im)
         if im.get_clip_path() is None:
             # image does not already have clipping set, clip to axes patch
             im.set_clip_path(self.patch)
@@ -4553,9 +4552,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
         # to tightly fit the image, regardless of dataLim.
         im.set_extent(im.get_extent())
 
-        self.images.append(im)
-        im._remove_method = lambda h: self.images.remove(h)
-
+        self.add_image(im)
         return im
 
     @staticmethod
@@ -5202,7 +5199,7 @@ def pcolorfast(self, *args, **kwargs):
                                          **kwargs)
             im.set_data(C)
             im.set_alpha(alpha)
-            self.images.append(im)
+            self.add_image(im)
             ret = im
 
         if style == "pcolorimage":
@@ -5211,10 +5208,9 @@ def pcolorfast(self, *args, **kwargs):
                                     norm=norm,
                                     alpha=alpha,
                                     **kwargs)
-            self.images.append(im)
+            self.add_image(im)
             ret = im
 
-        self._set_artist_props(ret)
         if vmin is not None or vmax is not None:
             ret.set_clim(vmin, vmax)
         else:
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1457,6 +1457,17 @@ def add_collection(self, collection, autolim=True):
         collection._remove_method = lambda h: self.collections.remove(h)
         return collection
 
+    def add_image(self, image):
+        """
+        Add a :class:`~matplotlib.image.AxesImage` to the axes.
+
+        Returns the image.
+        """
+        self._set_artist_props(image)
+        self.images.append(image)
+        image._remove_method = lambda h: self.images.remove(h)
+        return image
+
     def add_line(self, line):
         """
         Add a :class:`~matplotlib.lines.Line2D` to the list of plot
