matplotlib · tacaswell · Jan 19, 2014 · Jan 19, 2014 · May 16, 2015 · May 16, 2015
diff --git a/doc/users/whats_new/2015-05_color_shading.rst b/doc/users/whats_new/2015-05_color_shading.rst
@@ -0,0 +1,9 @@
+Easy color shading
+``````````````````
+Often we would like the ability add subtle color variation to our plots,
+especially when similar element are plotted in close proximity to one another.
+:func:`matplotlib.colors.shade_color` can be used to take an existing color and
+slightly darken it, by giving a negative percentage, or to slightly lighten it,
+by giving a positive percentage.
+
+.. plot:: mpl_examples/color/color_shade_demo.py
diff --git a/examples/color/color_shade_demo.py b/examples/color/color_shade_demo.py
@@ -0,0 +1,21 @@
+"""
+Demo of shade_color utility.
+
+"""
+import matplotlib.pyplot as plt
+import matplotlib.colors as mcolors
+
+fig = plt.figure()
+ax = fig.add_subplot(111)
+
+lightened_color = mcolors.shade_color('blue', -50)
+darkened_color = mcolors.shade_color('blue', +50)
+
+ax.fill_between([0,1], [0,0], [1,1], facecolor=darkened_color)
+ax.fill_between([0,1], [0,0], [.66, .66], facecolor='blue')
+ax.fill_between([0,1], [0,0], [.33, .33], facecolor=lightened_color)
+
+plt.xlim([0, 1])
+plt.ylim([0, 1])
+
+plt.show()
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -64,9 +64,12 @@
 from collections import Sized
 import re
 import warnings
+from colorsys import rgb_to_hls, hls_to_rgb
+
 
 import numpy as np
 import matplotlib.cbook as cbook
+
 from ._color_data import BASE_COLORS, TABLEAU_COLORS, CSS4_COLORS, XKCD_COLORS
 
 
@@ -1947,3 +1950,38 @@ def from_levels_and_colors(levels, colors, extend='neither'):
 
     norm = BoundaryNorm(levels, ncolors=n_data_colors)
     return cmap, norm
+
+
+def shade_color(color, percent):
+    """A color helper utility to either darken or lighten given color.
+
+    This color utility function allows the user to easily darken or
+    lighten a color for plotting purposes.  This function first
+    converts the given color to RGB using ColorConverter and then to
+    HSL.  The saturation is modified according to the given percentage
+    and converted back to RGB.
+
+    Parameters
+    ----------
+    color : string, list, hexvalue
+        Any acceptable Matplotlib color value, such as 'red',
+        'slategrey', '#FFEE11', (1,0,0)
+
+    percent : the amount by which to brighten or darken the color.
+
+    Returns
+    -------
+    color : tuple of floats
+        tuple representing converted rgb values
+
+    """
+
+    rgb = colorConverter.to_rgb(color)
+
+    h, l, s = rgb_to_hls(*rgb)
+
+    l *= 1 + float(percent)/100
+
+    l = np.clip(l, 0, 1)
+
+    return hls_to_rgb(h, l, s)
diff --git a/lib/matplotlib/tests/test_colors.py b/lib/matplotlib/tests/test_colors.py
@@ -10,7 +10,8 @@
 import numpy as np
 import pytest
 
-from numpy.testing.utils import assert_array_equal, assert_array_almost_equal
+from numpy.testing.utils import (assert_array_equal,
+                                 assert_array_almost_equal, assert_equal)
 
 from matplotlib import cycler
 import matplotlib
@@ -708,3 +709,34 @@ def __add__(self, other):
                  mcolors.SymLogNorm(3, vmax=5, linscale=1),
                  mcolors.PowerNorm(1)]:
         assert_array_equal(norm(data.view(MyArray)), norm(data))
+
+
+def _shade_test_helper(color, shade, expected):
+    sc = mcolors.shade_color(color, shade)
+    assert_equal(sc, expected)
+
+
+def test_color_shading():
+    test_colors = (
+        'red',
+        'red',
+        'red',
+        'red',
+        'red',
+        [0, .5, .9],
+        'slategrey',
+    )
+    test_shade = (0, 50, 100, -50, -100, 20, -20)
+    known_shaded_result = (
+        (1.0, 0.0, 0.0),
+        (1.0, 0.5, 0.5),
+        (1.0, 1.0, 1.0),
+        (0.5, 0.0, 0.0),
+        (0.0, 0.0, 0.0),
+        (0.080000000000000071, 0.59111111111111092, 1.0),
+        (0.35097730430754981, 0.40156862745098038, 0.45215995059441105)
+    )
+    for color, shade, expected in zip(test_colors,
+                                      test_shade,
+                                      known_shaded_result):
+        _shade_test_helper(color, shade, expected)