New QuiverKey class and quiverkey function; deprecated quiver_classic.

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

Author: efiring

CHANGELOG

@@ -1,4 +1,12 @@
-2006-06-11 Fixed a usetex bug for windows, running latex on files 
+2006-06-11 Added quiverkey command to pylab and Axes, using
+           QuiverKey class in quiver.py.  Changed pylab and Axes
+           to use quiver2 if possible, but drop back to the
+           newly-renamed quiver_classic if necessary.  Modified
+           examples/quiver_demo.py to illustrate the new quiver
+           and quiverkey.  Changed LineCollection implementation
+           slightly to improve compatibility with PolyCollection. - EF
+
+2006-06-11 Fixed a usetex bug for windows, running latex on files
            with spaces in their names or paths was failing - DSD
 
 2006-06-09 Made additions to numerix, changes to quiver to make it

boilerplate.py

@@ -84,6 +84,7 @@ def %(func)s(*args, **kwargs):
     'vlines',
     'quiver',
     'quiver2',
+    'quiverkey',
     )
 
 _misccommands = (
@@ -103,6 +104,7 @@ def %(func)s(*args, **kwargs):
     'imshow'  : 'gci._current = ret',
     'spy2'    : 'gci._current = ret',
     'quiver2' : 'gci._current = ret',
+    'quiver' : 'gci._current = ret',
     'specgram'  : 'gci._current = ret[-1]',
 
 }

examples/quiver2_demo.py

@@ -1,25 +1,69 @@
+'''
+Demonstration of quiver and quiverkey functions. This is using the
+new version coming from the code in quiver.py.
 
+Known problem: the plot autoscaling does not take into account
+the arrows, so those on the boundaries are often out of the picture.
+This is *not* an easy problem to solve in a perfectly general way.
+The workaround is to manually expand the axes.
+
+'''
 from pylab import *
 
 X,Y = meshgrid( arange(0,2*pi,.2),arange(0,2*pi,.2) )
 U = cos(X)
 V = sin(Y)
 
+#1
 figure()
-quiver( X, Y, U, V, 0.2, color='length')
+Q = quiver( U, V)
+qk = quiverkey(Q, 0.5, 0.92, 2, '2 m/s', labelpos='W',
+                    fontproperties={'weight': 'bold'})
+l,r,b,t = axis()
+dx, dy = r-l, t-b
+axis([l-0.05*dx, r+0.05*dx, b-0.05*dy, t+0.05*dy])
+
+title('Minimal arguments, no kwargs')
 
+#2
 figure()
-quiver( U, V, 0.8, color='r' )
+Q = quiver( X, Y, U, V, units='width')
+qk = quiverkey(Q, 0.9, 0.95, 2, '2 m/s',
+                            labelpos='E',
+                            coordinates='figure',
+                            fontproperties={'weight': 'bold'})
+axis([-1, 7, -1, 7])
+title('scales with plot width, not view')
 
+#3
 figure()
-quiver( U, V)
-title('quiver(U,V)')
+Q = quiver( X[::3, ::3], Y[::3, ::3], U[::3, ::3], V[::3, ::3],
+            pivot='mid', color='r', units='inches' )
+qk = quiverkey(Q, 0.5, 0.03, 1, '1 m/s', fontproperties={'weight': 'bold'})
+plot( X[::3, ::3], Y[::3, ::3], 'k.')
+axis([-1, 7, -1, 7])
+title("pivot='mid'; every third arrow; units='inches'")
 
+#4
 figure()
-quiver( U, V, color=U+V )
+M = sqrt(pow(U, 2) + pow(V, 2))
+Q = quiver( X, Y, U, V, M, units='x', pivot='tip', width=0.022, scale=1/0.15)
+qk = quiverkey(Q, 0.9, 1.05, 1, '1 m/s',
+                            labelpos='E',
+                            fontproperties={'weight': 'bold'})
+plot(X, Y, 'k.')
+axis([-1, 7, -1, 7])
+title("scales with x view; pivot='tip'")
 
+#5
 figure()
-quiver( X, Y, U, V )
-title('quiver(X,Y,U,V); needs a scale parameter')
+Q = quiver( X[::3, ::3], Y[::3, ::3], U[::3, ::3], V[::3, ::3],
+             color='r', units='x',
+            linewidths=(2,), edgecolors=('k'), headaxislength=5 )
+qk = quiverkey(Q, 0.5, 0.03, 1, '1 m/s', fontproperties={'weight': 'bold'})
+axis([-1, 7, -1, 7])
+title("triangular head; scale with x view; black edges")
+
+
 show()
 

examples/quiver_demo.py

@@ -16,7 +16,8 @@
 from cbook import iterable, is_string_like, flatten, enumerate, \
      allequal, dict_delall, popd, popall, silent_list
 from collections import RegularPolyCollection, PolyCollection, LineCollection, QuadMesh
-from colors import colorConverter, normalize, Colormap, LinearSegmentedColormap, looks_like_color
+from colors import colorConverter, normalize, Colormap, \
+        LinearSegmentedColormap, looks_like_color, is_color_like
 import cm
 from cm import ScalarMappable
 from contour import ContourSet
@@ -43,7 +44,7 @@
 from transforms import PBox
 from font_manager import FontProperties
 
-from quiver import Quiver
+from quiver import Quiver, QuiverKey
 
 import matplotlib
 
@@ -3201,6 +3202,12 @@ def arrow(self, x, y, dx, dy, **kwargs):
         self.add_artist(a)
         return a
 
+    def quiverkey(self, *args, **kw):
+        qk = QuiverKey(*args, **kw)
+        self.add_artist(qk)
+        return qk
+    quiverkey.__doc__ = QuiverKey.quiverkey_doc
+
     def quiver2(self, *args, **kw):
         q = Quiver(self, *args, **kw)
         self.add_collection(q)
@@ -3209,7 +3216,21 @@ def quiver2(self, *args, **kw):
         return q
     quiver2.__doc__ = Quiver.quiver_doc
 
-    def quiver(self, U, V, *args, **kwargs ):
+    def quiver(self, *args, **kw):
+        if (len(args) == 3 or len(args) == 5) and not iterable(args[-1]):
+            return self.quiver_classic(*args, **kw)
+        c = kw.get('color', None)
+        if c is not None:
+            try:
+                if not is_color_like(c):
+                    assert shape(asarray(c)) == shape(asarray(args[-1]))
+                    return self.quiver_classic(*args, **kw)
+            except:
+                pass
+        return self.quiver2(*args, **kw)
+    quiver.__doc__ = Quiver.quiver_doc
+
+    def quiver_classic(self, U, V, *args, **kwargs ):
         """
         QUIVER( X, Y, U, V )
         QUIVER( U, V )
@@ -3238,6 +3259,10 @@ def quiver(self, U, V, *args, **kwargs ):
 
 
         """
+        msg = '''This version of quiver is obsolete and will be
+        phased out; please use the new quiver.
+        '''
+        warnings.warn(msg, DeprecationWarning)
         if not self._hold: self.cla()
         do_scale = True
         S = 1.0

lib/matplotlib/axes.py

@@ -379,7 +379,7 @@ class LineCollection(Collection, ScalarMappable):
     the len of props is less than the number of sements
     """
     zorder = 2
-    def __init__(self, segments,
+    def __init__(self, segments,     # Can be None.
                  linewidths    = None,
                  colors        = None,
                  antialiaseds  = None,
@@ -436,21 +436,31 @@ def __init__(self, segments,
         if antialiaseds is None :
             antialiaseds = (rcParams['lines.antialiased'], )
 
-        self._segments = list(segments)
         self._colors = colorConverter.to_rgba_list(colors)
         self._aa = antialiaseds
         self._lw = linewidths
         self.set_linestyle(linestyle)
+        self._uniform_offsets = None
         if transOffset is None:
             if offsets is not None:
-                self._add_offsets(offsets)
+                self._uniform_offsets = offsets
                 offsets = None
             transOffset = identity_transform()
         self._offsets = offsets
         self._transOffset = transOffset
+        self.set_segments(segments)
+
+    def set_segments(self, segments):
+        if segments is None: return
+        self._segments = list(segments)
+        if self._uniform_offsets is not None:
+            self._add_offsets()
+
+    set_verts = set_segments # for compatibility with PolyCollection
 
-    def _add_offsets(self, offsets):
+    def _add_offsets(self):
         segs = self._segments
+        offsets = self._uniform_offsets
         Nsegs = len(segs)
         Noffs = len(offsets)
         if not iterable(offsets[0]):  # i.e., not a tuple but an x-offset

lib/matplotlib/collections.py

@@ -391,6 +391,8 @@ def to_rgb(self, arg, warn=True):
             arg = tuple(arg)
             try: self.cache[arg]
             except KeyError: pass
+            except TypeError:
+                raise ValueError('to_rgb: unhashable even inside a tuple')
 
         try:
             if is_string_like(arg):

lib/matplotlib/colors.py

@@ -2265,7 +2265,7 @@ def quiver(*args, **kwargs):
     except:
         hold(b)
         raise
-
+    gci._current = ret
     hold(b)
     return ret
 if Axes.quiver.__doc__ is not None:
@@ -2293,6 +2293,27 @@ def quiver2(*args, **kwargs):
     quiver2.__doc__ = _shift_string(Axes.quiver2.__doc__) + """
 Addition kwargs: hold = [True|False] overrides default hold state"""
 
+# This function was autogenerated by boilerplate.py.  Do not edit as
+# changes will be lost
+def quiverkey(*args, **kwargs):
+    # allow callers to override the hold state by passing hold=True|False
+    b = ishold()
+    h = popd(kwargs, 'hold', None)
+    if h is not None:
+        hold(h)
+    try:
+        ret =  gca().quiverkey(*args, **kwargs)
+        draw_if_interactive()
+    except:
+        hold(b)
+        raise
+
+    hold(b)
+    return ret
+if Axes.quiverkey.__doc__ is not None:
+    quiverkey.__doc__ = _shift_string(Axes.quiverkey.__doc__) + """
+Addition kwargs: hold = [True|False] overrides default hold state"""
+
 # This function was autogenerated by boilerplate.py.  Do not edit as
 # changes will be lost
 def cla(*args, **kwargs):
@@ -2526,3 +2547,4 @@ def winter():
 
 
 
+