Revision: 6413
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=6413&view=rev
Author: efiring
Date: 2008-11-18 21:37:25 +0000 (Tue, 18 Nov 2008)
Log Message:
-----------
Improved docstrings in colors.py
Modified Paths:
--------------
trunk/matplotlib/lib/matplotlib/colors.py
Modified: trunk/matplotlib/lib/matplotlib/colors.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/colors.py 2008-11-17 23:08:20 UTC (rev
6412)
+++ trunk/matplotlib/lib/matplotlib/colors.py 2008-11-18 21:37:25 UTC (rev
6413)
@@ -1,10 +1,25 @@
"""
-A class for converting color arguments to RGB or RGBA
+A module for converting numbers or 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.
+*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 @@
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,18 +551,48 @@
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`
"""
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Matplotlib-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/matplotlib-checkins
