@@ -0,0 +1,8 @@
+Change in the ``draw_image`` backend API
+----------------------------------------
+
+The ``draw_image`` method implemented by backends has changed its interface.
+
+This change is only relevant if the backend declares that it is able
+to transform images by returning ``True`` from ``option_scale_image``.
+See the ``draw_image`` docstring for more information.
@@ -0,0 +1,18 @@
+Improved image support
+----------------------
+
+Prior to version 2.0, matplotlib resampled images by first applying
+the color map and then resizing the result.  Since the resampling was
+performed on the colored image, this introduced colors in the output
+image that didn't actually exist in the color map.  Now, images are
+resampled first (and entirely in floating-point, if the input image is
+floating-point), and then the color map is applied.
+
+In order to make this important change, the image handling code was
+almost entirely rewritten.  As a side effect, image resampling uses
+less memory and fewer datatype conversions than before.
+
+The experimental private feature where one could "skew" an image by
+setting the private member ``_image_skew_coordinate`` has been
+removed.  Instead, images will obey the transform of the axes on which
+they are drawn.
@@ -19,10 +19,20 @@ Configuration (rcParams)
 |`svg.hashsalt`              | see note                                         |
 +----------------------------+--------------------------------------------------+
 
-``svg.hashsalt``
-````````````````
+Added ``svg.hashsalt`` key to rcParams
+```````````````````````````````````````
 
 If ``svg.hashsalt`` is ``None`` (which it is by default), the svg
 backend uses ``uuid4`` to generate the hash salt.  If it is not
 ``None``, it must be a string that is used as the hash salt instead of
 ``uuid4``.  This allows for deterministic SVG output.
+
+
+Removed the ``svg.image_noscale`` rcParam
+`````````````````````````````````````````
+
+As a result of the extensive changes to image handling, the
+``svg.image_noscale`` rcParam has been removed.  The same
+functionality may be achieved by setting ``interpolation='none'`` on
+individual images or globally using the ``image.interpolation``
+rcParam.
@@ -1,6 +1,3 @@
-#!/usr/bin/env python
-
-
 """
 For the backends that supports draw_image with optional affine
 transform (e.g., agg, ps backend), the image of the output should
@@ -24,22 +21,15 @@ def get_image():
     return Z
 
 
-def imshow_affine(ax, z, *kl, **kwargs):
-    im = ax.imshow(z, *kl, **kwargs)
-    x1, x2, y1, y2 = im.get_extent()
-    im._image_skew_coordinate = (x2, y1)
-    return im
-
-
 if 1:
 
     # image rotation
 
-    fig, (ax1, ax2) = plt.subplots(1, 2)
+    fig, ax1 = plt.subplots(1, 1)
     Z = get_image()
-    im1 = imshow_affine(ax1, Z, interpolation='none',
-                        origin='lower',
-                        extent=[-2, 4, -3, 2], clip_on=True)
+    im1 = ax1.imshow(Z, interpolation='none',
+                     origin='lower',
+                     extent=[-2, 4, -3, 2], clip_on=True)
 
     trans_data2 = mtransforms.Affine2D().rotate_deg(30) + ax1.transData
     im1.set_transform(trans_data2)
@@ -53,13 +43,3 @@ def imshow_affine(ax, z, *kl, **kwargs):
 
     ax1.set_xlim(-3, 5)
     ax1.set_ylim(-4, 4)
-
-    # image skew
-
-    im2 = ax2.imshow(Z, interpolation='none',
-                     origin='lower',
-                     extent=[-2, 4, -3, 2], clip_on=True)
-    im2._image_skew_coordinate = (3, -2)
-
-    plt.show()
-    #plt.savefig("demo_affine_image")
@@ -18,6 +18,7 @@
            'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric',
            'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos']
 
+np.random.seed(0)
 grid = np.random.rand(4, 4)
 
 fig, axes = plt.subplots(3, 6, figsize=(12, 6),
@@ -26,7 +27,7 @@
 fig.subplots_adjust(hspace=0.3, wspace=0.05)
 
 for ax, interp_method in zip(axes.flat, methods):
-    ax.imshow(grid, interpolation=interp_method)
+    ax.imshow(grid, interpolation=interp_method, cmap='viridis')
     ax.set_title(interp_method)
 
 plt.show()
@@ -48,6 +48,7 @@
 
     arr = np.arange(100).reshape((10, 10))
     im = OffsetImage(arr, zoom=2)
+    im.image.axes = ax
 
     ab = AnnotationBbox(im, xy,
                         xybox=(-50., 50.),
@@ -62,9 +63,10 @@
 
     from matplotlib._png import read_png
     fn = get_sample_data("grace_hopper.png", asfileobj=False)
-    arr_lena = read_png(fn)
+    arr_img = read_png(fn)
 
-    imagebox = OffsetImage(arr_lena, zoom=0.2)
+    imagebox = OffsetImage(arr_img, zoom=0.2)
+    imagebox.image.axes = ax
 
     ab = AnnotationBbox(imagebox, xy,
                         xybox=(120., -80.),
 
@@ -490,7 +490,7 @@ namespace agg
                     fg_ptr = (const value_type*)base_type::source().next_y();
                 }
 
-                fg >>= image_filter_shift;
+                fg = color_type::downshift(fg, image_filter_shift);
                 if(fg < 0) fg = 0;
                 if(fg > color_type::full_value()) fg = color_type::full_value();
                 span->v = (value_type)fg;
 
@@ -842,6 +842,7 @@ def matplotlib_fname():
     'savefig.extension': ('savefig.format', lambda x: x, None),
     'axes.color_cycle': ('axes.prop_cycle', lambda x: cycler('color', x),
                          lambda x: [c.get('color', None) for c in x]),
+    'svg.image_noscale': ('image.interpolation', None, None),
     }
 
 _deprecated_ignore_map = {
 
@@ -2321,15 +2321,6 @@ def draw(self, renderer=None, inframe=False):
             artists.remove(self._left_title)
             artists.remove(self._right_title)
 
-        # add images to dsu if the backend supports compositing.
-        # otherwise, does the manual compositing  without adding images to dsu.
-        if len(self.images) <= 1 or renderer.option_image_nocomposite():
-            _do_composite = False
-        else:
-            _do_composite = True
-            for im in self.images:
-                artists.remove(im)
-
         if self.figure.canvas.is_saving():
             dsu = [(a.zorder, a) for a in artists]
         else:
@@ -2354,46 +2345,12 @@ def draw(self, renderer=None, inframe=False):
         if self.axison and self._frameon:
             self.patch.draw(renderer)
 
-        if _do_composite:
-            # make a composite image, blending alpha
-            # list of (mimage.Image, ox, oy)
-
-            zorder_images = [(im.zorder, im) for im in self.images
-                             if im.get_visible()]
-            zorder_images.sort(key=lambda x: x[0])
-
-            mag = renderer.get_image_magnification()
-            ims = [(im.make_image(mag), 0, 0, im.get_alpha())
-                   for z, im in zorder_images]
-
-            l, b, r, t = self.bbox.extents
-            width = int(mag * ((np.round(r) + 0.5) - (np.round(l) - 0.5)))
-            height = int(mag * ((np.round(t) + 0.5) - (np.round(b) - 0.5)))
-            im = mimage.from_images(height,
-                                    width,
-                                    ims)
-
-            im.is_grayscale = False
-            l, b, w, h = self.bbox.bounds
-            # composite images need special args so they will not
-            # respect z-order for now
-
-            gc = renderer.new_gc()
-            gc.set_clip_rectangle(self.bbox)
-            gc.set_clip_path(mtransforms.TransformedPath(
-                self.patch.get_path(),
-                self.patch.get_transform()))
-
-            renderer.draw_image(gc, round(l), round(b), im)
-            gc.restore()
-
         if dsu_rasterized:
             for zorder, a in dsu_rasterized:
                 a.draw(renderer)
             renderer.stop_rasterizing()
 
-        for zorder, a in dsu:
-            a.draw(renderer)
+        mimage._draw_list_compositing_images(renderer, self, dsu)
 
         renderer.close_group('axes')
         self._cachedRenderer = renderer
 
@@ -515,7 +515,7 @@ def get_image_magnification(self):
         """
         return 1.0
 
-    def draw_image(self, gc, x, y, im):
+    def draw_image(self, gc, x, y, im, trans=None):
         """
         Draw the image instance into the current axes;
 
@@ -531,7 +531,14 @@ def draw_image(self, gc, x, y, im):
             is the distance from bottom
 
         *im*
-            the :class:`matplotlib._image.Image` instance
+            An NxMx4 array of RGBA pixels (of dtype uint8).
+
+        *trans*
+            If the concrete backend is written such that
+            `option_scale_image` returns `True`, an affine
+            transformation may also be passed to `draw_image`.  The
+            backend should apply the transformation to the image
+            before applying the translation of `x` and `y`.
         """
         raise NotImplementedError
Original file line number	Diff line number	Diff line change
`@@ -490,7 +490,7 @@ namespace agg`
`490`	`490`	`fg_ptr = (const value_type*)base_type::source().next_y();`
`491`	`491`	`}`
`492`	`492`
`493`		`- fg >>= image_filter_shift;`
	`493`	`+ fg = color_type::downshift(fg, image_filter_shift);`
`494`	`494`	`if(fg < 0) fg = 0;`
`495`	`495`	`if(fg > color_type::full_value()) fg = color_type::full_value();`
`496`	`496`	`span->v = (value_type)fg;`
Original file line number	Diff line number	Diff line change
`@@ -842,6 +842,7 @@ def matplotlib_fname():`
`842`	`842`	`'savefig.extension': ('savefig.format', lambda x: x, None),`
`843`	`843`	`'axes.color_cycle': ('axes.prop_cycle', lambda x: cycler('color', x),`
`844`	`844`	`lambda x: [c.get('color', None) for c in x]),`
	`845`	`+ 'svg.image_noscale': ('image.interpolation', None, None),`
`845`	`846`	`}`
`846`	`847`
`847`	`848`	`_deprecated_ignore_map = {`