adds documentation and example plots

bastibe · bastibe · commit 600127415121 · 2018-05-09T10:05:48.000+02:00
diff --git a/tutorials/colors/colormaps.py b/tutorials/colors/colormaps.py
@@ -56,7 +56,12 @@
    middle value, such as topography or when the data deviates around
    zero.
 
-3. Qualitative: often are miscellaneous colors; should be used to
+3. Wrapping: change in lightness of two different colors that meet in
+   the middle and beginning/end at an unsaturated color; should be
+   used for values that wrap around at the endpoints, such as phase
+   angle, wind direction, or time of day.
+
+4. Qualitative: often are miscellaneous colors; should be used to
    represent information which does not have ordering or
    relationships.
 """
@@ -124,6 +129,26 @@
             'PiYG', 'PRGn', 'BrBG', 'PuOr', 'RdGy', 'RdBu',
             'RdYlBu', 'RdYlGn', 'Spectral', 'coolwarm', 'bwr', 'seismic']
 
+###############################################################################
+# Wrapping
+# --------
+#
+# For Wrapping maps, we want to start and end on the same color, and meet a
+# symmetric center point in the middle. :math:`L^*` should change monotonically
+# from start to middle, and inversely from middle to end. It should be symmetric
+# on the increasing and decreasing side, and only differ in hue. At the ends and
+# middle, :math:`L^*` will reverse direction, which should be smoothed in
+# :math:`L^*` space to reduce artifacts. See [kovesi-colormaps]_ for more
+# information on the design of wrapping maps.
+#
+# The often-used HSV colormap is included in this set of colormaps, although it
+# is not symmetric to a center point. Additionally, the :math:`L^*` values vary
+# widely throughout the colormap, making it a poor choice for representing data
+# for viewers to see perceptually. See an extension on this idea at
+# [mycarta-jet]_.
+
+cmaps['Wrapping'] = ['twilight', 'sunlight', 'hsv']
+
 ###############################################################################
 # Qualitative
 # -----------
@@ -158,7 +183,7 @@
 
 cmaps['Miscellaneous'] = [
             'flag', 'prism', 'ocean', 'gist_earth', 'terrain', 'gist_stern',
-            'gnuplot', 'gnuplot2', 'CMRmap', 'cubehelix', 'brg', 'hsv',
+            'gnuplot', 'gnuplot2', 'CMRmap', 'cubehelix', 'brg',
             'gist_rainbow', 'rainbow', 'jet', 'nipy_spectral', 'gist_ncar']
 
 ###############################################################################
@@ -206,13 +231,13 @@ def plot_color_gradients(cmap_category, cmap_list, nrows):
 
 # Number of colormap per subplot for particular cmap categories
 _DSUBS = {'Perceptually Uniform Sequential': 5, 'Sequential': 6,
-          'Sequential (2)': 6, 'Diverging': 6, 'Qualitative': 4,
-          'Miscellaneous': 6}
+          'Sequential (2)': 6, 'Diverging': 6, 'Wrapping': 3,
+          'Qualitative': 4, 'Miscellaneous': 6}
 
 # Spacing between the colormaps of a subplot
 _DC = {'Perceptually Uniform Sequential': 1.4, 'Sequential': 0.7,
-       'Sequential (2)': 1.4, 'Diverging': 1.4, 'Qualitative': 1.4,
-       'Miscellaneous': 1.4}
+       'Sequential (2)': 1.4, 'Diverging': 1.4, 'Wrapping': 1.4,
+       'Qualitative': 1.4, 'Miscellaneous': 1.4}
 
 # Indices to step through colormap
 x = np.linspace(0.0, 1.0, 100)
@@ -388,6 +413,7 @@ def plot_color_gradients(cmap_category, cmap_list):
 # .. [list-colormaps] https://gist.github.com/endolith/2719900#id7
 # .. [mycarta-banding] https://mycarta.wordpress.com/2012/10/14/the-rainbow-is-deadlong-live-the-rainbow-part-4-cie-lab-heated-body/
 # .. [mycarta-jet] https://mycarta.wordpress.com/2012/10/06/the-rainbow-is-deadlong-live-the-rainbow-part-3/
+# .. [kovesi-colormaps] https://arxiv.org/abs/1509.03700
 # .. [bw] http://www.tannerhelland.com/3643/grayscale-image-algorithm-vb6/
 # .. [colorblindness] http://www.color-blindness.com/
 # .. [vischeck] http://www.vischeck.com/vischeck/
