From: <ef...@us...> - 2008-11-18 21:37:35
|
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. |