Updated CHANGELOG to put proposed change at the top of the list

Reverted from the 'combine_images' terminology back to the 'composite_image' terminology. With this terminology, we can keep the method name 'renderer.option_image_nocomposite()', and maintain backwards compatibility.
matplotlib · WeatherGod · Mar 6, 2015 · Feb 2, 2015 · Feb 27, 2015 · Mar 2, 2015
commit 87ba9cb1fd33a93a33ae7fb0c84f44eece042480
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,15 +1,13 @@
+2015-02-27 Added the rcParam 'image.composite_image' to permit users 
+		   to decide whether they want the vector graphics backends to combine 
+		   all images within a set of axes into a single composite image.  
+		   (If images do not get combined, users can open vector graphics files 
+		   in Adobe Illustrator or Inkscape and edit each image individually.)  
+
 2015-02-19 Rewrite of C++ code that calculates contours to add support for
            corner masking.  This is controlled by the 'corner_mask' keyword
            in plotting commands 'contour' and 'contourf'. - IMT
 
-2015-01-31 Added the rcParam 'image.combine_images' to permit users 
-		   to decide whether they want the vector graphics backends to combine 
-		   all images within a set of axes into a single image.  (If images do 
-		   not get combined, users can open vector graphics files in Adobe 
-		   Illustrator or Inkscape and edit each image individually.)  Also 
-		   changed 'renderer.option_nocomposite' to the clearer name 
-		   'renderer.option_combine_images'. 
-
 2015-01-23 Text bounding boxes are now computed with advance width rather than
            ink area.  This may result in slightly different placement of text.
 

diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -2028,13 +2028,13 @@ def draw(self, renderer=None, inframe=False):
             dsu = [(a.zorder, a) for a in artists
                    if not a.get_animated()]
 
-        # add images to dsu if the backend supports combining images.
-        # otherwise, perform manual combining, without adding images to dsu.
-        if len(self.images) <= 1 or not renderer.option_combine_images():
+        # 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():
             dsu.extend([(im.zorder, im) for im in self.images])
-            _combine_images = False
+            _do_composite = False
         else:
-            _combine_images = True
+            _do_composite = True
 
         dsu.sort(key=itemgetter(0))
 
@@ -2054,8 +2054,8 @@ def draw(self, renderer=None, inframe=False):
         if self.axison and self._frameon:
             self.patch.draw(renderer)
 
-        if _combine_images:
-            # combine images, blending alpha
+        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

diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -527,12 +527,12 @@ def draw_image(self, gc, x, y, im):
         """
         raise NotImplementedError
 
-    def option_combine_images(self):
+    def option_image_nocomposite(self):
         """
-        override this method for renderers that do not necessarily
+        override this method for renderers that do not necessarily always
         want to rescale and composite raster images. (like SVG, PDF, or PS)
         """
-        return True
+        return False
 
     def option_scale_image(self):
         """

diff --git a/lib/matplotlib/backends/backend_agg.py b/lib/matplotlib/backends/backend_agg.py
@@ -322,11 +322,11 @@ def buffer_rgba(self):
     def clear(self):
         self._renderer.clear()
 
-    def option_combine_images(self):
-        # It is generally faster to write each image directly to
-        # the Figure, and there's no file size benefit to combining images
+    def option_image_nocomposite(self):
+        # It is generally faster to composite each image directly to
+        # the Figure, and there's no file size benefit to compositing
         # with the Agg backend
-        return False
+        return True
 
     def option_scale_image(self):
         """

diff --git a/lib/matplotlib/backends/backend_macosx.py b/lib/matplotlib/backends/backend_macosx.py
@@ -170,8 +170,8 @@ def flipy(self):
     def points_to_pixels(self, points):
         return points/72.0 * self.dpi
 
-    def option_combine_images(self):
-        return False
+    def option_image_nocomposite(self):
+        return True
 
 
 class GraphicsContextMac(_macosx.GraphicsContext, GraphicsContextBase):

diff --git a/lib/matplotlib/backends/backend_mixed.py b/lib/matplotlib/backends/backend_mixed.py
@@ -63,7 +63,7 @@ def __init__(self, figure, width, height, dpi, vector_renderer,
         draw_path_collection draw_quad_mesh draw_tex draw_text
         finalize flipy get_canvas_width_height get_image_magnification
         get_texmanager get_text_width_height_descent new_gc open_group
-        option_combine_images points_to_pixels strip_math
+        option_image_nocomposite points_to_pixels strip_math
         start_filter stop_filter draw_gouraud_triangle
         draw_gouraud_triangles option_scale_image
         _text2path _get_text_path_transform height width

diff --git a/lib/matplotlib/backends/backend_pdf.py b/lib/matplotlib/backends/backend_pdf.py
@@ -1577,12 +1577,12 @@ def option_scale_image(self):
         """
         return True
 
-    def option_combine_images(self):
+    def option_image_nocomposite(self):
         """
-        return whether to combine multiple images on a set of axes into one
-        image
+        return whether to generate a composite image from multiple images on 
+        a set of axes
         """
-        return rcParams['image.combine_images']
+        return not rcParams['image.composite_image']
 
     def draw_image(self, gc, x, y, im, dx=None, dy=None, transform=None):
         self.check_gc(gc)

diff --git a/lib/matplotlib/backends/backend_ps.py b/lib/matplotlib/backends/backend_ps.py
@@ -452,12 +452,12 @@ def option_scale_image(self):
         """
         return True
 
-    def option_combine_images(self):
+    def option_image_nocomposite(self):
         """
-        return whether to combine multiple images on a set of axes into one 
-        image
+        return whether to generate a composite image from multiple images on 
+        a set of axes
         """
-        return rcParams['image.combine_images']
+        return not rcParams['image.composite_image']
 
     def _get_image_h_w_bits_command(self, im):
         if im.is_grayscale:

diff --git a/lib/matplotlib/backends/backend_svg.py b/lib/matplotlib/backends/backend_svg.py
@@ -527,15 +527,15 @@ def open_group(self, s, gid=None):
     def close_group(self, s):
         self.writer.end('g')
 
-    def option_combine_images(self):
+    def option_image_nocomposite(self):
         """
-        if svg.image_noscale is True, combining multiple images into one is 
-        prohibited
+        return whether to generate a composite image from multiple images on 
+        a set of axes
         """
         if rcParams['svg.image_noscale']:
-            return False
+            return True
         else:
-            return rcParams['image.combine_images']
+            return not rcParams['image.composite_image']
 
     def _convert_path(self, path, transform=None, clip=None, simplify=None):
         if clip:

diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1045,16 +1045,16 @@ def draw(self, renderer):
 
         # override the renderer default if self.suppressComposite
         # is not None
-        combine_images = renderer.option_combine_images()
+        not_composite = renderer.option_image_nocomposite()
         if self.suppressComposite is not None:
-            combine_images = not self.suppressComposite
+            not_composite = self.suppressComposite
 
-        if (len(self.images) <= 1 or not combine_images or
+        if (len(self.images) <= 1 or not_composite or
                 not cbook.allequal([im.origin for im in self.images])):
             for a in self.images:
                 dsu.append((a.get_zorder(), a, a.draw, [renderer]))
         else:
-            # make a combined image, blending alpha
+            # make a composite image blending alpha
             # list of (_image.Image, ox, oy)
             mag = renderer.get_image_magnification()
             ims = [(im.make_image(mag), im.ox, im.oy, im.get_alpha())
@@ -1067,15 +1067,15 @@ def draw(self, renderer):
             im.is_grayscale = False
             l, b, w, h = self.bbox.bounds
 
-            def draw_combined_image():
+            def draw_composite():
                 gc = renderer.new_gc()
                 gc.set_clip_rectangle(self.bbox)
                 gc.set_clip_path(self.get_clip_path())
                 renderer.draw_image(gc, l, b, im)
                 gc.restore()
 
             dsu.append((self.images[0].get_zorder(), self.images[0],
-                        draw_combined_image, []))
+                        draw_composite, []))
 
         # render the axes
         for a in self.axes:

diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -595,9 +595,9 @@ def __call__(self, s):
     'image.lut':           [256, validate_int],  # lookup table
     'image.origin':        ['upper', six.text_type],  # lookup table
     'image.resample':      [False, validate_bool],
-    # Force vector graphics backends to combine all images on a set of axes 
-    # into a single image
-    'image.combine_images': [True, validate_bool],
+    # Specify whether vector graphics backends will combine all images on a 
+    # set of axes into a single composite image
+    'image.composite_image': [True, validate_bool],
 
     # contour props
     'contour.negative_linestyle': ['dashed',

diff --git a/...images/test_image/image_combine_alpha.pdf → ...ages/test_image/image_composite_alpha.pdf b/...images/test_image/image_combine_alpha.pdf → ...ages/test_image/image_composite_alpha.pdf
diff --git a/...images/test_image/image_combine_alpha.png → ...ages/test_image/image_composite_alpha.png b/...images/test_image/image_combine_alpha.png → ...ages/test_image/image_composite_alpha.png
diff --git a/...images/test_image/image_combine_alpha.svg → ...ages/test_image/image_composite_alpha.svg b/...images/test_image/image_combine_alpha.svg → ...ages/test_image/image_composite_alpha.svg
diff --git a/...s/test_image/image_combine_background.pdf → ...test_image/image_composite_background.pdf b/...s/test_image/image_combine_background.pdf → ...test_image/image_composite_background.pdf
diff --git a/...s/test_image/image_combine_background.png → ...test_image/image_composite_background.png b/...s/test_image/image_combine_background.png → ...test_image/image_composite_background.png
diff --git a/...s/test_image/image_combine_background.svg → ...test_image/image_composite_background.svg b/...s/test_image/image_combine_background.svg → ...test_image/image_composite_background.svg
diff --git a/lib/matplotlib/tests/test_backend_pdf.py b/lib/matplotlib/tests/test_backend_pdf.py
@@ -89,21 +89,21 @@ def test_multipage_keep_empty():
 
 
 @cleanup
-def test_combine_images():
+def test_composite_image():
     #Test that figures can be saved with and without combining multiple images
-    #(on a single set of axes) into a single image.
+    #(on a single set of axes) into a single composite image.
     X, Y = np.meshgrid(np.arange(-5, 5, 1), np.arange(-5, 5, 1))
     Z = np.sin(Y ** 2)
     fig = plt.figure()
     ax = fig.add_subplot(1, 1, 1)
     ax.set_xlim(0, 3)
     ax.imshow(Z, extent=[0, 1, 0, 1])
     ax.imshow(Z[::-1], extent=[2, 3, 0, 1])
-    plt.rcParams['image.combine_images'] = True
+    plt.rcParams['image.composite_image'] = True
     with PdfPages(io.BytesIO()) as pdf:
         fig.savefig(pdf, format="pdf")
         assert len(pdf._file.images.keys()) == 1
-    plt.rcParams['image.combine_images'] = False
+    plt.rcParams['image.composite_image'] = False
     with PdfPages(io.BytesIO()) as pdf:
         fig.savefig(pdf, format="pdf")
         assert len(pdf._file.images.keys()) == 2
diff --git a/lib/matplotlib/tests/test_backend_ps.py b/lib/matplotlib/tests/test_backend_ps.py
@@ -87,23 +87,23 @@ def test_savefig_to_stringio_with_usetex_eps():
 
 
 @cleanup
-def test_combine_images():
+def test_composite_image():
     #Test that figures can be saved with and without combining multiple images
-    #(on a single set of axes) into a single image.
+    #(on a single set of axes) into a single composite image.
     X, Y = np.meshgrid(np.arange(-5, 5, 1), np.arange(-5, 5, 1))
     Z = np.sin(Y ** 2)
     fig = plt.figure()
     ax = fig.add_subplot(1, 1, 1)
     ax.set_xlim(0, 3)
     ax.imshow(Z, extent=[0, 1, 0, 1])
     ax.imshow(Z[::-1], extent=[2, 3, 0, 1])
-    plt.rcParams['image.combine_images'] = True
+    plt.rcParams['image.composite_image'] = True
     with io.BytesIO() as ps:
         fig.savefig(ps, format="ps")
         ps.seek(0)
         buff = ps.read()
         assert buff.count(six.b(' colorimage')) == 1
-    plt.rcParams['image.combine_images'] = False
+    plt.rcParams['image.composite_image'] = False
     with io.BytesIO() as ps:
         fig.savefig(ps, format="ps")
         ps.seek(0)

diff --git a/lib/matplotlib/tests/test_backend_svg.py b/lib/matplotlib/tests/test_backend_svg.py
@@ -56,23 +56,23 @@ def test_noscale():
 
 
 @cleanup
-def test_combine_images():
+def test_composite_images():
     #Test that figures can be saved with and without combining multiple images
-    #(on a single set of axes) into a single image.
+    #(on a single set of axes) into a single composite image.
     X, Y = np.meshgrid(np.arange(-5, 5, 1), np.arange(-5, 5, 1))
     Z = np.sin(Y ** 2)
     fig = plt.figure()
     ax = fig.add_subplot(1, 1, 1)
     ax.set_xlim(0, 3)
     ax.imshow(Z, extent=[0, 1, 0, 1])
     ax.imshow(Z[::-1], extent=[2, 3, 0, 1])
-    plt.rcParams['image.combine_images'] = True
+    plt.rcParams['image.composite_image'] = True
     with BytesIO() as svg:
         fig.savefig(svg, format="svg")
         svg.seek(0)
         buff = svg.read()
         assert buff.count(six.b('<image ')) == 1
-    plt.rcParams['image.combine_images'] = False
+    plt.rcParams['image.composite_image'] = False
     with BytesIO() as svg:
         fig.savefig(svg, format="svg")
         svg.seek(0)

diff --git a/lib/matplotlib/tests/test_image.py b/lib/matplotlib/tests/test_image.py
@@ -248,8 +248,8 @@ def test_image_edges():
 
     assert g != 100, 'Expected a non-green edge - but sadly, it was.'
 
-@image_comparison(baseline_images=['image_combine_background'], remove_text=True)
-def test_image_combine_background():
+@image_comparison(baseline_images=['image_composite_background'], remove_text=True)
+def test_image_composite_background():
     fig = plt.figure()
     ax = fig.add_subplot(111)
     arr = np.arange(12).reshape(4, 3)
@@ -258,8 +258,8 @@ def test_image_combine_background():
     ax.set_axis_bgcolor((1, 0, 0, 0.5))
     ax.set_xlim([0, 12])
 
-@image_comparison(baseline_images=['image_combine_alpha'], remove_text=True)
-def test_image_combine_alpha():
+@image_comparison(baseline_images=['image_composite_alpha'], remove_text=True)
+def test_image_composite_alpha():
     """
     Tests that the alpha value is recognized and correctly applied in the
     process of combining images together.

diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -358,8 +358,8 @@ backend      : %(backend)s
 #image.lut    : 256               # the size of the colormap lookup table
 #image.origin : upper             # lower | upper
 #image.resample  : False
-#image.combine_images : True      # When True, all the images on a set of axes 
-                                  # are combined into a single image before 
+#image.composite_image : True     # When True, all the images on a set of axes are 
+								  # combined into a single composite image before 
                                   # saving a figure as a vector graphics file, 
                                   # such as a PDF.