Add a sketch path filter.

Author: mdboom

lib/matplotlib/artist.py

@@ -101,6 +101,7 @@ def __init__(self):
         self._url = None
         self._gid = None
         self._snap = None
+        self._sketch = rcParams['path.sketch']
 
     def __getstate__(self):
         d = self.__dict__.copy()
@@ -456,6 +457,42 @@ def set_snap(self, snap):
         """
         self._snap = snap
 
+    def get_sketch_params(self):
+        """
+        Returns the sketch parameters, which is a tuple with three elements:
+
+          * *scale*: The amplitude of the wiggle perpendicular to the
+            source line.
+
+          * *length*: The length of the wiggle along the line.
+
+          * *randomness*: The scale factor by which the length is
+            shrunken or expanded.
+
+        May return `None` if no sketch parameters were set.
+        """
+        return self._sketch
+
+    def set_sketch_params(self, scale=None, length=None, randomness=None):
+        """
+        Sets the the sketch parameters:
+
+          * *scale*: The amplitude of the wiggle perpendicular to the
+            source line, in pixels.
+
+          * *length*: The length of the wiggle along the line, in
+             pixels (default 128.0)
+
+          * *randomness*: The scale factor by which the length is
+            shrunken or expanded (default 16.0)
+
+        If *scale* is None, no wiggling will be set.
+        """
+        if scale is None:
+            self._sketch = None
+        else:
+            self._sketch = (scale, length or 128.0, randomness or 16.0)
+
     def get_figure(self):
         """
         Return the :class:`~matplotlib.figure.Figure` instance the

lib/matplotlib/backend_bases.py

@@ -701,6 +701,7 @@ def __init__(self):
         self._url = None
         self._gid = None
         self._snap = None
+        self._sketch = None
 
     def copy_properties(self, gc):
         'Copy properties from gc to self'
@@ -1003,6 +1004,42 @@ def get_hatch_path(self, density=6.0):
             return None
         return Path.hatch(self._hatch, density)
 
+    def get_sketch_params(self):
+        """
+        Returns the sketch parameters, which is a tuple with three elements:
+
+          * *scale*: The amplitude of the wiggle perpendicular to the
+            source line.
+
+          * *length*: The length of the wiggle along the line.
+
+          * *randomness*: The scale factor by which the length is
+            shrunken or expanded.
+
+        May return `None` if no sketch parameters were set.
+        """
+        return self._sketch
+
+    def set_sketch_params(self, scale=None, length=None, randomness=None):
+        """
+        Sets the the sketch parameters:
+
+          * *scale*: The amplitude of the wiggle perpendicular to the
+            source line.
+
+          * *length*: The length of the wiggle along the line, in
+             pixels.
+
+          * *randomness*: The scale factor by which the length is
+            shrunken or expanded, in pixels.
+
+        If *scale* is None, no wiggling will be set.
+        """
+        if scale is None:
+            self._sketch = None
+        else:
+            self._sketch = (scale, length or 128.0, randomness or 16.0)
+
 
 class TimerBase(object):
     '''

lib/matplotlib/backends/backend_pdf.py

@@ -1313,11 +1313,12 @@ def writePathCollectionTemplates(self):
             self.endStream()
 
     @staticmethod
-    def pathOperations(path, transform, clip=None, simplify=None):
+    def pathOperations(path, transform, clip=None, simplify=None, sketch=None):
         cmds = []
         last_points = None
         for points, code in path.iter_segments(transform, clip=clip,
-                                               simplify=simplify):
+                                               simplify=simplify,
+                                               sketch=sketch):
             if code == Path.MOVETO:
                 # This is allowed anywhere in the path
                 cmds.extend(points)
@@ -1340,14 +1341,15 @@ def pathOperations(path, transform, clip=None, simplify=None):
             last_points = points
         return cmds
 
-    def writePath(self, path, transform, clip=False):
+    def writePath(self, path, transform, clip=False, sketch=None):
         if clip:
             clip = (0.0, 0.0, self.width * 72, self.height * 72)
             simplify = path.should_simplify
         else:
             clip = None
             simplify = False
-        cmds = self.pathOperations(path, transform, clip, simplify=simplify)
+        cmds = self.pathOperations(path, transform, clip, simplify=simplify,
+                                   sketch=sketch)
         self.output(*cmds)
 
     def reserveObject(self, name=''):
@@ -1526,7 +1528,8 @@ def draw_path(self, gc, path, transform, rgbFace=None):
         self.check_gc(gc, rgbFace)
         self.file.writePath(
             path, transform,
-            rgbFace is None and gc.get_hatch_path() is None)
+            rgbFace is None and gc.get_hatch_path() is None,
+            gc.get_sketch_params())
         self.file.output(self.gc.paint())
 
     def draw_path_collection(self, gc, master_transform, paths, all_transforms,

lib/matplotlib/collections.py

@@ -260,6 +260,9 @@ def draw(self, renderer):
         if self._hatch:
             gc.set_hatch(self._hatch)
 
+        if self.get_sketch_params() is not None:
+            gc.set_sketch_params(*self.get_sketch_params())
+
         if self.get_path_effects():
             #from patheffects import PathEffectsRenderer
             for pe in self.get_path_effects():

lib/matplotlib/lines.py

@@ -545,6 +545,8 @@ def draw(self, renderer):
         gc.set_joinstyle(join)
         gc.set_capstyle(cap)
         gc.set_snap(self.get_snap())
+        if self.get_sketch_params() is not None:
+            gc.set_sketch_params(*self.get_sketch_params())
 
         funcname = self._lineStyles.get(self._linestyle, '_draw_nothing')
         if funcname != '_draw_nothing':

lib/matplotlib/patches.py

@@ -426,6 +426,9 @@ def draw(self, renderer):
         if self._hatch:
             gc.set_hatch(self._hatch)
 
+        if self.get_sketch_params() is not None:
+            gc.set_sketch_params(*self.get_sketch_params())
+
         path = self.get_path()
         transform = self.get_transform()
         tpath = transform.transform_path_non_affine(path)
@@ -4014,6 +4017,9 @@ def draw(self, renderer):
         if self._hatch:
             gc.set_hatch(self._hatch)
 
+        if self.get_sketch_params() is not None:
+            gc.set_sketch_params(*self.get_sketch_params())
+
         # FIXME : dpi_cor is for the dpi-dependecy of the
         # linewidth. There could be room for improvement.
         #

lib/matplotlib/path.py

@@ -199,7 +199,7 @@ def __len__(self):
 
     def iter_segments(self, transform=None, remove_nans=True, clip=None,
                       snap=False, stroke_width=1.0, simplify=None,
-                      curves=True):
+                      curves=True, sketch=None):
         """
         Iterates over all of the curve segments in the path.  Each
         iteration returns a 2-tuple (*vertices*, *code*), where
@@ -233,6 +233,10 @@ def iter_segments(self, transform=None, remove_nans=True, clip=None,
         *curves*: If True, curve segments will be returned as curve
          segments.  If False, all curves will be converted to line
          segments.
+
+        *sketch*: If not None, must be a 3-tuple of the form
+         (scale, length, randomness), representing the sketch
+         parameters.
         """
         vertices = self.vertices
         if not len(vertices):
@@ -247,7 +251,8 @@ def iter_segments(self, transform=None, remove_nans=True, clip=None,
         STOP         = self.STOP
 
         vertices, codes = cleanup_path(self, transform, remove_nans, clip,
-                                       snap, stroke_width, simplify, curves)
+                                       snap, stroke_width, simplify, curves,
+                                       sketch)
         len_vertices = len(vertices)
 
         i = 0

lib/matplotlib/rcsetup.py

@@ -426,6 +426,16 @@ def validate_bbox(s):
             return None
         raise ValueError("bbox should be 'tight' or 'standard'")
 
+def validate_sketch(s):
+    if s == 'None' or s is None:
+        return None
+    if isinstance(s, basestring):
+        result = tuple([float(v.strip()) for v in s.split(',')])
+    elif isinstance(s, (list, tuple)):
+        result = tuple([float(v) for v in s])
+    if len(result) != 3:
+        raise ValueError("path.sketch must be a tuple (scale, length, randomness)")
+    return result
 
 class ValidateInterval:
     """
@@ -741,6 +751,7 @@ def __call__(self, s):
     'path.simplify_threshold': [1.0 / 9.0, ValidateInterval(0.0, 1.0)],
     'path.snap': [True, validate_bool],
     'agg.path.chunksize': [0, validate_int],       # 0 to disable chunking;
+    'path.sketch': [None, validate_sketch],
                                                     # recommend about 20000 to
                                                     # enable. Experimental.
     # key-mappings (multi-character mappings should be a list/tuple)

matplotlibrc.template

@@ -358,6 +358,13 @@ text.hinting_factor : 8 # Specifies the amount of softness for hinting in the
 #path.snap : True # When True, rectilinear axis-aligned paths will be snapped to
                   # the nearest pixel when certain criteria are met.  When False,
                   # paths will never be snapped.
+#path.sketch : None # May be none, or a 3-tuple of the form (scale, length,
+                    # randomness).
+                    # *scale* is the amplitude of the wiggle
+                    # perpendicular to the line (in pixels).  *length*
+                    # is the length of the wiggle along the line (in
+                    # pixels).  *randomness* is the factor by which
+                    # the length is randomly scaled.
 
 # the default savefig params can be different from the display params
 # e.g., you may want a higher resolution, or to make the figure

src/_backend_agg.cpp

@@ -205,6 +205,7 @@ GCAgg::GCAgg(const Py::Object &gc, double dpi) :
     _set_clip_path(gc);
     _set_snap(gc);
     _set_hatch_path(gc);
+    _set_sketch_params(gc);
 }
 
 
@@ -375,6 +376,24 @@ GCAgg::_set_hatch_path(const Py::Object& gc)
         throw Py::Exception();
 }
 
+void
+GCAgg::_set_sketch_params(const Py::Object& gc)
+{
+    _VERBOSE("GCAgg::_get_sketch_params");
+
+    Py::Object method_obj = gc.getAttr("get_sketch_params");
+    Py::Callable method(method_obj);
+    Py::Object result = method.apply(Py::Tuple());
+    if (result.ptr() == Py_None) {
+        sketch_scale = 0.0;
+    } else {
+        Py::Tuple sketch_params(result);
+        sketch_scale = Py::Float(sketch_params[0]);
+        sketch_length = Py::Float(sketch_params[1]);
+        sketch_randomness = Py::Float(sketch_params[2]);
+    }
+}
+
 
 const size_t
 RendererAgg::PIXELS_PER_INCH(96);
@@ -1397,6 +1416,7 @@ RendererAgg::draw_path(const Py::Tuple& args)
     typedef PathSnapper<clipped_t>             snapped_t;
     typedef PathSimplifier<snapped_t>          simplify_t;
     typedef agg::conv_curve<simplify_t>        curve_t;
+    typedef Sketch<curve_t>                    sketch_t;
 
     _VERBOSE("RendererAgg::draw_path");
     args.verify_length(3, 4);
@@ -1430,10 +1450,11 @@ RendererAgg::draw_path(const Py::Tuple& args)
     snapped_t          snapped(clipped, gc.snap_mode, path.total_vertices(), snapping_linewidth);
     simplify_t         simplified(snapped, simplify, path.simplify_threshold());
     curve_t            curve(simplified);
+    sketch_t           sketch(curve, gc.sketch_scale, gc.sketch_length, gc.sketch_randomness);
 
     try
     {
-        _draw_path(curve, has_clippath, face, gc);
+        _draw_path(sketch, has_clippath, face, gc);
     }
     catch (const char* e)
     {
@@ -2102,7 +2123,6 @@ RendererAgg::write_rgba(const Py::Tuple& args)
         if ((py_file = npy_PyFile_OpenFile(py_fileobj.ptr(), (char *)"wb")) == NULL) {
             throw Py::Exception();
         }
-        close_file = true;
     }
     else
     {