matplotlib · efiring · May 31, 2012 · May 21, 2012 · May 21, 2012 · May 22, 2012
diff --git a/doc/users/customizing.rst b/doc/users/customizing.rst
@@ -24,7 +24,7 @@ locations, in the following order:
    is something like :file:`/usr/lib/python2.5/site-packages` on Linux, and
    maybe :file:`C:\\Python25\\Lib\\site-packages` on Windows. Every time you
    install matplotlib, this file will be overwritten, so if you want your
-   customizations to be saved, please move this file to you :file:`.matplotlib`
+   customizations to be saved, please move this file to your :file:`.matplotlib`
    directory.
 
 To display where the currently active :file:`matplotlibrc` file was

diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1645,39 +1645,232 @@ def colors():
 
 def colormaps():
     """
-    matplotlib provides the following colormaps.
-
-    * autumn
-    * bone
-    * cool
-    * copper
-    * flag
-    * gray
-    * hot
-    * hsv
-    * jet
-    * pink
-    * prism
-    * spring
-    * summer
-    * winter
-    * spectral
+    Matplotlib provides a number of colormaps, and others can be added using 
+    :func:`register_cmap`.  This function documents the built-in colormaps, 
+    and will also return a list of all registered colormaps if called.
 
     You can set the colormap for an image, pcolor, scatter, etc,
-    either as a keyword argument::
+    using a keyword argument::
 
       imshow(X, cmap=cm.hot)
 
-    or post-hoc using the corresponding pylab interface function::
+    or using the :func:`set_cmap` function::
+
+      imshow(X)
+      pyplot.set_cmap('hot')
+      pyplot.set_cmap('jet')
+
+    In interactive mode, :func:`set_cmap` will update the colormap post-hoc, 
+    allowing you to see which one works best for your data.
+
+    All built-in colormaps can be reversed by appending ``_r``: For instance,
+    ``gray_r`` is the reverse of ``gray``.
+
+    There are several common color schemes used in visualization:
+
+    Sequential schemes
+      for unipolar data that progresses from low to high
+    Diverging schemes
+      for bipolar data that emphasizes positive or negative deviations from a 
+      central value
+    Cyclic schemes
+      meant for plotting values that wrap around at the 
+      endpoints, such as phase angle, wind direction, or time of day
+    Qualitative schemes
+      for nominal data that has no inherent ordering, where color is used 
+      only to distinguish categories
+
+    The base colormaps are (with the exception of `spectral`) derived from 
+    those of the same name provided with Matlab:
+
+      =========   =======================================================
+      Colormap    Description
+      =========   =======================================================
+      autumn      sequential linearly-increasing shades of red-orange-yellow
+      bone        sequential increasing black-white color map with 
+                  a tinge of blue, to emulate X-ray film
+      cool        linearly-decreasing shades of cyan-magenta
+      copper      sequential increasing shades of black-copper
+      flag        repetitive red-white-blue-black pattern (not cyclic at 
+                  endpoints)
+      gray        sequential linearly-increasing black-to-white
+                  grayscale
+      hot         sequential black-red-yellow-white, to emulate blackbody
+                  radiation from an object at increasing temperatures
+      hsv         cyclic red-yellow-green-cyan-blue-magenta-red, formed 
+                  by changing the hue component in the HSV color space
+      jet         a spectral map with dark endpoints, blue-cyan-yellow-red; 
+                  based on a fluid-jet simulation by NCSA [#]_
+      pink        sequential increasing pastel black-pink-white, meant
+                  for sepia tone colorization of photographs
+      prism       repetitive red-yellow-green-blue-purple-...-green pattern 
+                  (not cyclic at endpoints)
+      spring      linearly-increasing shades of magenta-yellow
+      summer      sequential linearly-increasing shades of green-yellow
+      winter      linearly-increasing shades of blue-green
+      spectral    black-purple-blue-green-yellow-red-white spectrum
+      =========   =======================================================
+
+    For the above list only, you can also set the colormap using the 
+    corresponding pylab shortcut interface function, similar to Matlab::
 
       imshow(X)
       hot()
       jet()
 
-    In interactive mode, this will update the colormap allowing you to
-    see which one works best for your data.
-    """
-    pass
+    The next set of palettes are from the `Yorick scientific visualisation
+    package <http://yorick.sourceforge.net/index.php>`_, an evolution of 
+    the GIST package, both by David H. Munro:
+
+      ============  =======================================================
+      Colormap      Description
+      ============  =======================================================
+      gist_earth    mapmaker's colors from dark blue deep ocean to green 
+                    lowlands to brown highlands to white mountains
+      gist_heat     sequential increasing black-red-orange-white, to emulate 
+                    blackbody radiation from an iron bar as it grows hotter
+      gist_ncar     pseudo-spectral black-blue-green-yellow-red-purple-white 
+                    colormap from National Center for Atmospheric 
+                    Research [#]_
+      gist_rainbow  runs through the colors in spectral order from red to 
+                    violet at full saturation (like *hsv* but not cyclic)
+      gist_stern    "Stern special" color table from Interactive Data 
+                    Language software
+      ============  =======================================================
+
+    The following colormaps are based on the `ColorBrewer 
+    <http://colorbrewer.org>`_ color specifications and designs developed by 
+    Cynthia Brewer:
+
+    ColorBrewer Diverging (luminance is highest at the midpoint, and 
+    decreases towards differently-colored endpoints):
+
+      ========  ===================================
+      Colormap  Description
+      ========  ===================================
+      BrBG      brown, white, blue-green
+      PiYG      pink, white, yellow-green
+      PRGn      purple, white, green
+      PuOr      orange, white, purple
+      RdBu      red, white, blue
+      RdGy      red, white, gray
+      RdYlBu    red, yellow, blue
+      RdYlGn    red, yellow, green
+      Spectral  red, orange, yellow, green, blue
+      ========  ===================================
+
+    ColorBrewer Sequential (luminance decreases monotonically):
+
+      ========  ====================================
+      Colormap  Description
+      ========  ====================================
+      Blues     white to dark blue
+      BuGn      white, light blue, dark green
+      BuPu      white, light blue, dark purple
+      GnBu      white, light green, dark blue
+      Greens    white to dark green
+      Greys     white to black (not linear)
+      Oranges   white, orange, dark brown
+      OrRd      white, orange, dark red
+      PuBu      white, light purple, dark blue
+      PuBuGn    white, light purple, dark green
+      PuRd      white, light purple, dark red
+      Purples   white to dark purple
+      RdPu      white, pink, dark purple
+      Reds      white to dark red
+      YlGn      light yellow, dark green
+      YlGnBu    light yellow, light green, dark blue
+      YlOrBr    light yellow, orange, dark brown
+      YlOrRd    light yellow, orange, dark red
+      ========  ====================================
+
+    ColorBrewer Qualitative:
+
+    (For plotting nominal data, :class:`ListedColormap` should be used, 
+    not :class:`LinearSegmentedColormap`.  Different sets of colors are 
+    recommended for different numbers of categories.  These continuous 
+    versions of the qualitative schemes may be removed or converted in the 
+    future.)
+
+    * Accent
+    * Dark2
+    * Paired
+    * Pastel1
+    * Pastel2
+    * Set1
+    * Set2
+    * Set3
+
+    Other miscellaneous schemes:
+
+      =========  =======================================================
+      Colormap   Description
+      =========  =======================================================
+      afmhot     sequential black-orange-yellow-white blackbody 
+                 spectrum, commonly used in atomic force microscopy
+      brg        blue-red-green 
+      bwr        diverging blue-white-red
+      coolwarm   diverging blue-gray-red, meant to avoid issues with 3D 
+                 shading, color blindness, and ordering of colors [#]_
+      CMRmap     "Default colormaps on color images often reproduce to 
+                 confusing grayscale images. The proposed colormap 
+                 maintains an aesthetically pleasing color image that 
+                 automatically reproduces to a monotonic grayscale with 
+                 discrete, quantifiable saturation levels." [#]_
+      cubehelix  Unlike most other color schemes cubehelix was designed 
+                 by D.A. Green to be monotonically increasing in terms 
+                 of perceived brightness. Also, when printed on a black 
+                 and white postscript printer, the scheme results in a 
+                 greyscale with monotonically increasing brightness. 
+                 This color scheme is named cubehelix because the r,g,b 
+                 values produced can be visualised as a squashed helix 
+                 around the diagonal in the r,g,b color cube.
+      gnuplot    gnuplot's traditional pm3d scheme 
+                 (black-blue-red-yellow)
+      gnuplot2   sequential color printable as gray 
+                 (black-blue-violet-yellow-white)
+      ocean      green-blue-white
+      rainbow    spectral purple-blue-green-yellow-orange-red colormap
+                 with diverging luminance
+      seismic    diverging blue-white-red
+      terrain    mapmaker's colors, blue-green-yellow-brown-white, 
+                 originally from IGOR Pro
+      =========  =======================================================
+
+    The following colormaps are redundant and may be removed in future 
+    versions.  It's recommended to use *gray* or *gray_r* instead, which 
+    produce identical output:
+
+      =========  =======================================================
+      Colormap   Description
+      =========  =======================================================
+      gist_gray  identical to *gray*
+      gist_yarg  identical to *gray_r*
+      binary     identical to *gray_r*
+      =========  =======================================================
+
+    .. rubric:: Footnotes
+
+    .. [#] Rainbow colormaps, ``jet`` in particular, are considered a poor 
+      choice for scientific visualization by many researchers: `Rainbow Color 
+      Map (Still) Considered Harmful 
+      <http://www.jwave.vt.edu/%7Erkriz/Projects/create_color_table/color_07.pdf>`_
+
+    .. [#] Resembles "BkBlAqGrYeOrReViWh200" from NCAR Command 
+      Language. See `Color Table Gallery 
+      <http://www.ncl.ucar.edu/Document/Graphics/color_table_gallery.shtml>`_
+
+    .. [#] See `Diverging Color Maps for Scientific Visualization 
+      <http://www.cs.unm.edu/~kmorel/documents/ColorMaps/>`_ by Kenneth 
+      Moreland.
+
+    .. [#] See `A Color Map for Effective Black-and-White Rendering of 
+      Color-Scale Images 
+      <http://www.mathworks.com/matlabcentral/fileexchange/2662-cmrmap-m>`_ 
+      by Carey Rappaport
+
+    """
+    return sorted(cm.cmap_d.keys())
 
 
 ## Plotting part 1: manually generated functions and wrappers ##

diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -3,9 +3,9 @@
 # This is a sample matplotlib configuration file - you can find a copy
 # of it on your system in
 # site-packages/matplotlib/mpl-data/matplotlibrc.  If you edit it
-# there, please note that it will be overridden in your next install.
+# there, please note that it will be overwritten in your next install.
 # If you want to keep a permanent local copy that will not be
-# over-written, place it in HOME/.matplotlib/matplotlibrc (unix/linux
+# overwritten, place it in HOME/.matplotlib/matplotlibrc (unix/linux
 # like systems) and C:\Documents and Settings\yourname\.matplotlib
 # (win32 systems).
 #
@@ -40,7 +40,7 @@ backend      : %(backend)s
 # "pyqt" and "pyside".  The "pyqt" setting has the side effect of
 # forcing the use of Version 2 API for QString and QVariant.
 
-# if you are runing pyplot inside a GUI and your backend choice
+# if you are running pyplot inside a GUI and your backend choice
 # conflicts, we will automatically try to find a compatible one for
 # you if backend_fallback is True
 #backend_fallback: True
@@ -220,8 +220,8 @@ backend      : %(backend)s
                                    # For example, use ',' as a decimal
                                    # separator in the fr_FR locale.
 #axes.unicode_minus  : True    # use unicode for the minus symbol
-                               # rather than hypen.  See
-                               # http://en.wikipedia.org/wiki/Plus_sign
+                               # rather than hyphen.  See
+                               # http://en.wikipedia.org/wiki/Plus_and_minus_signs#Character_codes
 #axes.color_cycle    : b, g, r, c, m, y, k  # color cycle for plot lines
                                             # as list of string colorspecs:
                                             # single letter, long name, or
@@ -265,7 +265,7 @@ backend      : %(backend)s
 #legend.numpoints     : 2      # the number of points in the legend line
 #legend.fontsize      : large
 #legend.pad           : 0.0    # deprecated; the fractional whitespace inside the legend border
-#legend.borderpad     : 0.5    # border whitspace in fontsize units
+#legend.borderpad     : 0.5    # border whitespace in fontsize units
 #legend.markerscale   : 1.0    # the relative size of legend markers vs. original
 # the following dimensions are in axes coords
 #legend.labelsep      : 0.010  # deprecated; the vertical space between the legend entries
@@ -288,7 +288,7 @@ backend      : %(backend)s
 #figure.facecolor : 0.75    # figure facecolor; 0.75 is scalar gray
 #figure.edgecolor : white   # figure edgecolor
 
-# The figure subplot parameters.  All dimensions are fraction of the
+# The figure subplot parameters.  All dimensions are a fraction of the
 # figure width or height
 #figure.subplot.left    : 0.125  # the left side of the subplots of the figure
 #figure.subplot.right   : 0.9    # the right side of the subplots of the figure