Improved docstrings in colors.py

efiring · efiring · commit 53d54e36d14b · 2008-11-18T21:37:25.000Z
svn path=/trunk/matplotlib/; revision=6413
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -1,9 +1,24 @@
 """
-A class for converting color arguments to RGB or RGBA
-
-This class instantiates a single instance colorConverter that is used
-to convert matlab color strings to RGB.  RGB is a tuple of float RGB
-values in the range 0-1.
+A module for converting numbers or color arguments to *RGB* or *RGBA*
+
+*RGB* and *RGBA* are sequences of, respectively, 3 or 4 floats in the
+range 0-1.
+
+This module includes functions and classes for color specification
+conversions, and for mapping numbers to colors in a 1-D array of
+colors called a colormap. Colormapping typically involves two steps:
+a data array is first mapped onto the range 0-1 using an instance
+of :class:`Normalize` or of a subclass; then this number in the 0-1
+range is mapped to a color using an instance of a subclass of
+:class:`Colormap`.  Two are provided here:
+:class:`LinearSegmentedColormap`, which is used to generate all
+the built-in colormap instances, but is also useful for making
+custom colormaps, and :class:`ListedColormap`, which is used for
+generating a custom colormap from a list of color specifications.
+
+The module also provides a single instance, *colorConverter*, of the
+:class:`ColorConverter` class providing methods for converting single
+color specifications or sequences of them to *RGB* or *RGBA*.
 
 Commands which take color arguments can use several formats to specify
 the colors.  For the basic builtin colors, you can use a single letter
@@ -193,6 +208,7 @@
         cnames[k] = v
 
 def is_color_like(c):
+    'Return *True* if *c* can be converted to *RGB*'
     try:
         colorConverter.to_rgb(c)
         return True
@@ -218,6 +234,15 @@ def hex2color(s):
     return tuple([int(n, 16)/255.0 for n in (s[1:3], s[3:5], s[5:7])])
 
 class ColorConverter:
+    """
+    Provides methods for converting color specifications to *RGB* or *RGBA*
+
+    Caching is used for more efficient conversion upon repeated calls
+    with the same argument.
+
+    Ordinarily only the single instance instantiated in this module,
+    *colorConverter*, is needed.
+    """
     colors = {
         'b' : (0.0, 0.0, 1.0),
         'g' : (0.0, 0.5, 0.0),
@@ -526,17 +551,47 @@ def is_gray(self):
 class LinearSegmentedColormap(Colormap):
     """Colormap objects based on lookup tables using linear segments.
 
-    The lookup transfer function is a simple linear function between
-    defined intensities. There is no limit to the number of segments
-    that may be defined. Though as the segment intervals start containing
-    fewer and fewer array locations, there will be inevitable quantization
-    errors
+    The lookup table is generated using linear interpolation for each
+    primary color, with the 0-1 domain divided into any number of
+    segments.
     """
     def __init__(self, name, segmentdata, N=256):
         """Create color map from linear mapping segments
 
         segmentdata argument is a dictionary with a red, green and blue
-        entries. Each entry should be a list of x, y0, y1 tuples.
+        entries. Each entry should be a list of *x*, *y0*, *y1* tuples,
+        forming rows in a table.
+
+        Example: suppose you want red to increase from 0 to 1 over
+        the bottom half, green to do the same over the middle half,
+        and blue over the top half.  Then you would use::
+
+            cdict = {'red':   [(0.0,  0.0, 0.0),
+                               (0.5,  1.0, 1.0),
+                               (1.0,  1.0, 1.0)],
+
+                     'green': [(0.0,  0.0, 0.0),
+                               (0.25, 0.0, 0.0),
+                               (0.75, 1.0, 1.0),
+                               (1.0,  1.0, 1.0)],
+
+                     'blue':  [(0.0,  0.0, 0.0),
+                               (0.5,  0.0, 0.0),
+                               (1.0,  1.0, 1.0)]}
+
+        Each row in the table for a given color is a sequence of
+        *x*, *y0*, *y1* tuples.  In each sequence, *x* must increase
+        monotonically from 0 to 1.  For any input value *z* falling
+        between *x[i]* and *x[i+1]*, the output value of a given color
+        will be linearly interpolated between *y1[i]* and *y0[i+1]*::
+
+            row i:   x  y0  y1
+                           /
+                          /
+            row i+1: x  y0  y1
+
+        Hence y0 in the first row and y1 in the last row are never used.
+
 
         .. seealso::
             :func:`makeMappingArray`
