New C++ contour code with corner_mask

CHANGELOG

@@ -1,14 +1,18 @@
+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-23 Text bounding boxes are now computed with advance width rather than
-   ink area. This may result in slightly different placement of text.
+   ink area. This may result in slightly different placement of text.
 
 2014-10-27 Allowed selection of the backend using the `MPLBACKEND` environment
  variable. Added documentation on backend selection methods.
 
 2014-09-27 Overhauled `colors.LightSource`. Added `LightSource.hillshade` to
-  allow the independent generation of illumination maps. Added new
-  types of blending for creating more visually appealing shaded relief
-  plots (e.g. `blend_mode="overlay"`, etc, in addition to the legacy
-  "hsv" mode).
+  allow the independent generation of illumination maps. Added new
+  types of blending for creating more visually appealing shaded relief
+  plots (e.g. `blend_mode="overlay"`, etc, in addition to the legacy
+  "hsv" mode).
 
 2014-06-10 Added Colorbar.remove()
 
@@ -64,7 +68,7 @@
  of a generator at line 263.
 
 2014-04-02 Added `clipon=False` to patch creation of wedges and shadows
-  in `pie`.
+  in `pie`.
 
 2014-02-25 In backend_qt4agg changed from using update -> repaint under
  windows. See comment in source near `self._priv_update` for

doc/api/api_changes/2015-02-19-IMT.rst

@@ -0,0 +1,25 @@
+Changed behaviour of contour plots
+``````````````````````````````````
+
+The default behaviour of :func:`~matplotlib.pyplot.contour` and
+:func:`~matplotlib.pyplot.contourf` when using a masked array is now determined
+by the new keyword argument `corner_mask`, or if this is not specified then
+the new rcParam `contour.corner_mask` instead. The new default behaviour is
+equivalent to using `corner_mask=True`; the previous behaviour can be obtained
+using `corner_mask=False` or by changing the rcParam. The example
+http://matplotlib.org/examples/pylab_examples/contour_corner_mask.py
+demonstrates the difference. Use of the old contouring algorithm, which is
+obtained with `corner_mask='legacy'`, is now deprecated.
+
+Contour labels may now appear in different places than in earlier versions of
+matplotlib.
+
+In addition, the keyword argument `nchunk` now applies to
+:func:`~matplotlib.pyplot.contour` as well as
+:func:`~matplotlib.pyplot.contourf`, and it subdivides the domain into
+subdomains of exactly `nchunk` by `nchunk` quads, whereas previously it was
+only roughly `nchunk` by `nchunk` quads.
+
+The C/C++ object that performs contour calculations used to be stored in the
+public attribute QuadContourSet.Cntr, but is now stored in a private attribute
+and should not be accessed by end users.

doc/users/whats_new/plotting.rst

@@ -3,3 +3,19 @@ Added center and frame kwargs to pie
 
 These control where the center of the pie graph are and if
 the Axes frame is shown.
+
+Contour plot corner masking
+```````````````````````````
+
+Ian Thomas rewrote the C++ code that calculates contours to add support for
+corner masking. This is controlled by a new keyword argument
+``corner_mask`` in the functions :func:`~matplotlib.pyplot.contour` and
+:func:`~matplotlib.pyplot.contourf`. The previous behaviour, which is now
+obtained using ``corner_mask=False``, was for a single masked point to
+completely mask out all four quads touching that point. The new behaviour,
+obtained using ``corner_mask=True``, only masks the corners of those
+quads touching the point; any triangular corners comprising three unmasked
+points are contoured as usual. If the ``corner_mask`` keyword argument is not
+specified, the default value is taken from rcParams.
+
+.. plot:: mpl_examples/pylab_examples/contour_corner_mask.py

examples/pylab_examples/contour_corner_mask.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python
+"""
+Illustrate the difference between corner_mask=False and corner_mask=True
+for masked contour plots.
+"""
+import matplotlib.pyplot as plt
+import numpy as np
+
+# Data to plot.
+x, y = np.meshgrid(np.arange(7), np.arange(10))
+z = np.sin(0.5*x)*np.cos(0.52*y)
+
+# Mask various z values.
+mask = np.zeros_like(z, dtype=np.bool)
+mask[2, 3:5] = True
+mask[3:5, 4] = True
+mask[7, 2] = True
+mask[5, 0] = True
+mask[0, 6] = True
+z = np.ma.array(z, mask=mask)
+
+corner_masks = [False, True]
+for i, corner_mask in enumerate(corner_masks):
+ plt.subplot(1, 2, i+1)
+ cs = plt.contourf(x, y, z, corner_mask=corner_mask)
+ plt.contour(cs, colors='k')
+ plt.title('corner_mask = {}'.format(corner_mask))
+
+ # Plot grid.
+ plt.grid(c='k', ls='-', alpha=0.3)
+
+ # Indicate masked points with red circles.
+ plt.plot(np.ma.array(x, mask=~mask), y, 'ro')
+
+plt.show()

lib/matplotlib/contour.py

@@ -13,6 +13,7 @@
 import numpy as np
 from numpy import ma
 import matplotlib._cntr as _cntr
+import matplotlib._contour as _contour
 import matplotlib.path as mpath
 import matplotlib.ticker as ticker
 import matplotlib.cm as cm
@@ -989,9 +990,10 @@ def get_transform(self):
 
  def __getstate__(self):
  state = self.__dict__.copy()
- # the C object Cntr cannot currently be pickled. This isn't a big issue
- # as it is not actually used once the contour has been calculated
- state['Cntr'] = None
+ # the C object _contour_generator cannot currently be pickled. This
+ # isn't a big issue as it is not actually used once the contour has
+ # been calculated.
+ state['_contour_generator'] = None
  return state
 
  def legend_elements(self, variable_name='x', str_format=str):
@@ -1433,18 +1435,34 @@ def _process_args(self, *args, **kwargs):
  Process args and kwargs.
  """
  if isinstance(args[0], QuadContourSet):
- C = args[0].Cntr
  if self.levels is None:
  self.levels = args[0].levels
  self.zmin = args[0].zmin
  self.zmax = args[0].zmax
+ self._corner_mask = args[0]._corner_mask
+ if self._corner_mask == 'legacy':
+ contour_generator = args[0].Cntr
+ else:
+ contour_generator = args[0]._contour_generator
  else:
  x, y, z = self._contour_args(args, kwargs)
 
  _mask = ma.getmask(z)
- if _mask is ma.nomask:
+ if _mask is ma.nomask or not _mask.any():
  _mask = None
- C = _cntr.Cntr(x, y, z.filled(), _mask)
+
+ self._corner_mask = kwargs.get('corner_mask', None)
+ if self._corner_mask is None:
+ self._corner_mask = mpl.rcParams['contour.corner_mask']
+
+ if self._corner_mask == 'legacy':
+ cbook.warn_deprecated('1.5',
+ name="corner_mask='legacy'",
+ alternative='corner_mask=False or True')
+ contour_generator = _cntr.Cntr(x, y, z.filled(), _mask)
+ else:
+ contour_generator = _contour.QuadContourGenerator(
+ x, y, z.filled(), _mask, self._corner_mask, self.nchunk)
 
  t = self.get_transform()
 
@@ -1465,7 +1483,10 @@ def _process_args(self, *args, **kwargs):
  self.ax.update_datalim([(x0, y0), (x1, y1)])
  self.ax.autoscale_view(tight=True)
 
- self.Cntr = C
+ if self._corner_mask == 'legacy':
+ self.Cntr = contour_generator
+ else:
+ self._contour_generator = contour_generator
 
  def _get_allsegs_and_allkinds(self):
  """
@@ -1476,20 +1497,28 @@ def _get_allsegs_and_allkinds(self):
  lowers, uppers = self._get_lowers_and_uppers()
  allkinds = []
  for level, level_upper in zip(lowers, uppers):
- nlist = self.Cntr.trace(level, level_upper,
- nchunk=self.nchunk)
- nseg = len(nlist) // 2
- segs = nlist[:nseg]
- kinds = nlist[nseg:]
- allsegs.append(segs)
+ if self._corner_mask == 'legacy':
+ nlist = self.Cntr.trace(level, level_upper,
+ nchunk=self.nchunk)
+ nseg = len(nlist) // 2
+ vertices = nlist[:nseg]
+ kinds = nlist[nseg:]
+ else:
+ vertices, kinds = \
+ self._contour_generator.create_filled_contour(
+ level, level_upper)
+ allsegs.append(vertices)
  allkinds.append(kinds)
  else:
  allkinds = None
  for level in self.levels:
- nlist = self.Cntr.trace(level)
- nseg = len(nlist) // 2
- segs = nlist[:nseg]
- allsegs.append(segs)
+ if self._corner_mask == 'legacy':
+ nlist = self.Cntr.trace(level)
+ nseg = len(nlist) // 2
+ vertices = nlist[:nseg]
+ else:
+ vertices = self._contour_generator.create_contour(level)
+ allsegs.append(vertices)
  return allsegs, allkinds
 
  def _contour_args(self, args, kwargs):
@@ -1672,6 +1701,20 @@ def _initialize_x_y(self, z):
 
  Optional keyword arguments:
 
+ *corner_mask*: [ *True* | *False* | 'legacy' ]
+ Enable/disable corner masking, which only has an effect if *Z* is
+ a masked array. If *False*, any quad touching a masked point is
+ masked out. If *True*, only the triangular corners of quads
+ nearest those points are always masked out, other triangular
+ corners comprising three unmasked points are contoured as usual.
+ If 'legacy', the old contouring algorithm is used, which is
+ equivalent to *False* and is deprecated, only remaining whilst the
+ new algorithm is tested fully.
+
+ If not specified, the default is taken from
+ rcParams['contour.corner_mask'], which is True unless it has
+ been modified.
+
  *colors*: [ *None* | string | (mpl_colors) ]
  If *None*, the colormap specified by cmap will be used.
 
@@ -1750,6 +1793,15 @@ def _initialize_x_y(self, z):
  filled contours, the default is *True*. For line contours,
  it is taken from rcParams['lines.antialiased'].
 
+ *nchunk*: [ 0 | integer ]
+ If 0, no subdivision of the domain. Specify a positive integer to
+ divide the domain into subdomains of *nchunk* by *nchunk* quads.
+ Chunking reduces the maximum length of polygons generated by the
+ contouring algorithm which reduces the rendering workload passed
+ on to the backend and also requires slightly less RAM. It can
+ however introduce rendering artifacts at chunk boundaries depending
+ on the backend, the *antialiased* flag and value of *alpha*.
+
  contour-only keyword arguments:
 
  *linewidths*: [ *None* | number | tuple of numbers ]
@@ -1774,13 +1826,6 @@ def _initialize_x_y(self, z):
 
  contourf-only keyword arguments:
 
- *nchunk*: [ 0 | integer ]
- If 0, no subdivision of the domain. Specify a positive integer to
- divide the domain into subdomains of roughly *nchunk* by *nchunk*
- points. This may never actually be advantageous, so this option may
- be removed. Chunking introduces artifacts at the chunk boundaries
- unless *antialiased* is *False*.
-
  *hatches*:
  A list of cross hatch patterns to use on the filled areas.
  If None, no hatching will be added to the contour.
@@ -1802,4 +1847,6 @@ def _initialize_x_y(self, z):
  .. plot:: mpl_examples/pylab_examples/contour_demo.py
 
  .. plot:: mpl_examples/pylab_examples/contourf_demo.py
+
+ .. plot:: mpl_examples/pylab_examples/contour_corner_mask.py
  """

lib/matplotlib/rcsetup.py

@@ -389,6 +389,13 @@ def validate_negative_linestyle_legacy(s):
  return (0, dashes) # (offset, (solid, blank))
 
 
+def validate_corner_mask(s):
+ if s == 'legacy':
+ return s
+ else:
+ return validate_bool(s)
+
+
 def validate_tkpythoninspect(s):
  # Introduced 2010/07/05
  warnings.warn("tk.pythoninspect is obsolete, and has no effect")
@@ -589,8 +596,10 @@ def __call__(self, s):
  'image.origin': ['upper', six.text_type], # lookup table
  'image.resample': [False, validate_bool],
 
+ # contour props
  'contour.negative_linestyle': ['dashed',
  validate_negative_linestyle_legacy],
+ 'contour.corner_mask': [True, validate_corner_mask],
 
  # axes props
  'axes.axisbelow': [False, validate_bool],