pyplot tracks current image at the figure and axes level;

fixes ticket 1656374

svn path=/trunk/matplotlib/; revision=7494

Author: efiring

CHANGELOG

@@ -1,3 +1,6 @@
+2009-08-15 Pyplot interface: the current image is now tracked at the
+           figure and axes level, addressing tracker item 1656374. - EF
+
 2009-08-15 Docstrings are now manipulated with decorators defined
            in a new module, docstring.py, thanks to Jason Coombs. - EF
 

boilerplate.py

@@ -1,5 +1,5 @@
 # Wrap the plot commands defined in axes.  The code generated by this
-# file is pasted into pylab.py.  We did try to do this the smart way,
+# file is pasted into pyplot.py.  We did try to do this the smart way,
 # with callable functions and new.function, but could never get the
 # docstrings right for python2.2.  See
 # http://groups.google.com/group/comp.lang.python/browse_frm/thread/dcd63ec13096a0f6/1b14640f3a4ad3dc?#1b14640f3a4ad3dc
@@ -13,7 +13,7 @@
 import types
 
 # import the local copy of matplotlib, not the installed one
-sys.path.insert(0, './lib')
+#sys.path.insert(0, './lib')
 from matplotlib.axes import Axes
 from matplotlib.cbook import dedent
 
@@ -104,16 +104,16 @@ def %(func)s(%(argspec)s):
     )
 
 cmappable = {
-    'contour' : 'if %(ret)s._A is not None: gci._current = %(ret)s',
-    'contourf': 'if %(ret)s._A is not None: gci._current = %(ret)s',
-    'hexbin' : 'gci._current = %(ret)s',
-    'scatter' : 'gci._current = %(ret)s',
-    'pcolor'  : 'gci._current = %(ret)s',
-    'pcolormesh'  : 'gci._current = %(ret)s',
-    'imshow'  : 'gci._current = %(ret)s',
-    'spy'    : 'gci._current = %(ret)s',
-    'quiver' : 'gci._current = %(ret)s',
-    'specgram'  : 'gci._current = %(ret)s[-1]',
+    'contour' : 'if %(ret)s._A is not None: sci(%(ret)s)',
+    'contourf': 'if %(ret)s._A is not None: sci(%(ret)s)',
+    'hexbin' :  'sci(%(ret)s)',
+    'scatter' : 'sci(%(ret)s)',
+    'pcolor'  : 'sci(%(ret)s)',
+    'pcolormesh': 'sci(%(ret)s)',
+    'imshow'  : 'sci(%(ret)s)',
+    'spy'    :  'sci(%(ret)s)',
+    'quiver' :  'sci(%(ret)s)',
+    'specgram'  : 'sci(%(ret)s[-1])',
 
 }
 
@@ -233,3 +233,4 @@ def %(name)s():
 # add all the colormaps (autumn, hsv, ....)
 for name in cmaps:
     print _fmtcmap%locals()
+

examples/pylab_examples/multi_image.py

@@ -5,7 +5,7 @@
 It also illustrates colorbar tick labelling with a multiplier.
 '''
 
-from matplotlib.pyplot import figure, show, sci
+from matplotlib.pyplot import figure, show, axes, sci
 from matplotlib import cm, colors
 from matplotlib.font_manager import FontProperties
 from numpy import amin, amax, ravel
@@ -68,9 +68,11 @@ def __call__(self, leader):
 # The colorbar is also based on this master image.
 fig.colorbar(images[0], cax, orientation='horizontal')
 
-# We need the following only if we want to run this
+# We need the following only if we want to run this interactively and
+# modify the colormap:
 
-sci(images[0])
+axes(ax[0])     # Return the current axes to the first one,
+sci(images[0])  # because the current image must be in current axes.
 
 show()
 

lib/matplotlib/axes.py

@@ -838,6 +838,7 @@ def cla(self):
         self.tables = []
         self.artists = []
         self.images = []
+        self._current_image = None # strictly for pyplot via _sci, _gci
         self.legend_ = None
         self.collections = []  # collection.Collection instances
 
@@ -1309,6 +1310,27 @@ def get_yticklines(self):
 
     #### Adding and tracking artists
 
+    def _sci(self, im):
+        """
+        helper for :func:`~matplotlib.pyplot.sci`;
+        do not use elsewhere.
+        """
+        if isinstance(im, matplotlib.contour.ContourSet):
+            if im.collections[0] not in self.collections:
+                raise ValueError(
+                    "ContourSet must be in current Axes")
+        elif im not in self.images and im not in self.collections:
+            raise ValueError(
+            "Argument must be an image, collection, or ContourSet in this Axes")
+        self._current_image = im
+
+    def _gci(self):
+        """
+        helper for :func:`~matplotlib.pyplot.gci`;
+        do not use elsewhere.
+        """
+        return self._current_image
+
     def has_data(self):
         '''Return *True* if any artists have been added to axes.
 

lib/matplotlib/cbook.py

@@ -1007,7 +1007,7 @@ def __setitem__(self, k, v):
 
 
 
-class Stack:
+class Stack(object):
     """
     Implement a stack where elements can be pushed on and you can move
     back and forth.  But no pop.  Should mimic home / back / forward
@@ -1023,6 +1023,12 @@ def __call__(self):
         if not len(self._elements): return self._default
         else: return self._elements[self._pos]
 
+    def __len__(self):
+        return self._elements.__len__()
+
+    def __getitem__(self, ind):
+        return self._elements.__getitem__(ind)
+
     def forward(self):
         'move the position forward and return the current element'
         N = len(self._elements)

lib/matplotlib/figure.py

@@ -950,6 +950,17 @@ def sca(self, a):
         for func in self._axobservers: func(self)
         return a
 
+    def _gci(self):
+        """
+        helper for :func:`~matplotlib.pyplot.gci`;
+        do not use elsewhere.
+        """
+        for ax in reversed(self._axstack):
+            im = ax._gci()
+            if im is not None:
+                return im
+        return None
+
     def add_axobserver(self, func):
         'whenever the axes state change, func(self) will be called'
         self._axobservers.append(func)
@@ -1039,7 +1050,7 @@ def savefig(self, *args, **kwargs):
     def colorbar(self, mappable, cax=None, ax=None, **kw):
         """
         Create a colorbar for a ScalarMappable instance.
-        
+
         Documentation for the pylab thin wrapper:
         %(colorbar_doc)s
         """

lib/matplotlib/pyplot.py

@@ -129,8 +129,10 @@ def rcdefaults():
     matplotlib.rcdefaults()
     draw_if_interactive()
 
-# The current "image" (ScalarMappable) is tracked here on a
-# per-pylab-session basis:
+# The current "image" (ScalarMappable) is retrieved or set
+# only via the pyplot interface using the following two
+# functions:
+
 def gci():
     """
     Get the current :class:`~matplotlib.cm.ScalarMappable` instance
@@ -142,18 +144,20 @@ def gci():
     :func:`~matplotlib.pyplot.pcolor` and
     :func:`~matplotlib.pyplot.scatter` create
     :class:`~matplotlib.collections.Collection` instances.
+    The current image is an attribute of the current axes, or the
+    nearest earlier axes in the current figure that contains an
+    image.
     """
-    return gci._current
-gci._current = None
-
+    return gcf()._gci()
 
 def sci(im):
     """
     Set the current image (target of colormap commands like
     :func:`~matplotlib.pyplot.jet`, :func:`~matplotlib.pyplot.hot` or
-    :func:`~matplotlib.pyplot.clim`).
+    :func:`~matplotlib.pyplot.clim`).  The current image is an
+    attribute of the current axes.
     """
-    gci._current = im
+    gca()._sci(im)
 
 
 ## Any Artist ##
@@ -1598,7 +1602,6 @@ def autogen_docstring(base):
 
 ## Plotting part 2: autogenerated wrappers for axes methods ##
 
-
 # This function was autogenerated by boilerplate.py.  Do not edit as
 # changes will be lost
 @autogen_docstring(Axes.acorr)
@@ -1830,7 +1833,7 @@ def contour(*args, **kwargs):
         draw_if_interactive()
     finally:
         ax.hold(washold)
-    if ret._A is not None: gci._current = ret
+    if ret._A is not None: sci(ret)
     return ret
 
 # This function was autogenerated by boilerplate.py.  Do not edit as
@@ -1848,7 +1851,7 @@ def contourf(*args, **kwargs):
         draw_if_interactive()
     finally:
         ax.hold(washold)
-    if ret._A is not None: gci._current = ret
+    if ret._A is not None: sci(ret)
     return ret
 
 # This function was autogenerated by boilerplate.py.  Do not edit as
@@ -1956,7 +1959,7 @@ def hexbin(x, y, C=None, gridsize=100, bins=None, xscale='linear', yscale='linea
         draw_if_interactive()
     finally:
         ax.hold(washold)
-    gci._current = ret
+    sci(ret)
     return ret
 
 # This function was autogenerated by boilerplate.py.  Do not edit as
@@ -2010,7 +2013,7 @@ def imshow(X, cmap=None, norm=None, aspect=None, interpolation=None, alpha=1.0,
         draw_if_interactive()
     finally:
         ax.hold(washold)
-    gci._current = ret
+    sci(ret)
     return ret
 
 # This function was autogenerated by boilerplate.py.  Do not edit as
@@ -2046,7 +2049,7 @@ def pcolor(*args, **kwargs):
         draw_if_interactive()
     finally:
         ax.hold(washold)
-    gci._current = ret
+    sci(ret)
     return ret
 
 # This function was autogenerated by boilerplate.py.  Do not edit as
@@ -2064,7 +2067,7 @@ def pcolormesh(*args, **kwargs):
         draw_if_interactive()
     finally:
         ax.hold(washold)
-    gci._current = ret
+    sci(ret)
     return ret
 
 # This function was autogenerated by boilerplate.py.  Do not edit as
@@ -2154,7 +2157,7 @@ def quiver(*args, **kw):
         draw_if_interactive()
     finally:
         ax.hold(washold)
-    gci._current = ret
+    sci(ret)
     return ret
 
 # This function was autogenerated by boilerplate.py.  Do not edit as
@@ -2190,7 +2193,7 @@ def scatter(x, y, s=20, c='b', marker='o', cmap=None, norm=None, vmin=None, vmax
         draw_if_interactive()
     finally:
         ax.hold(washold)
-    gci._current = ret
+    sci(ret)
     return ret
 
 # This function was autogenerated by boilerplate.py.  Do not edit as
@@ -2244,7 +2247,7 @@ def specgram(x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.win
         draw_if_interactive()
     finally:
         ax.hold(washold)
-    gci._current = ret[-1]
+    sci(ret[-1])
     return ret
 
 # This function was autogenerated by boilerplate.py.  Do not edit as
@@ -2262,7 +2265,7 @@ def spy(Z, precision=0, marker=None, markersize=None, aspect='equal', hold=None,
         draw_if_interactive()
     finally:
         ax.hold(washold)
-    gci._current = ret
+    sci(ret)
     return ret
 
 # This function was autogenerated by boilerplate.py.  Do not edit as
@@ -2628,3 +2631,5 @@ def spectral():
     draw_if_interactive()
 
 
+
+